expected_hitting_time: Compute the estimated hitting time for a state of a...

In nhm: Non-Homogeneous Markov and Hidden Markov Multistate Models

Compute the estimated hitting time for a state of a progressive multi-state model.

Description

Uses the estimated state occupation probabilities from a fitted multi-state model using nhm to calculate the expected time of entry into a given state, conditional on reaching that state.

Usage

expected_hitting_time(model, state, covvalue=NULL, tstart=0, tmax=NULL,
initp = NULL, npt = 500,  ltrunc = NULL, rtol = 1e-06,  atol = 1e-06, ci = TRUE, 
sim = FALSE, mode = "main", B = 1000, coverage = 0.95)

Arguments

model	Fitted model object produced using nhm.
state	The state of interest for the hitting time.
covvalue	Vector of covariate vectors (should be given in the order specified in the covariate option in nhm). If omitted the function will use the mean values of the covariates.
tstart	Initial time from which to measure the hitting time and calculate initial state probabilities. Defaults to 0 if omitted.
tmax	Maximum time to integrate over to estimate the mean hitting time. The expected hitting time is effectively conditional on reaching the state before tmax. Defaults to the maximum observed follow-up time in the data.
initp	optional vector of initial state occupation probabilities. If NULL then will use the estimates from the model. If original model was left-truncated will assume probabilities at tstart correspond to those implied by the left-truncation model. If ltrunc supplied will similarly calculate based on left-truncation from the value of t0 supplied. If model does not include misclassification, will assume entry in state 1.
npt	Number of points over which to evaluate state occupation probabilities in order to numerically approximate the integrals via a trapezium rule.
ltrunc	Optional list containing ltruncation_time and ltruncation_states. If supplied will replace the values in the original model fit object.
rtol	Relative tolerance parameter to be used by lsoda when solving the differential equations
atol	Absolute tolerance parameter to be used by lsoda when solving the differential equations
ci	Logical for whether confidence intervals should be calculated for the quantities.
sim	Logical for whether simulation-based (parametric bootstrap) confidence intervals should be used (TRUE) or delta method-based intervals (FALSE).
mode	Argument for internal use to faciliate parametric bootstrapping: default "main" ensures standard errors and calculated, if mode="boot" then standard errors are not calculated.
B	Integer specifying the number of bootstrap replicates to perform if sim=TRUE. Defaults to 1000.
coverage	Nominal coverage proportion required for confidence intervals. Defaults to 0.95 implying two-sided 95% confidence intervals.

Details

Uses the estimated state occupation probabilities and transition intensities from a fitted multi-state model using nhm to calculate the expected time of entry into a particular state, conditional on entry.

The method assumes the state of interest can only be entered once and will give incorrect results otherwise.

The state occupation probabilities are calculated in the same way as in state_occupation_probability.nhm. If the estimated initp has a non-zero probability of being in the hitting state (or states only reachable via that state), then the function computes the expected hitting time from tstart conditional on not having not yet reached that state.

Value

Returns a list with the following components:

est	Estimated expected hitting time.
var_est	Variance of the expected hitting time estimate.
var_lest	Variance of the log of the expected hitting time.
est_low	Lower limit of symmetric confidence interval
est_high	Upper limit of symmetric confidence interval
est_low2	Lower limit of confidence interval based on a log-transformation.
est_high2	Upper limit of confidence interval based on a log-transformation.
est0	Estimated unconditional probability of reaching the state.
var_est0	Variance of the estimate of the unconditional probability of reaching the state.
initp	Value of the initial probability vector at time tstart calculated from the model.

Author(s)

Andrew Titman [e-mail]

See Also

state_occupation_probability.nhm, expected_hitting_time

nhm documentation built on Sept. 1, 2025, 1:08 a.m.