Package jline.api.infer

Class InferSmp

java.lang.Object
jline.api.infer.InferSmp
public final class InferSmp extends Object
Maximum-likelihood fit of a fully parametric semi-Markov multi-state model to right-censored sojourn data, under either of the two parameterizations of Asanjarani, Liquet and Nazarathy.

DATA. One row per observed sojourn: the process entered state from[k], stayed dur[k] > 0, and then moved to state to[k], or was still in from[k] when observation stopped, coded to[k] = -1 (right censoring). States are 0-based, 0..E-1, as the stages of an Environment. A history J0 -> J1 -> ... -> JN with sojourns tau_1..tau_N and censoring time U contributes the rows (J0,J1,tau_1), ..., (J_{N-1},J_N,tau_N) and, unless J_N is absorbing, (J_N, -1, U).

APPROACHES. "intensity" (default) fits the transition intensity functions a~_ij(t) (Approach II): each transition i->j is a latent clock with its own law and the likelihood splits into one two-state censored-data likelihood per transition (Eqs. 30-31), every sojourn out of i that did not end in j counting as censored for i->j. "sojourn" fits Approach I: the embedded chain p_ij and the law F_ij of a sojourn that ends in j, with likelihood (27); a censored sojourn in i contributes S_i(U) = sum_j p_ij S_ij(U), which couples the parameters of a state, so a state with censored rows is fitted jointly (p by a softmax) and one without in closed form for p. Covariates enter as a proportional-hazards factor exp(beta_ij' z) on a~_ij (Eq. 33) or on the sojourn hazard alpha_ij (Eq. 32), optionally masked per transition (the "+Select" models of Sec. 4).

The maximizer is a deterministic Nelder-Mead (the Lagarias et al. variant of fminsearch, restarted from its own optimum until it stops improving), the same in all four codebases; an exponential transition without covariates has its closed-form MLE. Standard errors are from the central-difference Hessian of the negative log-likelihood in the theta coordinates, NaN when it is not positive definite.

Port of MATLAB infer_smp.m, infer_smp_env.m, infer_smp_hazard.m and infer_smp_nelson_aalen.m.

Reference: A. Asanjarani, B. Liquet, Y. Nazarathy, Estimation of semi-Markov multi-state models: a comparison of the sojourn times and transition intensities approaches, arXiv:2005.14462 (2020).

  • Method Details

    • infer_smp

      public static InferSmp.Fit infer_smp(int[] from, int[] to, double[] dur)
      Fit with default options.

    • infer_smp

      public static InferSmp.Fit infer_smp(int[] from, int[] to, double[] dur, InferSmp.Options opt)

    • infer_smp_env

      public static Environment infer_smp_env(InferSmp.Fit fit, Model[] models, String[] names, String[] types, double[] z)
      The Environment of a fit, with models[e] the stage model of state e. An "intensity" fit becomes competing arcs (addTransition), each the fitted latent clock of its transition; a "sojourn" fit becomes kernel arcs (addKernelTransition) with the fitted embedded probability and conditional sojourn law. Either is solved by SolverENV method 'smp'.
      Parameters:
      fit - the fit
      models - one stage model per state
      names - stage names, or null for S1..SE
      types - stage types, or null for "stage"
      z - covariate vector at which to evaluate the proportional-hazards factors, or null for the baseline
      Returns:
      the environment

    • infer_smp_env

      public static Environment infer_smp_env(InferSmp.Fit fit, Model[] models, String[] names, String[] types, double[] z, String name)

    • infer_smp_hazard

      public static List<InferSmp.Hazard> infer_smp_hazard(InferSmp.Fit fit, double[] t, double[] z)
      Both hazard functions of every transition of a fit, on the ascending instants t > 0, whichever approach produced it (Asanjarani et al., Eqs. 11-15). They are related by a~_ij(t) = p_ij f_ij(t) / S_i(t), S_i the holding-time survival of state i. An "intensity" fit carries a~ (the hazard of the fitted clock) and A~ in closed form and obtains the CIF by the quadrature of Smp_stage_cif; alpha_ij then follows as a~_ij S_i / (p_ij - CIF_ij). A "sojourn" fit carries alpha (the hazard of the fitted F_ij) and the CIF in closed form; a~ follows from the relation above, and A~ is a midpoint sum on the grid [0, logspace(log10(T_max)-8, log10(T_max), 2001)] joined with linspace(0, T_max, 20001) and t, which resolves an integrable singularity at 0.
      Parameters:
      fit - the fit
      t - ascending, finite, positive instants
      z - covariate vector, or null for the baseline
      Returns:
      one entry per arc of the fit, in the same order

    • infer_smp_nelson_aalen

      public static List<InferSmp.NelsonAalen> infer_smp_nelson_aalen(int[] from, int[] to, double[] dur, int nstates)
      Nelson-Aalen estimate of the cumulative transition intensity A~_ij(t) of every observed transition, on the clock reset at each jump, from the sojourn data of infer_smp(int[], int[], double[]) (to = -1 for a censored sojourn). The risk set at t of transition i->j is the number of sojourns in i of duration at least t, so this is the nonparametric benchmark of the "intensity" approach (Asanjarani et al., Sec. 4).
      Parameters:
      nstates - E, or 0 for max(from, to) + 1