A data frame containing the time/status information and, if used, the covariate.

A vector of length 2 giving the time and status fields. It is recommended to use vars() and symbolic column names or code that is tidily-evaluated on data. You can also pass a character vector with the column names or a numeric vector with column indices.

The covariates. Pass symbolic columns names or code that is tidily-evaluated on data. Column names or column indices are also possible. In any case, factors with appropriate labels will be generated which in all printouts. You can use covariate_name_dict and covariate_label_dict to rename these factors and their levels.

Interactions (optional). Same format as covariates. Covariates to include together with their interaction (*, not + in the formula)

Strata (optional). Same format as covariates. For each strata level (if multiple fields, unique combinations of levels) a separate baseline hazard is fit.

A dictionary (named list or vector) of old->new covariate names

A dictionary (named list or vector) of old->new covariate value level labels

For categorical variables, the Cox regression uses pseudo variables for each level relative to a reference category, resulting in n-1 variables for n levels of a categorical covariate. Hazard ratios will be relative to the reference level, which is defined as having hazard ratio 1.0. Per default, the reference level is the first factor level. You can specify a different level by passing a named vector: factor name -> value of reference level. Note that this is independent of covariate_label_dict, i.e. specify the factor level as it is in data#'

A vars() list of one or more symbolic column names. The result contains a data frame of the cox regression results (cox_as_data_frame). This frame contains the variables "Lower_CI", "HR", "Upper_CI", "Inv_Lower_CI", "Inv_HR", "Inv_Upper_CI", "p". You can specify by which variables the frame should be sorted. Default: Hazard Ratio.

A data frame containing the time/status information and, if used, the covariate.

A vector of length 2 giving the time and status fields. It is recommended to use vars() and symbolic column names or code that is tidily-evaluated on data. You can also pass a character vector with the column names or a numeric vector with column indices.

The term by which survival curves will be separated. Pass NULL or omit to generate a single curve and only descriptive statistics. Pass symbolic columns names or code that is tidily-evaluated on data to generate more than one curve, and the appropriate statistics to compare the curves. A column name or column index is also possible. In any case, the parameter will be used to create a factor with appropriate labels. This factor will appear in all printouts and plots. You can use by_label_map and by_order_vector to rename and reorder this factor.

A dictionary (named list or vector) of old->new labels of the factor created using by. The factor will be renamed accordingly, and also reordered by the order of the vector.

A vector of the labels of the factor created using by, after renaming them based on by_label_map (so specify the "new" level). The factor will be ordered according to the order of this vector. It need not contain all elements, only those found will be reorder at the top.

The result will include a univariate Cox regression. Use this parameter to specify the level of the factor generated using by that you want to use a the reference level (Hazard ratios will be relative to the reference level, which is defined as having hazard ratio 1.0) Note that the given string applies after all renaming has been done, so specify the "new" level.

If there are more than two levels in the by factor, the result will include the return value of pairwise_survdiff, which performs p adjustment. You can specify the desired method here. Note that other p values are not corrected, this is beyond the scope of this method.

Named list of arguments that will be stored for later use in plotting methods, such as kaplan_meier_plot. There they will take precedence over arguments given to that method. This is useful when plotting multiple results with a set of default arguments, of which some such as title or axis scale differ per-plot.

The summary.coxph or coxph result object

An unmangle dict of mangled column name -> readable column name (as created by analyse_multivariate)

The frame contains one column "factor.id" which is a composite of covariate name and, if categorical, the factor level (one line for each factor level except for the reference level)

A vars() list of one or more symbolic column names. This frame contains the variables "Lower_CI", "HR", "Upper_CI", "Inv_Lower_CI", "Inv_HR", "Inv_Upper_CI", "p". You can choose to sort by any combination. Use desc() to sort a variable in descending order.

The SurvivalAnalysisResult objects. You can also pass one list of such objects, or use explicit splicing (!!! operator). If not use_one_hot, also a list of coxph objects, or a mix is acceptable.

If not use_one_hot (default), will take univariate or multivariate results and plot hazard ratios against the reference level (as provided to the analyse_survival or analyse_multivariate function, or, per default, the first factor level), resulting in k-1 values for k levels. If use_one_hot == TRUE, will only accept univariate results from analyse_survival and plot HRs of one factor level vs. remaining cohort, resulting in k values for k levels.

Either

