msSurv (version 1.2-2)

msSurv-class: Class "msSurv"

Description

The class "msSurv" contains nonparametric estimates for multistate models subject to right censoring and possibly left truncation by calling msSurv.

Objects from the Class

Objects can be created by calls of the form new("msSurv", ...). "msSurv" objects are also returned from function msSurv

Slots

tree:

Object of class "graphNEL". A graphNEL object with nodes corresponding to the states in the multistate model and the edges corresponding to the allowed transitions.

ns:

Object of class "numeric". The number of unique states in the multistate model.

et:

Object of class "numeric". The event times.

pos.trans:

Object of class "character". Possible transtitions between states.

nt.states:

Object of class "character". The non-terminal states in the multistate model.

dNs:

Object of class "array". A matrix containing the differential of the counting processes for the event times.

Ys:

Object of class "array". A matrix containing the at risk sets for the event times.

sum_dNs:

Object of class "array". A matrix containing the differential for the counting process for total transitions out of each state, at each event time.

dNs.K:

Object of class "array". A matrix containing the differential of the weighted counting process described in Datta and Satten (2001).

Ys.K:

Object of class "array". A matrix containing the weighted at risk sets described in Datta and Satten (2001).

sum_dNs.K:

Object of class "array". A matrix containing the differential of the weighted counting process for total transitions out of each state, at each event time.

ps:

Object of class "array". A matrix with state occupation probabilities for each state at each event time.

AJs:

Object of class "array". An array containing matrices of Aalen-Johansen estimates (transition probabilities) at each event time.

I.dA:

Object of class "array". A matrix containing the I+dA transition matrices for Aalen-Johansen computation.

cov.AJs:

Object of class "array". An array containing the variance-covariance matrices for transition probabilities at each event time.

var.sop:

Object of class "array". A matrix containing covariance estimates for the state occupation probabilities.

cov.dA:

Object of class "array". A matrix containing the covariance of dA matrices used for computation of cov(P(s,t)).

Fnorm:

Object of class "array". A matrix containing normalized state entry distributions. Note: "NA" is recorded for Fnorm at the initial state(s) (node(s)).

Fsub:

Object of class "array". A matrix containing unnormalized (subdistribution) state entry distributions. Note: "NA" is recorded for Fsub at the initial state(s) (node(s)).

Gnorm:

Object of class "array". A matrix containing normalized state exit distributions. Note: "NA" is recorded for Gnorm at the terminal state(s) (node(s)).

Gsub:

Object of class "array". A matrix containing unnormalized (subdistribution) state exit distributions. Note: "NA" is recorded for Gsub at the terminal state(s) (node(s)).

Fnorm.var:

Object of class "array or NULL". A matrix containing variance estimates for the normalized state entry distributions. Will be NULL if the user does not specify bs=TRUE.

Fsub.var:

Object of class "array or NULL". A matrix containing variance estimates for the unnormalized (subdistribution) state entry distributions. Will be NULL if the user does not specify bs=TRUE.

Gnorm.var:

Object of class "array or NULL". A matrix containing variance estimates for the normalized state exit distributions. Will be NULL if the user does not specify bs=TRUE.

Gsub.var:

Object of class "array or NULL". A matrix containing variance estimates for the unnormalized (subdistribution) state exit distributions. Will be NULL if the user does not specify bs=TRUE.

Methods

ACCESSOR FUNCTIONS

signature(object = "msSurv"): Accessor functions are defined for each of the slots in an msSurv object, e.g. tree, ns, et, etc. The accessor functions all have the same name as the corresponding slot name, and all have the same signature.

print

signature(x = "msSurv"): Print method for "msSurv" objects.

show

signature(object = "msSurv"): Show method for "msSurv" objects.

summary

signature(object = "msSurv"): Summary function for "msSurv" objects. Additional arguements:

digits=3

The number of significant digits to use for estimates. Defalt is 3.

all=FALSE

Logical argument to determine whether summary information should be displayed for all event times or only for the key percentile time points (IQR). Default is FALSE where all=FALSE corresponds to only the IQR of event times being displayed in the summary output.

times=NULL

Numeric vector of time-points at which to present summary information. Overrides all if supplied.

ci.fun="linear"

Transformation applied to confidence intervals. Possible choices are "linear", "log", "log-log", and "cloglog". Default is "linear".

ci.level=0.95

Confidence level. Default is 0.95.

