reda (version 0.3.1)

mcf: Mean Cumulative Function (MCF)

Description

An S4 class generic function that estimates mean cumulative function (MCF) from a fitted model or computing the sample nonparametric MCF (also called Nelson-Aalen estimator) from data.

Usage

mcf(object, ...)
# S4 method for formula
mcf(object, data, subset, na.action,
    variance = c("Poisson", "LawlessNadeau"), logConfInt = TRUE,
    level = 0.95, ...)
# S4 method for rateReg
mcf(object, newdata, groupName, groupLevels, level = 0.95,
    na.action, control = list(), ...)

Arguments

object

An object used to dispatch a method.

...

Other arguments for future usage.

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), usually the environment from which the function is called.

subset

An optional vector specifying a subset of observations to be used in the fitting process.

na.action

A function that indicates what should the procedure do if the data contains NAs. The default is set by the na.action setting of options. The "factory-fresh" default is na.omit. Other possible values inlcude na.fail, na.exclude, and na.pass. help(na.fail) for details.

variance

An optional character specifying the variance estimator. The available options are "Poisson" (default) for Poisson process method, and "LawlessNadeau" for Lawless and Nadeau (1995) method. (A simple example is available at Reliawiki, 2012.) Partial matching on the names is allowed.

logConfInt

An optional logical value. If TRUE (default), the confidence interval of given level will be constucted based on the normality of logarithm of the MCF function. (Otherwise, the confidence interval will be constructed based on the normality of MCF function.)

level

An optional numeric value indicating the confidence level required. The default value is 0.95.

newdata

An optional data frame. If specified, the data frame should have the same column names as the covariate names appearing in the formula of original fitting.

groupName

An optional length-one charactor vector to specify the name for grouping each unique row in newdata, such as "gender" for "male" and "female". The default value is "group".

groupLevels

An optional charactor vector to specify the levels for each unique row in newdata, such as "treatment" and "control". The default values are capital letters starting from "A".

control

An optional list to specify the time grid where the MCF is estimated. The availble elements of the control list include grid, length.out, from and to. The time grid can be directly specified via element grid. A dense time grid is suggested. Element length.out represents the length of grid points. The dafault value is 1,000. Element from means the starting point of grid with default 0. Element to represnts the endpoint of grid with the right boundary knot as default. When grid is missing, the grid will be generated by seq (from package base) with arguments from, to and length.out.

Value

sampleMcf-class or rateRegMcf-class object. Their slots include

• level: Confidence level specified.

• MCF: Mean cumulative function at each time point.

• multiGroup: A logical value indicating whether MCF is estimated for different specified group.

• newdata: Given dataset used to estimate MCF.

For the meaning of other slots, see rateReg.

Methods (by class)

• formula: Sample MCF from data.

• rateReg: Estimated MCF from a fitted model.

Details

For formula object with Survr object as response, the covariate specified at the right hand side of the formula should be either 1 or any "linear" conbination of factor variable in the data. The former computes the overall sample MCF. The latter computes the sample MCF for each level of the combination of the factor variable(s) specified, respectively. The sample MCF is also called Nelson-Aalen nonparametric estimator (Nelson, 2003) and computed on each time point from sample data. The point estimate of sample MCF at each time point does not assume any particular underlying model. The variance estimates at each time point is given by Poisson process method (by default) or Lawless and Nadeau method (LawLess and Nadeau, 1995). The approximate confidence intervals are provided as well, which are constructed based on the asymptotic normality of logarithm of MCF (by default) or MCF itself directly.

For rateReg-class object, mcf estimates the baseline MCF and its confidence interval at each time grid if argument newdata is not specified. Otherwise, mcf estimates MCF and its confidence interval for the given newdata based on Delta-method.

References

Nelson, W. B. (2003). Recurrent events data analysis for product repairs, disease recurrences, and other applications (Vol. 10). SIAM.

Lawless, J. F. and Nadeau, C. (1995). Some Simple Robust Methods for the Analysis of Recurrent Events. Technometrics, 37, 158--168.

ReliaWiki. (2012, March 19). Recurrent Event Data Analysis. Retrieved November 23, 2015, from http://reliawiki.org/index.php/Recurrent_Event_Data_Analysis

See Also

rateReg for model fitting; plot-method for plotting MCF.

Examples

# NOT RUN {
library(reda)

### Example 1. valve-seat data
valveMcf <- mcf(Survr(ID, Days, No.) ~ 1, data = valveSeats)

## plot sample MCF
plot(valveMcf, conf.int = TRUE, mark.time = TRUE) + ggplot2::xlab("Days")

### Example 2. sample simulated data
simuMcf <- mcf(Survr(ID, time, event) ~ group + gender,
               data = simuDat, ID %in% 1 : 50, logConfInt = FALSE)

## create customized levels in legend
levs <- with(simuDat, expand.grid(levels(group), levels(gender)))
levs <- do.call(paste, c(as.list(levs), sep = " & "))

## plot sample MCF
plot(simuMcf, conf.int = TRUE, lty = 1 : 4,
     legendName = "Treatment & Gender", legendLevels = levs)

## For estimated MCF from a fitted model,
## see examples given in function rateReg.
# }