• A function which returns labels for the input: First argument, a vector of either (factor.ids) or (endpoints), resp. If the function takes ... or two arguments, as second argument a data frame with (at least) the columns survivalResult, endpoint, factor.id, factor.name, factor.value, HR, Lower_CI, Upper_CI, p, n, where survivalResult is the corresponding result object passed to forest_plot; Note the function must be vectorized, if you have a non-vectorized function taking single arguments, you may want to have a look at purrr::map_chr or purrr::pmap_chr.

• a dictionaryish list, looks up by (endpoints) or (factor.ids). The factor.id value: For continous factors, the factor name (column name in data frame); For categorical factors, factor name, factor_id_sep, and the factor level value. (note: If use_one_hot = FALSE, the HR is factor level value vs. cox reference given to survival_analysis; if use_one_hot = TRUE, the HR is the factor level value vs. remaining population)

A function which returns an integer ordering vector for the input:

• if the supplied function takes exactly one argument, a data frame with (at least) the columns survivalResult, endpoint, factor.id, factor.name, factor.value, HR, Lower_CI, Upper_CI, p, n, subgroup_n where survivalResult is the corresponding result object passed to forest_plot;

• or, if the function takes more than one argument, or its arguments include ..., the nine vectors (endpoint, factor.name, factor.value, HR, Lower_CI, Upper_CI, p, n, subgroup_n): a vector of endpoints (as given to Surv(endpoint, ...) in coxph), a vector of factors (as given to the right hand side of the coxph formula), and numeric vectors of the HR, lower CI, upper CI, p-value

• You can create a function from ordered vectors via orderer_function_from_sorted_vectors, or call order() with one or more of these vectors.

• Alternatively, you can provide a quosure of code, or a right-hand side formula; it will be executed such that the above nine vectors are available as symbols.

Example:

• orderer = quo(order(endpoint, HR))

• equivalent to orderer = ~order(endpoint, HR)

• equivalent to orderer = function(df) df %$% order(endpoint, HR)

• equivalent to orderer = function(df) { order(df$endpoint, df$HR) }

• equivalent to orderer = function(endpoint, factor.name, factor.value, HR, ...) order(endpoint, HR)

A function which returns one logical value if a breaking line should be inserted _above_ the input: Same semantics as for orderer. !Please note!: The order of the data is not yet ordered as per your orderer! If you do calculations depending on order, first order with your own orderer function. A proper implementation is easy using sequential_duplicates, for example categorizer=~!sequential_duplicates(endpoint, ordering = order(endpoint, HR))

relation of the width of the plots, labels, plot, values. Default is 1:1:1.

ggplot2 theme to use

Combination of "endpoint", "factor", "n", determining what is shown on the left-hand table and in which order.

Named vector with name=<allowed values of labels_displayed>, value=<your heading>.

Combination of "HR", "CI", "p", "subgroup_n", determining what is shown on the right-hand table and in which order. Note: subgroup_n is only applicable if oneHot=TRUE.

Named vector with name=<allowed values of values_displayed>, value=<your heading>.

sprintf() format strings for hazard ratio and p value

The lower limit below which p value will be displayed as "less than". If p_lessthan_cutoff == 0.001, the a p value of 0.002 will be displayed as is, while 0.0005 will become "p < 0.001".

Plot on log scale, which is quite common and gives symmetric length for the CI bars. Note that HRs of 0 (did not converge) will not be plotted in this case.

Breaks of the x scale for plotting HR and CI

Limits of the x scale for plotting HR and CI. Default (HR_x_lim = NULL) depends on log_scale and existing limits. Pass NA to use the existing minimum and maximum values without interference. Pass a vector of size 2 to specify (min, max) manually

Allows you to customize the separator of the factor id, the documentation of factor_labeller.

Only used in the multivariate case (use_one_hot = FALSE). Should null coefficients (NA/0/Inf) be removed?

A title on top of the plot, taking a fraction of title_relative_height of the returned plot. The title is drawn using draw_label; you can specify any arguments to this function by giving title_label_args Per default, font attributes are taken from the "title" entry from the given ggtheme, and the label is drawn centered as per draw_label defaults.

numeric vector of length 2, c(width, height), unit inches. forest_plot will store a suggested "papersize" attribute in the return value, computed from base_papersize and the number of entries in the plot (in particular, the height will be adjusted) The attribute is read by save_pdf. It will also store a "forestplot_entries" attribute which you can use for your own calculations.

Data frame containing the columns survivalResult, endpoint, factor.id, factor.name, factor.value, HR, Lower_CI, Upper_CI, p, n, subgroup_n giving the information that is to be presented in the forest plot

