*! version 1.0.0 06apr2026

Title

finegray_predict -- Post-estimation predictions after finegray

Syntax

finegray_predict
[type]
newvar
[if] [in],
[options]

xb linear predictor z'beta (default)

cif cumulative incidence function

schoenfeld Schoenfeld residuals at cause-event times

timevar(varname) use varname instead of _t for time

Description

finegray_predict generates predictions after finegray. Three prediction types are available:

xb (default) computes the linear predictor z'beta from the Fine-Gray model coefficient vector.

cif computes the cumulative incidence function: CIF(t|z) = 1 - exp(-H0(t) * exp(z'beta)), where H0(t) is the baseline cumulative subdistribution hazard stored in e(basehaz).

schoenfeld computes Schoenfeld residuals at cause-event times. For a model with p covariates, this creates p variables: newvar for the first covariate, newvar_2 through newvar_p for the rest. Residuals are missing for non-cause-event observations.

finegray must have been run before using finegray_predict. For models fit with factor variables or interactions, the current data must preserve the same factor-level support as the estimation sample. If a factor level has been dropped (e.g., by drop if), prediction will fail with an informative error.

Data requirements by prediction type: xb predictions can be computed on any dataset containing the model covariates. cif predictions additionally require a time variable (_t or timevar()). schoenfeld residuals and finegray_phtest require the original stset estimation data — specifically _t, _d, and a nonempty estimation sample (e(sample)). These commands will exit with an informative error if the estimation context is not present.

Options

xb computes the linear predictor z'beta. This is the default if neither cif nor schoenfeld is specified.

cif computes the cumulative incidence function (CIF) at each observation's event time. The CIF is computed as 1 - exp(-H0(t) * exp(z'beta)) using the baseline cumulative subdistribution hazard from e(basehaz).

schoenfeld computes Schoenfeld residuals at cause-event times. For a model with p covariates, p variables are created: newvar contains residuals for the first covariate, and newvar_2 through newvar_p contain residuals for the remaining covariates. Residuals are set to missing for observations that are not cause-of-interest events. timevar() has no effect when schoenfeld is specified; residuals are always computed at the original event times.

timevar(varname) specifies a variable to use as the time axis instead of _t. This is useful for generating predictions at specific time points or when the data are not currently stset.

Note: Factor-variable predictions are reconstructed on demand via fvrevar. The current data must contain the same factor levels as the estimation sample. Prediction on new data that lack a level present at estimation will exit with an informative error. If the persisted _fg_* design columns were dropped, schoenfeld residual labels still refer to the underlying factor term rather than an internal tempvar.

Examples

Setup

. webuse hypoxia, clear

. gen byte status = failtype

. stset dftime, failure(dfcens==1) id(stnum)

. finegray ifp tumsize pelnode, compete(status) cause(1)

Linear predictor (default)

. finegray_predict xb_hat

Cumulative incidence function

. finegray_predict cif_hat, cif

CIF with explicit storage type

. finegray_predict double cif_precise, cif

. summarize cif_precise

CIF at custom time points

. gen double mytime = 5

. finegray_predict cif_at5, cif timevar(mytime)

Schoenfeld residuals

. finegray_predict sch, schoenfeld

. list sch* in 1/5

Stored results

finegray_predict creates a new variable but does not store results in r() or e(). The new variable is labeled:

xb: "Linear prediction (xb)"

cif: "CIF prediction"

schoenfeld: "Schoenfeld residual: varname" for each covariate

Author

Timothy P Copeland, Karolinska Institutet

Version 1.0.0, 2026-04-06

Report bugs and suggestions at

https://github.com/tpcopeland/Stata-Tools

Also see

Online: finegray, finegray_phtest, stcrreg, stcox, stset