Assumptions and limitations

What polarstate estimates, what the data must represent, and what it does not provide.

What the estimate means

polarstate computes non-parametric Aalen–Johansen state-occupancy probabilities. With codes 0 and 1, it describes a standard time-to-event outcome. Adding code 2 represents a competing event.

The estimates are descriptive probabilities for the supplied cohort. They are not causal effects and do not adjust for covariates.

Data assumptions

  • Each row represents one independent subject with one observed follow-up time.
  • times is numeric, finite, non-negative, and uses a consistent time unit.
  • reals is integer-coded: 0 for right-censoring, 1 for the event of interest, and optionally 2 for a competing event.
  • Censoring is assumed independent of the event process, conditional on the study design and any stratification performed before estimation.
  • Events tied at the same time are aggregated. Input rows need not be sorted.

The package validates the mechanical requirements above, but it cannot verify study-design assumptions such as independent censoring.

Scope and limitations

The current public API supports one event of interest and one optional competing event. It does not currently provide:

  • confidence intervals, standard errors, or hypothesis tests;
  • covariate-adjusted or causal estimates;
  • left truncation, interval censoring, or time-varying covariates;
  • survey weights or clustered variance estimates;
  • automatic missing-data handling.

For group-specific estimates, split the data explicitly. Differences between groups remain unadjusted and should not be interpreted as causal effects.

Boundary behavior

Predictions are step functions. A requested horizon between observed times uses the most recent estimate at or before that horizon. A horizon before the first observation returns state probabilities (1, 0, 0).

Output-name compatibility

Correctly spelled transition columns are:

  • transition_probabilities_to_1_at_times
  • transition_probabilities_to_2_at_times

The historical misspelled names beginning with trainsition_ remain in the event table as backward-compatible aliases. New code should use the correctly spelled names.

Before reporting results

Confirm the outcome coding, time origin, time unit, censoring definition, and the number at risk near the horizons you report. Inspect the event table rather than relying only on fixed-horizon output.