Pass individual plots returned by forest_plot, or lists of such plots (bare lists will be spliced).

Specify the grid (one is sufficient, uses auto layout if both are null)

If the plots are given in by-row, or by-column (byrow=FALSE) order

Additional arguments to the plot_grid function which is used to create the grid.

The result generated by analyse_multivariate

Further arguments passed from other methods.

Precision with which to print floating point values

Cut-off for small p values. Values smaller than this will be displayed like "<..."

The result generated by analyse_survival

Further arguments passed from other methods.

A label describing the result

Precision with which to print floating point values

Cut-off for small p values. Values smaller than this will be displayed like "<..."

Append "\n—\n"? Comes handy if printing multiple results following each other

Unit for time spans: "days", "months" or "years".

The ggsurvplot object

Layout parameters, see arrange_ggsurvplots

Number of items in grid

Pass one of rows or cols, or none, in which case auto layout is used.

a vector

Effectively ignored

Named SurvivalAnalysisResult objects as returned by analyse_survival. Please note that the results need to come from the same data source and should only differ by the "by" parameter. The first given result acts as source for common attributes. Also takes one single named bare list.

One or many SurvivalAnalysisResult objects as returned by analyse_survival and arguments that will be passed to ggsurvplot. Bare lists will be spliced. If using lists, the same argument may be contained in multiple lists; in this case, the last occurrence is used, i.e. you can first pass a list with default arguments, and then override some of them. If you want to combine two curves in one plot (ggsurvplot_combine), wrap them in in_one_kaplan_meier_plot when passing as argument here. (otherwise you will get a list with separate plots for each) In addition to all arguments supported by ggsurvplot, these arguments and shortcuts can be used additionally:

• break.time.by: breakByYear, breakByHalfYear, breakByQuarterYear, breakByMonth (numeric value only in ggsurvplot)

• xscale: scaleByYear, scaleByMonth (numeric value only in ggsurvplot)

• hazard.ratio (logical): display hazard ratios in addition to p value, complementing pval=T

• xlab: {.OS,.PFS,.TTF,.DFS}.{years,months,days}

• table.layout: clean, displays risk table only with color code and number, no grid, axes or labels. (do not forget risk.table=TRUE to see something)

• papersize: numeric vector of length 2, c(width, height), unit inches. kaplan_meier_plot will store a "papersize" attribute with this value which is read by save_pdf

• ggplot.add: ggplot2 object to add to the ggplot plot part of the created KM plot. One common use case is manual specification of the line type, which is currently not possible with ggsurvplot. The passed object can be result of "+" operations will be added via "+" as usual with ggplot() objects.

Determines the layout by giving nrow and/or ncol, if missing, uses an auto layout.

Optionally specify a layout matrix, which is passed to marrangeGrob

If no layout_matrix is specified and there are multiple rows: How should the plots by layout? The order of the plots can be by-row (default) or by-col (set byrow=FALSE).

Optionally, if given n objects to plot, a named list of vectors of size n. The name is an argument names passed to ggsurvplot. The elements of the vector will be mapped 1:1 to each object. This allows to perform batch plotting where only few arguments differ (e.g. titles A, B, C...) between the plots. Please note that only object that need plotting (survival_analysis results) are considered, not those that are already plotted (kaplan_meier_plot results)

You can specify the size per plot, or the full paper width and height. size_per_plot may be a number (width == height) or two-dimensional, width and height. The resulting paper size will be stored as a papersize attribute that is e.g. read by save_pdf

Passed to arrange_ggsurvplots

The lower limit below which p value will be displayed as "less than". If p_lessthan_cutoff == 0.001, the a p value of 0.002 will be displayed as is, while 0.0005 will become "p < 0.001".

One or many SurvivalAnalysisResult objects as returned by analyse_survival and arguments that will be passed to ggsurvplot. Bare lists will be spliced. If using lists, the same argument may be contained in multiple lists; in this case, the last occurrence is used, i.e. you can first pass a list with default arguments, and then override some of them. If you want to combine two curves in one plot (ggsurvplot_combine), wrap them in in_one_kaplan_meier_plot when passing as argument here. (otherwise you will get a list with separate plots for each) In addition to all arguments supported by ggsurvplot, these arguments and shortcuts can be used additionally:

• break.time.by: breakByYear, breakByHalfYear, breakByQuarterYear, breakByMonth (numeric value only in ggsurvplot)

