hlm: Fit the heteroscedastic linear model.
In mlysy/hlm: Inference for a Heteroscedastic Linear Model

Description Usage Arguments Details Value Note References See Also Examples

View source: R/hlm.R

Calculates the MLE of a heteroscedastic linear model (HLM) with possibly right-censored responses. See Details.

1 2	hlm(formula, data, subset, weights, na.action, control, model = TRUE, qr = TRUE, x = FALSE, y = FALSE, offset)

`formula`	An object of class `formula` (or one that can be coerced to that class). See Details.
`data`	An optional data frame, list or environment containing the variables in the model. If not found in `data`, the variables are taken from `environment(formula)`.
`subset`	An optional vector specifying a subset of observations to be used in the fitting process.
`weights`	Currently ignored.
`na.action`	A function which indicates what should happen when the data contain `NA`s. Same default behavior as in `stats::lm`.
`control`	List of parameters to control the fitting process. See Details.
`model, x, y, qr`	Logical values indicating which data elements should be returned in the output. These correspond to the response, the covariance matrices, the `model.frame`, and the QR decomposition of the hessian of the negative loglikelihood, respectively. See `stats::lm`.
`offset`	Currently ignored, as are `offset` terms in the formula.

The heteroscedastic linear model (HLM) is defined as

y_i | x_i, z_i ~ind N(x_i'β, exp(z_i'γ)),

where for each subject i, y_i is the response, and x_i \in R^p and z_i \in R^q are mean and variance covariate vectors, respectively.

The formula term is specified as e.g.,

1	y ~ x1 + x2 \| z1 + z2

where the vertical bar separates mean and variance components. If no bar is provided, an intercept variance term of the form y ~ x1 + x2 | 1 is assumed, corresponding to the usual linear model (but with a different parametrization).

Right censoring of observations is supported by specifying the response as a two-column matrix, where the first column is the response and the second column is a censoring status indicator with 0: right-censored and 1: uncensored.

Fitting the hlm model is done by blockwise coordinate ascent, alternatively maximing the mean parameters by weighted least-squares, and the variance parameters either via Fisher scoring or Iteratively Reweighted Least Squares. When there is right-censoring, these maximization steps are embedded within an Expectation-Conditional-Maximization algorithm.

An object of class hlm with the following elements:

coefficients: A list with elements beta and gamma containing the coefficient MLEs.
loglik: The loglikelihood at the MLE.
df.residual: The residual degrees of freedom.
iter: The number of iterations used in the fitting algorithm.
call: The matched call.
terms: A list with elements X and Z giving the terms object for mean and variance models.
y: If requested, the response used.
x: If requested, a list with elements X and Z giving the mean and variance model matrices uses.
model: If requested, the model.frame used.
na.action: (Where relevant) information returned by model.frame on the special handling of NAs.
qr: If requested, the QR decomposition of the observed Fisher information matrix of size (p+q) x (p+q).

Warning: At present hlm cannot handle pure LM or LVLM models. For datasets without censoring, please use the low-level functions lm_fit and lvlm_fit instead.

Wang, Y., You, T., and Lysy, M. "A heteroscedastic accelerated failure time model for survival analysis" (2019): https://arxiv.org/abs/1508.05137.

Current methods for hlm objects are: print, nobs, vcov, and summary.

summary(colond) # colon cancer dataset

# fit model without censoring (i.e., ignoring it)
M <- hlm(log(time) ~ . | rx, data = colond)
M # brief display
summary(M) # full summary
vcov(M) # variance estimate

# fit same model but with censoring
hlm(cbind(log(time), status) ~ . | rx, data = colond)