Fit an rms Markov Model

orm_markov() fits a model using rms::orm() and stores the data needed by subsequent SOP and inference functions. It uses x = TRUE and y = TRUE by default, rejects offsets, stores separate likelihood, refit, and designated-start profile data on the returned model, and computes cluster-robust standard errors automatically when id_var is supplied.

Usage

orm_markov(
  formula,
  data,
  ...,
  id_var = NULL,
  type = c("HC0", "HC1"),
  cadjust = NULL,
  time_var = "time",
  first_followup_time = NULL,
  x = TRUE,
  y = TRUE
)

Arguments

formula

A model formula specifying the ordinal response and predictor terms. Offsets are not supported.

data

data frame to use. Default is the current frame.

...

arguments that are passed to orm.fit, or from print, to prModFit. Ignored for Quantile. One of the most important arguments is family.

id_var

Optional character scalar naming the patient or cluster ID column in data. When supplied, the returned object receives the package-owned patient-cluster sandwich covariance using this column. When omitted, the fit is returned without cluster-robust covariance and a warning is issued.

type

Character scalar selecting the empirical sandwich correction. "HC0" applies no observation degrees-of-freedom correction. "HC1" multiplies the sandwich meat by \((m - 1) / (m - p)\), where \(m\) is the number of positive-weight fitted likelihood rows and \(p\) is the complete raw coefficient count.

cadjust

Logical. Apply the finite-cluster correction \(n / (n - 1)\), where \(n\) is the number of represented patient clusters? NULL (the default) resolves to TRUE when id_var is supplied. This correction is independent of type, so selecting HC1 with cadjust = TRUE applies both factors.

time_var

Character scalar naming the modeled time column used to identify the designated starting-profile row.

first_followup_time

First scheduled post-baseline outcome time used to select the starting-profile row. For numeric time, NULL uses 1. Numeric schedules may not contain values below 1, and an explicit value must be the earliest observed time. Factor and character time require an explicit matching value.

x

causes the expanded design matrix (with missings excluded) to be returned under the name x. For print, an object created by orm.

y

causes the response variable (with missings excluded) to be returned under the name y.

Value

A fitted orm object. If id_var is supplied, $var contains the package-owned robust covariance and the object records its cluster, correction, bread, weighting, and covariance-integrity metadata.

Details

Starting profiles are retained before response-driven model-frame omission. Every fitted patient must have exactly one complete profile at the cohort-wide first_followup_time, including ID, model predictors, time, and the previous state; the transition response on that row may be missing. A patient is included only when at least one usable likelihood transition is fitted somewhere. Patients with no fitted transition are excluded, and a fitted patient without a complete designated profile is an error. Later likelihood rows are not substituted for that profile.

The ORM sandwich is computed inside mostr from analytic likelihood-row scores on the complete threshold-and-slope coefficient scale. Fitted case weights multiply those row scores before they are aggregated by patient. Zero-weight rows and clusters represented only by zero-weight rows are excluded from correction counts. The fitted model- based covariance is used as the bread; a penalized fit requesting var.penalty = "sandwich" uses its retained var.from.info.matrix inverse sensitivity. The selected type and cadjust settings affect conditional analytical variance estimates and MVN inference. Unconditional analytical variance estimates instead combine variation between patients' predictions with uncertainty in coefficient estimation; see inferences() for the calculation and supported models.

Row weights and subset supplied through ... are evaluated once when the model is fitted, looking first in data and then where orm_markov() was called, so they can be vectors defined outside data. Weights must be finite and non-negative. Each row keeps its weight in the data stored on the fit, and the stored data contain only the rows selected by subset, so bootstrap refits resample rows together with their weights.

Model-based SOP and diagnostic workflows require models created by orm_markov(), vglm_markov(), or blrm_markov(). The wrappers record the fitted-data and model-provenance contracts needed by those workflows; a raw backend fit is not accepted as a substitute.

See also

blrm_markov(), vglm_markov(), sops(), avg_sops()

Examples

if (FALSE) { # \dontrun{
dd <- rms::datadist(data)
options(datadist = "dd")

fit <- orm_markov(
  ordered(y) ~ rms::rcs(time, 4) + tx + yprev,
  data = data,
  id_var = "id"
)

sops(fit, times = 1:60, y_levels = factor(1:6), absorb = "6")
} # }