stateocc=TRUE

Logical argument specifying whether state occupation probabilities should be displayed. Default is TRUE.

trans.pr=TRUE

Logical argument specifying whether state transition probabilities should be displayed. Default is TRUE.

dist=TRUE

Logical argument specifying whether state entry / exit distributions should be displayed. Default is TRUE.

DS=FALSE

Logical argument specifying whether Datta-Satten weighted counting processes. Default is FALSE.

plot

signature(x = "msSurv", y = "missing"): Plotting method for "msSurv" objects. Additional arguments:

states="ALL"

States in the multistate model to be plotted. Default is all states in the system. User may specify individual states or multiple states to plot.

trans="ALL"

Transitions in the multistate model to be plotted. Default is all transitions. Transitions should be entered with a space between the two states, e.g.: "1 1".

CI=TRUE

A logical argument to specify whether pointwise confidence intervals should be plotted. If the user specifies CI=FALSE, only the estimates are plotted. If the user specifies CI=TRUE, plots of each estimate and its corresponding confidence intervals are created (if appropriate variances are available). The default is TRUE.

ci.level=0.95

Confidence level. Default is 0.95.

ci.trans="linear"

Transformation applied to confidence intervals. Possible choices are "linear", "log", "log-log", and "cloglog". Default is "linear".

plot.type="stateocc"

Determines the type of estimate to be plotted. User may specify "transprob" for transition probability plots, "stateocc" for state occupation probability plots, "entry.norm" / "entry.sub" for normalized / unnormalized state entry time distributions, or "exit.norm" / "exit.sub" for normalized / unnormalized state exit time distributions. "stateocc" is the default.

...

Further arguments passed to xyplot

References

Nicole Ferguson, Somnath Datta, Guy Brock (2012). msSurv: An R Package for Nonparametric Estimation of Multistate Models. Journal of Statistical Software, 50(14), 1-24. URL http://www.jstatsoft.org/v50/i14/.

Andersen, P.K., Borgan, O., Gill, R.D. and Keiding, N. (1993). Statistical models based on counting processes. Springer Series in Statistics. New York, NY: Springer.

Datta, S. and Satten G.A. (2001). Validity of the Aalen-Johansen estimators of stage occupation probabilities and Nelson-Aalen estimators of integrated transition hazards for non-Markov models. Statistics and Probability Letters, 55(4): 403-411.

Datta S, Satten GA (2002). Estimation of Integrated Transition Hazards and Stage Occupation Probabilities for Non-Markov Systems under Dependent Censoring. Biometrics, 58(4), 792-802.

See Also

For a description of the function 'msSurv' see msSurv.

Examples

## 3-state illness-death multistate model (no left-truncation)

## Row data for 3 individuals
## Data in the form "id", "start", "stop", "start.stage", "end.stage"
p1  <- c(1,0,0.21,1,3)
p2  <- c(2,0,0.799,1,2)
p22 <- c(2,0.799,1.577,2,3)
p3  <- c(3,0,0.199,1,0)

## Combining data into a matrix
ex1 <- rbind(p1,p2,p22,p3)
colnames(ex1) <- c("id", "start", "stop", "start.stage", "end.stage")
ex1 <- data.frame(id=ex1[,1], start=ex1[,2], stop=ex1[,3],
                  start.stage=ex1[,4], end.stage=ex1[,5])


## Inputting nodes & edges of the tree structure
Nodes <- c("1","2","3") # states in MSM
Edges <- list("1"=list(edges=c("2","3")),"2"=list(edges=c("3")),
           "3"=list(edges=NULL)) ## allowed transitions between states
                                 ## edges=NULL implies terminal node

## Specifying tree
treeobj <- new("graphNEL", nodes=Nodes, edgeL=Edges,
                edgemode="directed")

ans1 <- msSurv(ex1, treeobj)

print(ans1)  ## same as 'show(ans1)'

summary(ans1) ## prints IQR for ans1
summary(ans1, all=TRUE) ## prints all event times for ans1

## prints only state occupation probability info for all event times
summary(ans1, all=TRUE, trans.pr=FALSE, dist=FALSE)

plot(ans1) ## plots state occupation probability
plot(ans1, states="1")
plot(ans1, states=c("1", "2"))
plot(ans1, plot.type="transprob") ## plots for transition probability
plot(ans1, plot.type="transprob", trans=c("1 2", "1 3"))