• xscale: scaleByYear, scaleByMonth (numeric value only in ggsurvplot)

• hazard.ratio (logical): display hazard ratios in addition to p value, complementing pval=T

• xlab: {.OS,.PFS,.TTF,.DFS}.{years,months,days}

• table.layout: clean, displays risk table only with color code and number, no grid, axes or labels. (do not forget risk.table=TRUE to see something)

• papersize: numeric vector of length 2, c(width, height), unit inches. kaplan_meier_plot will store a "papersize" attribute with this value which is read by save_pdf

• ggplot.add: ggplot2 object to add to the ggplot plot part of the created KM plot. One common use case is manual specification of the line type, which is currently not possible with ggsurvplot. The passed object can be result of "+" operations will be added via "+" as usual with ggplot() objects.

Optionally, if given n objects to plot, a named list of vectors of size n. The name is an argument names passed to ggsurvplot. The elements of the vector will be mapped 1:1 to each object. This allows to perform batch plotting where only few arguments differ (e.g. titles A, B, C...) between the plots.

The lower limit below which p value will be displayed as "less than". If p_lessthan_cutoff == 0.001, the a p value of 0.002 will be displayed as is, while 0.0005 will become "p < 0.001".

An object of class "SurvivalAnalysisMultivariateResult" as returned by analyse_multivariate

The frame contains one column "factor.id" which is a composite of covariate name and, if categorical, the factor level (one line for each factor level except for the reference level)

A vars() list of one or more symbolic column names. This frame contains the variables "Lower_CI", "HR", "Upper_CI", "Inv_Lower_CI", "Inv_HR", "Inv_Upper_CI", "p". You can choose to sort by any combination. Use desc() to sort a variable in descending order.

An object of class SurvivalAnalysisMultivariateResult as returned by analyse_multivariate

The item to be retrieved:

• "coxph" containing the result of the coxph function

• "summary" containing the result of the summary of the "coxph" result

• "summary_data_frame" containing summary as a data frame (see multivariate_as_data_frame)

• "p" A vector of p values for the covariates, equivalent to the "p" column of "summary_data_frame"

• "overall" A named list with human-readable labels giving information about the overall fit, including the three flavors of p values contained in "summary"

An object of class SurvivalAnalysisUnivariateResult as returned by analyse_survival

The item to be retrieved:

• "survfit" containing the result of the survfit function

• "survdiff" containing the result of the survdiff function

• "survfit_overall" containing the result of the survfit function without terms, i.e. the full group not comparing subgroups

• "coxph" containing the result of the coxph function

• "p" The log-rank p value (if by provided at least two strata)

The result generated by analyse_multivariate

Further arguments passed from other methods.

Precision with which to print floating point values

Cut-off for small p values. Values smaller than this will be displayed like "<..."

The result generated by analyse_survival

Further arguments passed from other methods.

A label describing the result

Precision with which to print floating point values

Append "\n—\n"? Comes handy if printing multiple results following each other

Unit for time spans: "days", "months" or "years".

The result generated by analyse_survival

If true, all numbers will be formatted for printing according to the following options and will be returned as strings

Precision with which to print floating point values

Cut-off for small p values. Values smaller than this will be displayed like "<..."

Unit for time spans: "days", "months" or "years".

The result generated by analyse_survival

Optional label to include

Precision with which to print floating point values

Append "\n—\n"? Comes handy if printing multiple results following each other

Unit for time spans: "days", "months" or "years".

Print string to console

The result generated by analyse_survival

Time points to compute survival rate at

Precision with which to print floating point values in their label form

Unit for time spans: "days", "months" or "years".

Results generated by analyse_survival, or analyse_multivariate, or lists of such objects

A connection, or a character string naming the file to print to. (see cat)

A label describing the result, or a vector of the same size as results in ... (will then be mapped 1:1)

Precision with which to print floating point values

Boolean: Append "\n—\n" as separator? Comes handy if printing multiple results following each other

Unit for time spans: "days", "months" or "years"

Results generated by analyse_survival, or lists of such objects

A connection, or a character string naming the file to print to. (see cat)

Time points to compute survival rate at

A label describing the result, or a vector of the same size as results in ... (will then be mapped 1:1). Recommended to distinguish result lines from multiple results in ...

A writer function such as write.csv

Parameters to pass to the writer function

Precision with which to print floating point values in their label form

Unit for time spans: "days", "months" or "years"