Package {modMStates}

Fit a continuous-time Markov multi-state model to panel data

Description

Fits the continuous-time Markov model implied by one of the seven built-in structures, or by a user-supplied generator, by maximum likelihood, and returns all primary inferential summaries in a single object. Likelihood evaluation is delegated to msm.

Usage

fit_msm(data, process = NULL, state = "state", subject = "subject",
  time = "time", t = NULL, Q = NULL, deathexact = NULL,
  inits = c("crude", "user"), ci = c("normal", "none"), ...)

fit.msm(...)

Arguments

Details

Mean sojourn times are per visit to a state, not total time occupied. Where a state can be re-entered, total occupancy exceeds the reported sojourn time by a factor equal to the expected number of visits.

State coding, duplicate visit times and observed transitions are validated against the assumed structure before the optimiser is called, and the optimiser's own convergence code is reported rather than inferred from the absence of an error.

The objective minimised by msm grows with the number of observed intervals and can overflow during the search in large samples, so that a well identified model fails with a numerical overflow. When that happens the fit is repeated with the objective rescaled, which leaves the maximum unchanged; a warning is issued and rescaled in the returned object records it. The rescaling is applied only after an unscaled attempt has failed, so a fit that succeeds without it is identical to the equivalent hand-written msm() call.

fit.msm is a deprecated alias: the name is read by S3 dispatch as the msm method of a generic called fit, and msm::msm returns objects of class msm.

Value

An object of class "modMStates_fit" with elements qmatrix (estimates, se, ci.lower, ci.upper), sojourn, pmatrix, counts, converged, convergence_code, rescaled, loglik, npar, n_subjects, n_observations, process, horizon and fit, the underlying msm object.

References

Jackson CH (2011). Multi-state models for panel data: the msm package for R. Journal of Statistical Software 38(8), 1-29.

Kalbfleisch JD, Lawless JF (1985). The analysis of panel data under a Markov assumption. Journal of the American Statistical Association 80(392), 863-871.

See Also

sim_mspdata, ms_montecarlo

Examples

dat <- sim_mspdata("illness_death_3state", n = 200, t = 10)
fit <- fit_msm(dat, "illness_death_3state", t = 5)
fit
fit$counts

Generator and permitted-transition matrices

Description

Returns the structurally valid infinitesimal generator for a built-in structure, with the reference intensities used in the package documentation, or the indicator matrix of permitted transitions.

Usage

ms_generator(process, rates = NULL)

ms_allowed(process)

Arguments

Value

ms_generator returns a square generator matrix with zero row sums. ms_allowed returns the corresponding matrix of zeros and ones.

Examples

ms_generator("illness_death_3state")
ms_allowed("competing_risks")
ms_generator("two_state", rates = 0.35)

Monte Carlo evaluation with Monte Carlo standard errors

Description

Repeatedly simulates panel data from a known generator, fits the model, and summarises finite-sample performance. Every summary carries its Monte Carlo standard error, so that differences smaller than the simulation noise are not read as findings, and convergence is taken from the optimiser's code rather than from the absence of an error.

Usage

ms_montecarlo(process, n = c(100, 300, 500), B = 1000, t = 10,
  Q = NULL, truth = NULL, horizon = 5, sim_args = list(),
  seed = NULL, verbose = TRUE)

Arguments

Value

A data frame with one row per parameter and sample size holding the truth, the mean estimate, bias, relative bias, empirical standard error, RMSE and coverage, each with its Monte Carlo standard error, together with the non-convergence rate and the number of converged replicates.

See Also

fit_msm

Examples

ms_montecarlo("two_state", n = 100, B = 25, seed = 1)

Theoretical state occupation probabilities

Description

Row from of the matrix exponential of Q t at each requested time. Provided so that simulated data can be checked against the process they are supposed to come from.

Usage

ms_occupancy(Q = NULL, times, process = NULL, from = 1L)

Arguments

Value

A matrix with one row per time and one column per state.

Examples

ms_occupancy(process = "illness_death_3state", times = 0:5)

Built-in process structures

Description

The seven canonical multi-state process structures supported by the package: two-state failure, recurrent event, three-state illness-death, four-state illness-death, reversible illness-death, competing risks and complex hybrid.

Usage

ms_structures()

ms_states(process)

Arguments

Value

ms_structures returns a character vector of the seven structure names. ms_states returns the clinical state labels for one structure.

Examples

ms_structures()
ms_states("complex_hybrid")

Validate a generator matrix

Description

Checks that a user-supplied generator is square, numeric, finite and has non-negative off-diagonal elements, repairs the diagonal, and reports states that cannot be reached from state one.

Usage

ms_validate_Q(Q, strict = FALSE)

Arguments

Value

The validated generator, invisibly, with the diagonal set to minus the row sum of the off-diagonal elements.

Examples

ms_validate_Q(rbind(c(0, 0.2, 0.1), c(0, 0, 0.4), c(0, 0, 0)))

Print and summary methods for a fitted multi-state model

Description

Display methods for the object returned by fit_msm.

Usage

## S3 method for class 'modMStates_fit'
print(x, digits = 4, ...)

## S3 method for class 'modMStates_fit'
summary(object, ...)

Arguments

Value

print returns its argument invisibly and is called for the side effect of printing the fitted transition intensities with their confidence intervals and observed transition counts, the mean sojourn times, the transition probability matrix at the chosen horizon, and the optimiser's convergence status. State pairs with fewer than ten observed transitions are flagged. summary returns an object of class "summary.modMStates_fit", whose print method additionally shows the full matrix of observed transition counts.

See Also

fit_msm

Examples

dat <- sim_mspdata("illness_death_3state", n = 100, t = 10)
fit <- fit_msm(dat, "illness_death_3state", t = 5)
print(fit)
summary(fit)

Simulate panel multi-state data

Description

Generates exact continuous-time trajectories under a built-in or user-supplied generator and records the occupied state at a set of observation times, producing a panel dataset in long format. sim_semimarkov is the Weibull-sojourn wrapper used to assess sensitivity to the Markov assumption. sim.mspdata is a deprecated alias.

Usage

sim_mspdata(process = NULL, n = 100L, t = 10, Q = NULL,
  schedule = c("regular", "random"), by = 1, visit_rate = 1.2,
  p_miss = 0, start_state = 1L, exact_absorption = FALSE,
  sojourn = c("exponential", "weibull"), shape = 1)

sim_semimarkov(process = NULL, n = 100L, t = 10, shape = 1, Q = NULL,
  schedule = c("regular", "random"), by = 1, visit_rate = 1.2,
  p_miss = 0, start_state = 1L)

sim.mspdata(...)

Arguments

Details

Trajectory generation and panel construction are kept separate: the state recorded at observation time u is the destination of the last jump at or before u. Discretising the process directly onto the observation grid shifts the implied holding-time distribution by up to one inter-visit interval and biases every leaving rate.

Value

A data frame with columns subject, time and state, one row per subject-visit, with the generating generator attached as attribute "Q".

See Also

fit_msm, ms_occupancy

Examples

dat <- sim_mspdata("illness_death_3state", n = 50, t = 10)
head(dat)

irr <- sim_mspdata("illness_death_3state", n = 50, t = 10,
                   schedule = "random", visit_rate = 1.2, p_miss = 0.2)
range(table(irr$subject))