Version 1.2.2 separates variance estimation (error), the
CI transformation (conf.type), and the reference
distribution (conf.dist). For the formulas, method
combinations, and a worked example, see Computational formulas in cifcurve().
formula A model formula specifying the time-to-event
outcome on the left-hand side (typically
Event(time, status) or
survival::Surv(time, status)) and, optionally, a
stratification variable on the right-hand side. Unlike
cifplot(), this function does not accept a fitted
survfit object.data A data frame containing variables in
formula.weights Optional name of the weight variable in
data. Weights must be nonnegative. Supplied weights are
treated as fixed, including externally estimated IPTW; uncertainty from
estimating a propensity-score model is not included.n.risk.type Character string; one of
"weighted", "unweighted", or
"ess". Controls which risk set size is returned in
$n.risk without affecting estimates or standard errors
(default "weighted").subset.condition Optional character string giving a
logical condition to subset data (default
NULL).na.action A function specifying the action to take on
missing values (default na.omit).outcome.type Character string specifying the type of
time-to-event outcome. One of "survival" (Kaplan-Meier) or
"competing-risk" (Aalen-Johansen). If NULL
(default), the function automatically infers the outcome type from the
data: if the event variable has more than two unique levels,
"competing-risk" is assumed; otherwise,
"survival" is used. You can also use abbreviations such as
"S" or "C". Mixed or ambiguous inputs (e.g.,
c("S", "C")) trigger automatic detection based on the event
coding.code.event1 Integer code of the event of interest
(default 1).code.event2 Integer code of the competing event
(default 2).code.censoring Integer code of censoring (default
0).error Variance estimator. For unweighted KM, choose
"greenwood" (default), "tsiatis",
"if", or "fay". For unweighted AJ, choose
"delta" (default), "aalen", "if",
or "fay". With supplied weights, use "if"
(default) or "fay"; other choices warn and fall back to
"if". "fay" applies a Fay–Graubard-type
sandwich correction with a fixed leverage cap of 0.75; "fg"
and "fay-graubard" are accepted aliases.conf.type CI transformation: "plain",
"log", "log-log", "logit",
"arcsin" (default; aliases
"arcsine-square root", "a"), or
"none" to omit CIs. It acts on KM survival or on
1 - CIF for AJ. In particular, AJ "log-log"
uses log(-log(1 - CIF)).conf.int Numeric two-sided level of CIs (default
0.95).conf.dist Reference distribution for pointwise CIs:
"normal" (default) or "t". Student CIs require
error = "if" or "fay"; omitting
error with conf.dist = "t" selects
"if". This argument does not change the optional one-sided
test, which uses a normal reference.df.method Student degrees-of-freedom allocation:
"deletion" (default; FDF) or "equal" (EDF,
available only with error = "if"). Ignored for normal CIs.
Degrees of freedom vary by time and stratum and are generally not the
sample size minus one.time.point Optional single time point at which a
one-sided normal approximation test is performed when
null.hypothesis is specified.null.hypothesis Optional null value for the survival
probability or cumulative incidence at time.point. For
outcome.type = "survival", the one-sided alternative is
that the observed survival probability is higher than the null value.
For outcome.type = "competing-risk", the one-sided
alternative is that the observed CIF for code.event1 is
lower than the null value. A scalar value is recycled across strata. A
named numeric vector can be used to specify stratum-specific null
values.report.influence.function Logical. When
TRUE and engine = "calculateAJ_Rcpp", the
influence function is also computed and returned (default
FALSE).report.survfit.std.err Logical. If TRUE,
report SE on the log-survival scale (survfit’s convention). Otherwise SE
is on the probability scale.engine Character. One of "auto",
"calculateKM", or "calculateAJ_Rcpp"
(default). Student CIs and error = "fay" require
"calculateAJ_Rcpp" or "auto".prob.bound Numeric lower bound used to internally
truncate probabilities away from 0 and 1 (default
1e-7).IF/FG fits record conf.dist, df,
df.reason, critical.value, and
conf.status; Student fits also record
df.method. fay.bound in an FG fit records the
fixed cap 0.75 and is not an input argument. Use
summary(fit, times = ..., extend = TRUE) to extract saved
estimates, CIs, and diagnostics at requested times. For AJ,
$surv and its limits concern 1 - CIF; reverse
and complement the limits to obtain a CIF interval.
On the C++ IF/FG path, valid boundary estimates have singleton intervals. Interior zero/invalid variance, unavailable Student degrees of freedom, and times beyond positive-weight follow-up support give missing limits. Student failures do not fall back to normal CIs. These are pointwise approximations, not simultaneous bands or exact Student intervals.
To display IF-t (FDF or EDF) or FG-t intervals, first fit
cifcurve() with conf.dist = "t" and the
desired df.method, then pass that fitted object as
formula_or_fit. These two options are not forwarded by the
plotting formula interface through ... or
survfit.info. A supplied fit retains its saved intervals;
plotting arguments do not refit it.
fit <- cifcurve(
Event(t, epsilon) ~ fruitq1, data = diabetes.complications,
outcome.type = "competing-risk", error = "if", conf.dist = "t",
df.method = "equal", conf.type = "log-log"
)
cifplot(fit, outcome.type = "competing-risk", add.risktable = FALSE)formula_or_fit Either a model formula or a survfit
object. When a formula is supplied, the LHS must be
Event(time, status) or Surv(time, status). The
RHS specifies an optional stratification variable.data A data frame containing variables in
formula.weights Optional name of the weight variable in
data. Weights must be nonnegative. Supplied weights are
treated as fixed, including externally estimated IPTW; uncertainty from
estimating a propensity-score model is not included.n.risk.type Character string; one of
"weighted", "unweighted", or
"ess". Controls which risk set size is returned in
$n.risk without affecting estimates or standard errors
(default "weighted").subset.condition Optional character string giving a
logical condition to subset data (default
NULL).na.action A function specifying the action to take on
missing values (default na.omit).outcome.type Character string specifying the type of
time-to-event outcome. One of "survival" (Kaplan-Meier) or
"competing-risk" (Aalen-Johansen). If NULL
(default), the function automatically infers the outcome type from the
data: if the event variable has more than two unique levels,
"competing-risk" is assumed; otherwise,
"survival" is used. You can also use abbreviations such as
"S" or "C". Mixed or ambiguous inputs (e.g.,
c("S", "C")) trigger automatic detection based on the event
coding.code.event1 Integer code of the event of interest
(default 1).code.event2 Integer code of the competing event
(default 2).code.censoring Integer code of censoring (default
0).code.events code.events Optional specification of
event/censoring codes. For single-panel calls, supply a numeric vector.
For competing-risk outcomes, use
c(event1, event2, censoring). For survival outcomes, a
length-2 or length-3 vector is allowed: c(event, censoring)
or c(event, *, censoring), where any middle element is
ignored. When supplied, this argument overrides
code.event1, code.event2, and
code.censoring for the purpose of estimation. For panel
displays (e.g. cifpanel}() or when
panel.per.event = TRUE or
panel.censoring = TRUE), code.events may also
be a list of such numeric vectors, one per panel.error Variance estimator. For unweighted KM, choose
"greenwood" (default), "tsiatis",
"if", or "fay". For unweighted AJ, choose
"delta" (default), "aalen", "if",
or "fay". With supplied weights, use "if"
(default) or "fay"; other choices warn and fall back to
"if". "fay" applies a Fay–Graubard-type
sandwich correction with a fixed leverage cap of 0.75; "fg"
and "fay-graubard" are accepted aliases.conf.type CI transformation: "plain",
"log", "log-log", "logit",
"arcsin" (default; aliases
"arcsine-square root", "a"), or
"none" to omit CIs. It acts on KM survival or on
1 - CIF for AJ. In particular, AJ "log-log"
uses log(-log(1 - CIF)).conf.int Numeric two-sided level of CIs (default
0.95).type.y Character string specifying the y-scale. For
survival/CIF curves, "surv" implies survival probabilities
and "risk" implies CIF (1-survival in simple survival
settings). Specify "cumhaz" to plot cumulative hazard or
"cloglog" to generate a complementary log-log plot. If
NULL, a default is chosen from outcome.type or
the survfit object.label.x Character x-axis labels (default
"Time").label.y Character y-axis label (default is chosen
automatically from outcome.type and type.y,
e.g. “Survival”, “Cumulative incidence” or “Cumulative hazard”).label.strata Character vector of labels for
strata.order.strata Optional ordering of strata levels. When
panel.per.variable = TRUE, supply a named list
list(var = c("L1","L2",...)) for each RHS variable;
unmatched levels are dropped. When
panel.per.variable = FALSE, supply a character vector
c("L1","L2",...) that specifies the display order
(legend/risktable) of the single stratification factor. Levels not
listed are dropped. If label.strata is a named vector, its
names must match the (re-ordered) levels.limits.x Numeric length-2 vectors for axis limits. If
NULL it is internally set to
c(0,max(out_read_surv$t)).limits.y Numeric length-2 vectors for axis limits. If
NULL it is internally set to c(0,1).breaks.x Numeric vectors for axis breaks (default
NULL).breaks.y Numeric vectors for axis breaks (default
NULL).use.coord.cartesian Logical; if TRUE, uses
ggplot2::coord_cartesian() for zooming instead of changing
the scale limits (default FALSE).add.conf Logical add
add_confidence_interval() to plot. It calls
geom_ribbon() (default TRUE).add.risktable Logical add
add_risktable(risktable_stats="n.risk") to plot (default
TRUE).add.estimate.table Logical add
add_risktable(risktable_stats="estimate (conf.low, conf.high)")
to plot (default FALSE).symbol.risk.table Character specifying the symbol used
in the risk table to denote strata: "square",
"circle", or "triangle" (default
"square").font.size.risk.table Numeric font size for texts in
risk / estimate tables (default 3).add.censor.mark Logical add
add_censor_mark() to plot. It calls
geom_point() (default TRUE).shape.censor.mark Integer point shape for censor marks
(default 3).size.censor.mark Numeric point size for censor marks
(default 2).add.competing.risk.mark Logical add time marks to
describe event2 specified by Event(), usually the competing
events. It calls geom_point() (default
TRUE).competing.risk.time Named list of numeric vectors
(names must be mapped to strata labels).shape.competing.risk.mark Integer point shape for
competing-risk marks (default 16).size.competing.risk.mark Numeric point size for
competing-risk marks (default 2).add.intercurrent.event.mark Logical overlay
user-specified time marks per strata calls geom_point()
(default TRUE).intercurrent.event.time Named list of numeric vectors
(names must be mapped to strata labels).shape.intercurrent.event.mark Integer point shape for
intercurrent-event marks (default 1).size.intercurrent.event.mark Numeric point size for
intercurrent-event marks (default 2).add.quantile Logical add add_quantile() to
plot. It calls geom_segment() (default
TRUE).level.quantile Numeric quantile level for
add_quantile() (default 0.5).panel.per.event Logical. Explicit panel mode. If
TRUE and outcome.type == "competing-risk",
cifplot() internally calls cifpanel() to
display two event-specific CIFs side-by-side (event 1 and event 2) using
reversed code.events. Ignored for non-competing-risk
outcomes.panel.censoring Logical. Explicit panel mode. If
TRUE and outcome.type == "survival",
cifplot() internally calls cifpanel() to
display KM-type curves for (event, censor) and (censor, event) so that
censoring patterns can be inspected.panel.per.variable Logical. Explicit panel mode. If
TRUE and the right-hand side of the formula has multiple
covariates (e.g. ~ a + b + c), the function produces a
panel where each variable in RHS is used once as the stratification
factor.panel.mode Character specifying Automatic panel mode.
If "auto" and none of panel.per.variable,
panel.per.event, panel.censoring has been set
to TRUE, the function chooses a suitable panel mode
automatically: (i) if the formula RHS has 2+ variables, it behaves like
panel.per.variable = TRUE; (ii) otherwise, if
outcome.type == "competing-risk", it behaves like
panel.per.event = TRUE; (iii) otherwise, if
outcome.type == "survival", it behaves like
panel.censoring = TRUE. If a panel mode is explicitly
specified, panel.mode is ignored.rows.columns.panel Optional integer vector
c(nrow, ncol) controlling the panel layout. If
NULL, an automatic layout is used.style Character plot theme controls (default
"classsic").palette Optional character vector specify color
palette, e.g. palette=c("blue", "cyan", "navy", "green")
(default NULL).linewidth Optional numeric specifying the line width of
curve (default 0.8).linetype Optional logical using different line types of
curve (default \code{FALSE`).font.family Character plot theme controls
(e.g. "sans", "serif", and
"mono". default "sans").font.size Integer plot theme controls (default
12).legend.position Character specify position of legend:
"top", "right", "bottom",
"left", or "none" (default
"top").filename.ggsave Character save the
ggsurvfit plot with the path and name specified.width.ggsave Numeric specify width of the
ggsurvfit plot.height.ggsave Numeric specify height of the
ggsurvfit plot.dpi.ggsave Numeric specify dpi of the
ggsurvfit plot.... Additional arguments passed to internal helper
functions. This does not provide forwarding of conf.dist or
df.method; use a fitted cifcurve object for
Student intervals.For Student intervals, compute each curve with
cifcurve(), plot each fitted object with
cifplot(), and supply the resulting plots through
plots. The formula-based panel interface does not forward
conf.dist or df.method.
plots Optional list of existing ggplot objects to be
arranged into a panel. When plots is supplied, no new models are fitted;
the plots are used as-is.
formula A model formula specifying the time-to-event
outcome on the left-hand side (typically
Event(time, status) or
survival::Surv(time, status)) and, optionally, a
stratification variable on the right-hand side. Unlike
cifplot(), this function does not accept a fitted
survfit object.
formulas A list of formulas (one per panel). If
provided, overrides formula.
data A data frame containing variables in
formula.
weights Optional name of the weight variable in
data. Weights must be nonnegative. Supplied weights are
treated as fixed, including externally estimated IPTW; uncertainty from
estimating a propensity-score model is not included.
n.risk.type Character string; one of
"weighted", "unweighted", or
"ess". Controls which risk set size is returned in
$n.risk without affecting estimates or standard errors
(default "weighted").
subset.condition Optional character string giving a
logical condition to subset data (default
NULL).
na.action A function specifying the action to take
on missing values (default na.omit).
outcome.type Character string specifying the type of
time-to-event outcome. One of "survival" (Kaplan-Meier) or
"competing-risk" (Aalen-Johansen). If NULL
(default), the function automatically infers the outcome type from the
data: if the event variable has more than two unique levels,
"competing-risk" is assumed; otherwise,
"survival" is used. You can also use abbreviations such as
"S" or "C". Mixed or ambiguous inputs (e.g.,
c("S", "C")) trigger automatic detection based on the event
coding.
code.event1 Integer code of the event of interest
(default 1).
code.event2 Integer code of the competing event
(default 2).
code.censoring Integer code of censoring (default
0).
code.events code.events Optional specification of
event/censoring codes. For single-panel calls, supply a numeric vector.
For competing-risk outcomes, use
c(event1, event2, censoring). For survival outcomes, a
length-2 or length-3 vector is allowed: c(event, censoring)
or c(event, *, censoring), where any middle element is
ignored. When supplied, this argument overrides
code.event1, code.event2, and
code.censoring for the purpose of estimation. For panel
displays (e.g. cifpanel}() or when
panel.per.event = TRUE or
panel.censoring = TRUE), code.events may also
be a list of such numeric vectors, one per panel.
code.events Optional numeric length-3 vector
c(event1, event2, censoring). When supplied, it overrides
code.event1, code.event2, and
code.censoring (primarily used when cifpanel()
is called or when panel.per.event = TRUE).
error Variance estimator. For unweighted KM, choose
"greenwood" (default), "tsiatis",
"if", or "fay". For unweighted AJ, choose
"delta" (default), "aalen", "if",
or "fay". With supplied weights, use "if"
(default) or "fay"; other choices warn and fall back to
"if". "fay" applies a Fay–Graubard-type
sandwich correction with a fixed leverage cap of 0.75; "fg"
and "fay-graubard" are accepted aliases.
conf.type CI transformation: "plain",
"log", "log-log", "logit",
"arcsin" (default; aliases
"arcsine-square root", "a"), or
"none" to omit CIs. It acts on KM survival or on
1 - CIF for AJ. In particular, AJ "log-log"
uses log(-log(1 - CIF)).
conf.int Numeric two-sided level of CIs (default
0.95).
type.y Character string specifying the y-scale. For
survival/CIF curves, "surv" implies survival probabilities
and "risk" implies CIF (1-survival in simple survival
settings). Specify "cumhaz" to plot cumulative hazard or
"cloglog" to generate a complementary log-log plot. If
NULL, a default is chosen from outcome.type or
the survfit object.
label.x, label.y Optional vectors/lists
of axis labels per panel.
label.strata Optional list of character vectors for
legend labels per panel (passed to cifplot()).
order.strata Optional list of character vectors for
ordering labels per panel (passed to cifplot()).
limits.x, limits.y Optional
vectors/lists of numeric length-2 axis limits per panel.
breaks.x, breaks.y Optional
vectors/lists of axis breaks per panel (forwarded to
breaks.x / breaks.y in
cifplot()).
add.conf, add.censor.mark,
add.competing.risk.mark,
add.intercurrent.event.mark, add.quantile
Optional logical vectors/lists per panel to toggle features in
cifplot(). If NULL, sensible defaults are used
(CI/Censor on; others off).
rows.columns.panel Integer vector
c(nrow, ncol) specifying the grid size.
title.panel, subtitle.panel,
caption.panel Optional strings for panel
annotation.
tag.panel Passed to
patchwork::plot_annotation(tag_levels = ...).
title.plot Optional length-2 character vector,
titles for base/inset plots when
inset.panel = TRUE.
legend.position Position of legends:
"top", "right", "bottom",
"left", or "none".
legend.collect If TRUE (grid mode),
collect legends across subplots.
inset.panel If TRUE, place the second
plot as an inset over the first.
inset.left, inset.bottom,
inset.right, inset.top Numeric positions (0–1)
of the inset box.
inset.align.to One of "panel",
"plot", or "full".
inset.legend.position Legend position for the inset
plot (e.g., "none").
filename.ggsave Character save the composed panel
with the path and name specified.
width.ggsave Numeric specify width of the composed
panel.
height.ggsave Numeric specify height of the composed
panel.
dpi.ggsave Numeric specify dpi of the composed
panel.
print.panel Logical. If TRUE, the
composed patchwork object is printed immediately (for interactive use).
If FALSE, the object is returned invisibly so that it can
be assigned, modified, or saved. Kept for backward
compatibility.
engine Character scalar selecting the internal
plotting engine. Currently only "cifplot" is supported and
used to construct each panel cifplot_single(). This
argument is reserved for future extensions.
... Additional arguments forwarded to
cifplot (e.g., style,
font.family, font.size, etc.). Panel-wise
overrides provided via explicit arguments take precedence over
....
nuisance.model A formula describing the
outcome and nuisance covariates, excluding the exposure of interest. The
left-hand side must be Event(time, status) or
survival::Surv(time, status).exposure A character string giving the name of the
categorical exposure variable in data.strata Optional character string with the name of the
stratification variable used to adjust for dependent censoring (default
NULL).data A data frame containing the outcome, exposure and
nuisance covariates referenced by nuisance.model.subset.condition Optional character string giving a
logical condition to subset data (default
NULL).na.action A function specifying the action to take on
missing values (default na.omit).code.event1 Integer code of the event of interest
(default 1).code.event2 Integer code of the competing event
(default 2).code.censoring Integer code of censoring (default
0).code.exposure.ref Integer code identifying the
reference exposure category (default 0).effect.measure1 Character string specifying the effect
measure for the primary event. Supported values are "RR",
"OR" and "SHR".effect.measure2 Character string specifying the effect
measure for the competing event. Supported values are "RR",
"OR" and "SHR".time.point Numeric time point at which the exposure
effect is evaluated. Required for survival and competing risk
analyses.outcome.type Character string selecting the outcome
type. Valid values are "competing-risk",
"survival", "binomial",
"proportional-survival" and
"proportional-competing-risk". Defaults to
"competing-risk". If NULL (default), the
function automatically infers the outcome type from the data: if the
event variable has more than two unique levels,
"competing-risk" is assumed; otherwise,
"survival" is used. You can also use abbreviations such as
"S" or "C". Mixed or ambiguous inputs (e.g.,
c("S", "C")) trigger automatic detection based on the event
coding in data.conf.int Numeric two-sided level of CIs (default
0.95).report.nuisance.parameter Logical if TRUE,
the returned object includes estimates of the nuisance model parameters
(default FALSE).report.optim.convergence Logical if TRUE,
optimization convergence summaries are returned (default
FALSE).report.sandwich.conf Logical or NULL. When
TRUE, CIs based on sandwich variance are computed. When
FALSE, they are omitted (default TRUE). This
CI is default for time-point models
("outcome.type=COMPETING-RISK", "survival" or
"binomial") and is not available otherwise.report.boot.conf Logical or NULL. When
TRUE, bootstrap CIs are computed. When FALSE,
they are omitted. If NULL, the function chooses based on
outcome.type (default NULL). This CI is
default for proportional models
(outcome.type="proportional-competing-risk" or
"proportional-survival").boot.bca Logical indicating the bootstrap CI method.
Use TRUE for bias-corrected and accelerated intervals or
FALSE for the normal approximation (default to
FALSE).boot.replications Integer giving the number of
bootstrap replications (default to 200).boot.seed Numeric seed used for resampling of
bootstrap.nleqslv.method Character string specifying the solver
used in nleqslv(). Available choices are
"Broyden" and "Newton".optim.parameter1 Numeric tolerance for convergence of
the outer loop (default 1e-6).optim.parameter2 Numeric tolerance for convergence of
the inner loop (default 1e-6).optim.parameter3 Numeric constraint on the absolute
value of parameters (default 100).optim.parameter4 Integer maximum number of outer loop
iterations (default 50).optim.parameter5 Integer maximum number of
nleqslv() iterations per outer iteration (default
50).optim.parameter6 Integer maximum number of iterations
for the Levenberg-Marquardt routine (default 50).optim.parameter7 Numeric convergence tolerance for the
Levenberg-Marquardt routine (default 1e-10).optim.parameter8 Numeric tolerance for updating the
Hessian in the Levenberg-Marquardt routine (default
1e-6).optim.parameter9 Numeric starting value for the
Levenberg-Marquardt damping parameter lambda (default
1e-6).optim.parameter10 Numeric upper bound for lambda in the
Levenberg-Marquardt routine (default 40).optim.parameter11 Numeric lower bound for lambda in the
Levenberg-Marquardt routine (default 0.025).optim.parameter12 Numeric multiplicative increment
applied to lambda when the Levenberg-Marquardt step is successful
(default to 2).optim.parameter13 Numeric multiplicative decrement
applied to lambda when the Levenberg-Marquardt step is unsuccessful
(default 0.5).data.initial.values Optional data frame providing
starting values for the optimization (default NULL).normalize.covariate Logical indicating whether
covariates should be centered and scaled prior to optimization (default
TRUE).terminate.time.point Logical indicating whether time
points that contribute estimation are terminated by min of max follow-up
times of each exposure level (default TRUE).prob.bound Numeric lower bound used to internally
truncate probabilities away from 0 and 1 (default
1e-7).