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.subset.condition Optional character expression to
subset data before analysis.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 Character string specifying the method for SEs
and CIs used internally. For "survival" without weights,
choose one of "greenwood" (default),
"tsiatis", or "if". For
"competing-risk" without weights, choose one of
"delta" (default), "aalen", or
"if". SEs and CIs based on influence functions
("if") is recommended for weighted analysis.conf.type Character specifying the method of
transformation for CIs used internally (default
"arcsine-square root").conf.int Numeric two-sided level of CIs (default
0.95).return_if 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
"calculateAJ_Rcpp").prob.bound Numeric lower bound used to internally
truncate probabilities away from 0 and 1 (default
1e-7).formula_or_fit A model formula or a survfit object.
Note: When a formula is supplied, the left-hand side must be
Event(time, status) or
survival::Surv(time, status).data A data frame containing variables in
formula.weights Optional name of the weight variable in
data. Weights must be nonnegative.subset.condition Optional character expression to
subset data before analysis.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 Character string specifying the method for SEs
and CIs used internally. For "survival" without weights,
choose one of "greenwood" (default),
"tsiatis", or "if". For
"competing-risk" without weights, choose one of
"delta" (default), "aalen", or
"if". SEs and CIs based on influence functions
("if") is recommended for weighted analysis.conf.type Character specifying the method of
transformation for CIs used internally (default
"arcsine-square root").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.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.
subset.condition Optional character expression to
subset data before analysis.
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 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 Character string specifying the method for SEs
and CIs used internally. For "survival" without weights,
choose one of "greenwood" (default),
"tsiatis", or "if". For
"competing-risk" without weights, choose one of
"delta" (default), "aalen", or
"if". SEs and CIs based on influence functions
("if") is recommended for weighted analysis.
conf.type Character specifying the method of
transformation for CIs used internally (default
"arcsine-square root").
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.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).