repolr (version 3.4)

repolr-package: Repeated Measures Proportional Odds Logistic Regression using GEE

Description

The package allows regression models to be fitted to repeated ordinal scores, for the proportional odds model, using a generalized estimating equation (GEE) methodology. The algorithm estimates the correlation parameter by minimizing the generalized variance of the regression parameters at each step of the fitting algorithm. Parameter estimation is available for the uniform and first-order autoregressive correlation models, for data potentially recorded at irregularly spaced time intervals. A test for the proportional odds assumption is available, as is an option to fit a polynomial model to the the cut-point parameters.

Usage

repolr(formula, subjects, data, times, categories, corr.mod = "independence", alpha = 0.5, po.test = FALSE, fixed = FALSE, poly = NULL, space = NULL, diffmeth = "analytic", fit.opt = rep(NA, 5))

Arguments

formula
a formula, as for other regression models.
subjects
a character string specifying the name of the subject variable.
data
a dataframe in which to interpret the variables occurring in the formula.
times
a vector of times which occur within subject clusters; e.g. for four evenly spaced times c(1, 2, 3, 4).
categories
a numeric variable indicating the number of ordinal score categories.
corr.mod
a character string specifying the correlation structure. The following are permitted: “ar1”, “uniform” and “independence”.
alpha
an initial value for the correlation parameter.
po.test
a logical variable; if true a score test for proportional odds is reported.
fixed
a logical variable; if true the correlation is fixed at the initial value (alpha) during model fitting.
poly
a numeric variable indicating the order of the polynomial contrasts used for the cut-point model.
space
a vector indicating the category spacing when fitting the polynomial model; can generally be set to 1:categories
diffmeth
a character string specifying the method used for estimation of alpha. The folowing are available:“analytic” and “numeric
fit.opt
a vector of options to control the behaviour of the fitting algorithm.

Value

The function summary.repolr is used to obtain and print a summary of the fitted model.The fitted model is an object of class “repolr” and has the following values:
poly.mod
polynomial model for cut points: a list with elements poly, polycuts and space.
y
the response variable.
linear.predictors
a vector of linear predictors.
fitted.values
a vector of the fitted values.
coefficients
a named vector of regression coefficients.
robust.var
the robust (sandwich) variance matrix.
naive.var
the naive variance matrix.
alpha
an estimate of the correlation parameter.
convergence
a logical variable to reported if convergence was achieved.
iter
the number of iterations.
grad1
first derivative of generalized variance at convergence.
grad2
second derivative of generalized variance at convergence.
crit
convergence criterion.
po.test
results of po test: a list with elements po.stat, po.df and po.chi.

Details

The repolr function fits models for repeated ordinal scores using GEE methodology.

The user is required to specify, as a minimum: (i) a data set name (data), (ii) a model formula (formula), (iii) a cluster identification variable (subjects), (iv) a time variable (time) and (v) the number of categories used for the response variable (categories).

The data may contain records with missing data for either the response variable or the explanatory variables. The response variable must have at least three ordered categories (K greater than or equal to 3) and, as K-1 cut-point parameters are estimated, an additional intercept term can not be explicitly included in the model formula. A subject variable, which takes integer values from 1 to N with no missing values allowed, indicates the data clusters (patients or experimental units) and a time variable indicates the within cluster ordering; times must be ordered integers starting from one and spaced to indicate the relative distance between successive times. For instance, four observations at equally spaced times would be entered as 1, 2, 3 and 4, whereas if the first two observations were separated by half the time interval of the other observations then coding would be 1, 2, 4 and 6. The data must be pre-sorted by time clusters within each subject, and complete, i.e. where data is missing for a particular time it must be indicated as such. the datasets provided with this package provide exemplars of the required data formatting; e.g. HHSpain and QoL.

The available options for the correlation model (corstr) are AR1, uniform, fixed and independence, with default setting independence.

Additionally there are a number of other algorithm related options.

The algorithm is generally robust to the initial value for alpha (default setting = 0.5), where estimation is rerquired, however a starting value for alpha can be set. If required the correlation parameter, set via alpha, can be fixed throughout model fitting, and not updated, by setting the option fixed to TRUE.

The partial derivatives of the log of the determinant of the robust variance matrix (generalized variance), with respect to alpha, can either be determined analytically (“analytic” setting for diffmeth) or numerically by finite differencing (“numeric” setting for diffmeth). The latter method is often quicker for complex regression models, or if K is large.

Function poly, specifies the order of fitted orthogonal polynomial contrasts for the cut-point parameters; the default setting for repolr is to fit the complete set of cut-point parameters. Fitting polynomial contrasts can be particularly useful for long ordinal scores, where K is large, or where a particular form for the cut-point parameters is preferred; e.g. increasing uniformly at the extremes of the score scale. The order of the polynomial must be an integer less than K-1. The function requires one additional argument, space, that indicates the spacing between categories. This is normally set to 1:categories when all categories are observed, but can be modified to provide more realsitic models if for instance some categories are not observed.

The proportional odds assumption can be tested, using a score test, by setting the option po.test to TRUE.

The fit.opt argument provides control of the fitting algorithm; the defaults are

c(cmaxit = 10, omaxit = 5, ctol = 0.001, otol = 0.00001, h = 0.01).

These control the maximum number of iterations for updating estimates of alpha, the maximum number of iterations for updating the regression parameters within each of the updating steps for alpha, the convergence tolerances for estimation of alpha and the regression parameters, and the interval h for finite differencing, if the “numeric” option is selected.

Model fitting is implemented via a suite of of functions developed using RcppArmadillo (Rcpp) that construct correlations between derived binary variables at each time-point (smat) and between time-points (cmat). Complete (sparse) model covariance matrices are constructed using hgmat and alphpow, with model parameter estimation implemented in ordgee, using current estimates of the inverse of the correlation matrix from icormat. Function upalpha provides updates of correlation parameter estimates, and potest implements the test of proportional odds. These functions are not documented in detail here as they are primarily for internal use within repolr. There use outside of this setting is not recommended.

References

Parsons NR, Costa ML, Achten J, Stallard N. Repeated measures proportional odds logistic regression analysis of ordinal score data in the statistical software package R. Computational Statistics and Data Analysis 2009; 53:632-641.

Parsons NR, Edmondson RN, Gilmour SG. A generalized estimating equation method for fitting autocorrelated ordinal score data with an application in horticultural research. Journal of the Royal Statistical Society C 2006; 55:507-524.

Stiger TR, Barnhart HX, Williamson JM. Testing proportionality in the proportional odds model fitted with GEE. Statistics in Medicine 1999; 18:1419-1433.

Parsons NR. Proportional-odds models for repeated composite and long ordinal outcome scales. Statistics in Medicine 2013; 32:3181-3191.

See Also

QIC, polycuts, work.corr

Examples


data(HHSpain)
mod.0 <- repolr(HHSpain~Sex*Time, data=HHSpain, categories=4, subjects="Patient",
            times=c(1,2,5), corr.mod="uniform", alpha=0.5)
summary(mod.0)
summary(update(mod.0, diffmeth = "numeric"))
summary(update(mod.0, fixed = TRUE, alpha =0.5))