lod_lm {lodr}

Fitting Linear Models with Covariates Subject to a Limit of Detection (LOD)

Description

lod_lm is used to fit linear models while taking into account limits of detection for corresponding covariates. It carries out the method detailed in May et al. (2011) with regression coefficient standard errors calculated using bootstrap resampling.

Usage

lod_lm(data, frmla, lod=NULL, var_LOD=NULL, nSamples = 250,
fill_in_method="mean", convergenceCriterion = 0.001, boots = 25)

## S3 method for class 'lod_lm'
print(x, ...)

Arguments

data

a required data frame (or object coercible by as.data.frame to a data frame) containing the variables in the model. If not specified, a corresponding error is returned.

x

An object of class "lod_lm", usually, a result of a call to lod_lm

frmla

an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted. The details of model specification are given under 'Details'.

lod

a numeric vector (or object coercible by as.numeric) specifying the limit of detection for each covariates specified in var_LOD (in the same order as the covariates in var_LOD). Default is NULL, representing no covariates having limits of detection, which calls lm.

var_LOD

a character vector specifying which covariates in the model (frmla) are subject to limits of detection. Default is NULL, representing no covariates having limits of detection, which calls lm.

nSamples

an integer specifying the number of samples to generate for each subject with covariate values outside of their limits of detection. For more details, see May et al. (2011). The default is 250.

fill_in_method

a string specifying how values outside of the limits of detection should be handled when calculating residuals and fitted values. Default is "mean", which uses the mean covariate value. Another choice is "LOD" which uses the lower limit of detection.

convergenceCriterion

a number specifying the smallest difference between iterations required for the regression coefficient estimation process to complete. The default is 0.001.

boots

a number specifying the number of bootstrap resamples used for the standard error estimation process for the regression coefficient estimates. The default is 25.

...

further arguments passed to or from other methods.

Details

Models for lod_lm are specified the same as models for lm. A typical model as the form response ~ terms where response is the (numeric) response vector and terms is a series of terms separated by + which specifies a linear predictor for response. A formula has an implied intercept term.

In the dataset used with lod_lm, values outside of the limits of detection need to be denoted by the value of the lower limit of detection. Observations with values marked as missing by NA are removed by the model fit procedure as done with lm.

Value

lod_lm returns an object of class) "lod_lm" if arguments lod and var_LOD are not NULL, otherwise it returns class) "lm". The function summary prints a summary of the results in the same format as with an object of class) "lm". The generic accessor functions coef, fitted and residuals extract various useful features of the value returned by lod_lm.

An object of class) "lod_lm" is a list containing the following components:

coefficients

a named vector of regression coefficient estimates.

boot_SE

a named vector of regression coefficient estimate bootstrap standard error estimates.

fitted.values

the fitted mean values for subjects with covariates within their limits of detection.

rank

the numeric rank of the fitted linear model

residuals

the residuals, that is response minus fitted values, for subjects with covariates within their limits of detection.

df.residual

the residual degrees of freedom.

model

the model frame used.

call

the matched call.

terms

the terms object used.

Author(s)

Kevin Donovan, [e-mail].

Maintainer: Kevin Donovan <[e-mail]>

References

May RC, Ibrahim JG, Chu H (2011). “Maximum likelihood estimation in generalized linear models with multiple covariates subject to detection limits.” Statistics in medicine, 30(20), 2551–2561.

See Also

summary.lod_lm for summaries of the results from lod_lm

The generic functions coef, fitted and residuals.

Examples

library(lodr)
## Using example dataset provided in lodr package: lod_data_ex
## 3 covariates: x1, x2, x3 with x2 and x3 subject to a lower limit of
## detection of 0

## nSamples set to 100 for computational speed/illustration purposes only.  
## At least 250 is recommended.  Same for boots=0; results in NAs returned for standard errors

fit <- lod_lm(data=lod_data_ex, frmla=y~x1+x2+x3, lod=c(0,0),
                  var_LOD=c("x2", "x3"), nSamples=100, boots=0)
 summary(fit)