Maximum likelihood for a user-defined transition rate model

frml: like tda_fml, but for episode (survival) data rather than plain cross-sectional rows – fn is the log-likelihood contribution of one episode, and can refer to time (the position within it) the way tda_rate's own define can. This is not fml under another name: the same definitions that work with fml on plain rows fail here with “no episode data defined” until an actual episode structure (survival::Surv()) is given.

Usage

tda_frml(
  formula,
  data,
  definitions,
  start = NULL,
  id = NULL,
  spell = NULL,
  control = NULL,
  constraints = NULL,
  residuals = FALSE,
  residual_vars = NULL,
  protocol = FALSE,
  options = list(),
  dir = tempfile("tda"),
  ...
)

Arguments

formula: a Surv(...) formula, the same as tda_rate's.
data: a data frame.
definitions: a character vector of assignments, evaluated in order inside TDA, the last of which must define fn – see tda_fml for the same convention on plain data, and the description above for the episode-specific variables available here. Or an unevaluated { } block of plain R assignments instead, translated automatically the same way tda_fml's definitions is. Names on the right that are neither a covariate from formula nor one of TDA's built-ins, and are not defined earlier, are parameters to be estimated. formula's Surv(...) arguments can also be referenced directly by their real column name when they are a simple column reference (Surv(TFP, DES)'s TFP/DES, say, work the same as TDA's built-ins tf - ts/des) – matching how TDA's manual writes this (examples/exam/frml1.cf, referencing its own DES/DUR columns directly, not through any built-in alias). A computed Surv() argument (Surv(TFin - TStart + 1, DES)) has no one column to translate to, so only TDA's built-ins reach it.
start: optional named list of starting values, in the order the definitions introduce the parameters.
id, spell: columns identifying the case and numbering its spells, for multi-episode data – the same pair tda_rate takes; a case's spells then enter the likelihood together. strata() in the formula is refused rather than accepted: fml has no stratification mechanism and would silently ignore the term (fit per stratum instead).
control: optional tda_control.
constraints: optional linear constraints on the parameters – frml's con=, the identical mechanism and bN-by-position convention as tda_fml's constraints (see there for the full explanation and a worked example of the naming trap); it works the same way here.
residuals: ask TDA to also compute, per episode, its contribution to fn at the converged parameters – frml's own pres=, the identical mechanism as tda_fml's own residuals (see there for what it actually is: not a classical observed-minus-fitted residual), computed per episode here.
residual_vars: with residuals = TRUE, extra columns to write alongside fn's value, one per episode – frml's own v=, the same mechanism as tda_fml's residual_vars. Only reliably supports a covariate from formula; TDA's episode built-ins (ts, tf, org, des, time) cannot be named here, despite being available inside fn: they are expression-only aliases, not real data-matrix variables – v = ts,tf is a TDA syntax error (their real, differently-named underlying variables, e.g. Tstart for ts, do work, but are internal, auto-generated by edef() and not something to build an interface around safely).
protocol: ask TDA to also write its iteration-by-iteration diagnostic log – frml's prot=, the same mechanism as tda_fml's protocol.
options: a named list of further TDA options, passed through.
dir: working directory.
...: passed to tda_run.

Value

An object of class tda_fit. With residuals = TRUE, also carries $residuals.

Details

fn's expression cannot reference the raw duration/status columns from data directly – Surv()'s columns are consumed by edef() into TDA's internal episode representation, and are not separately visible by name afterward. An fn written against the original column names fails with those names listed as parameters to estimate (TDA's convention for any identifier it does not otherwise recognise), not as a lookup error. Use TDA's built-in accessors for an episode instead: ts and tf (start and finish time), org and des (origin and destination state), time (tf - ts, and the same built-in tda_rate's define can use). A covariate, by contrast, is referenced by its own name from formula, translated automatically the same way tda_fml does it.

Examples

set.seed(1)
n <- 200
d <- data.frame(x = rnorm(n))
haz <- exp(0.5 + 0.8 * d$x)
d$dur <- rexp(n, haz)
d$status <- 1
# the exponential hazard model, written out by hand -- matches
# tda_rate(Surv(dur, status) ~ x, d, model = "exponential"). des and
# (tf - ts) are TDA's built-ins, not d's dur/status columns -- see
# Details.
fit <- tda_frml(Surv(dur, status) ~ x, d,
                c("xb = b0 + x * b1", "gamma = exp(xb)",
                  "fn = des * xb - gamma * (tf - ts)"))
coef(fit)
#>        b0        b1 
#> 0.5387063 0.7930654 
coef(tda_rate(Surv(dur, status) ~ x, d, model = "exponential"))
#>  Constant         x 
#> 0.5387064 0.7930655 

# the same model, written in R syntax instead
fit2 <- tda_frml(Surv(dur, status) ~ x, d, {
    xb = b0 + x * b1
    gamma = exp(xb)
    fn = des * xb - gamma * (tf - ts)
})
coef(fit2)
#>        b0        b1 
#> 0.5387063 0.7930654