Package {ggforestplotR}

A plot created by ggforestplot() or a supported forest-table composition. Leave as NULL to use + add_favors(...) syntax.

Single strings shown beneath the left and right arrows.

Optional numeric reference value. NULL uses the reference line resolved by ggforestplot(), falling back to the null value stored in the forest-data metadata.

Gap on each side of the trained reference position, expressed as a fraction of the forest panel width.

Footer height in inches.

Text size passed to ggplot2::geom_text().

Line width passed to ggplot2::geom_segment().

Arrowhead length in inches.

Whether arrowheads are "closed" or "open".

A plot created by ggforestplot(). Leave as NULL to use + add_forest_table(...) syntax.

Whether to place the table on the left or right of the forest plot.

Optional explicit columns to display in the side table, in the order they should appear. Accepts built-in names such as "term", "group", "n", "events", "estimate", "ci", and "p", arbitrary original dataframe columns, or numeric positions in the supplied data. "conf.low" and "conf.high" are accepted as aliases for "ci". The default grouped table includes "group"; omit it from an explicit selection to hide it. Its header defaults to the source column supplied through ⁠group =⁠ for data frames and to "Model" for bind_forest_models() output.

Deprecated. Use the corresponding entry in column_labels, such as column_labels = c(term = "Variable").

Deprecated. Use column_labels = c(n = "N") instead.

Deprecated. Use column_labels = c(events = "Events") instead.

Header label for the estimate column. Defaults to the model-derived label when available.

Deprecated. Use column_labels = c(p = "P-value") instead.

Optional named vector used to relabel table column headers. Names should match values supplied to columns after column resolution, such as "term", "group", "estimate", "ci", "p", or an arbitrary original dataframe column. For grouped data frames, either "group" or the source column supplied through ⁠group =⁠ can relabel the group column. Use this argument instead of the deprecated dedicated header arguments.

Deprecated. Number of digits used when formatting estimates and p-values. Defaults to 2. Use estimate_digits, interval_digits, and p_digits for separate control.

Number of digits used for point estimates.

Number of digits used for confidence interval bounds.

Number of digits used for p-values.

Format string for the estimate column. Use {estimate}, {conf.low}, and {conf.high} as placeholders. The shorthand ⁠{conf.low, conf.high}⁠ is also supported. Defaults to "{estimate} ({conf.low}, {conf.high})", or "{estimate}" when columns includes "ci".

Format string for the confidence interval column when columns includes "ci". Use {conf.low} and {conf.high} as placeholders. The shorthand ⁠{conf.low, conf.high}⁠ is also supported. Defaults to "({conf.low}, {conf.high})".

Text size for table contents. Defaults to 3.2.

Header text size for table column labels. Defaults to 11.

Font face used for table column labels. Defaults to "bold".

Optional font family used for table column labels.

Whether to draw alternating row stripes behind the table. Defaults to the stripe setting used in ggforestplot().

Fill colour used for striped rows. Defaults to the stripe fill used in ggforestplot().

Outline colour for striped rows. Defaults to the stripe outline used in ggforestplot().

Transparency for striped rows. Defaults to the stripe alpha used in ggforestplot().

Whether to draw black horizontal grid lines in the table.

Colour used for the table grid lines.

Line width used for the table grid lines.

Line type used for the table grid lines.

Optional relative width allocated to the table panel. By default this is calculated from the displayed table content.

Optional relative width allocated to the forest-plot panel. Defaults to 2.4.

A plot created by ggforestplot(). Leave as NULL to use + add_split_table(...) syntax.

Optional explicit columns to place on the left side of the forest plot. Accepts built-in names such as "term", "group", "n", "events", "estimate", "ci", and "p", arbitrary original dataframe columns, or numeric positions in the supplied data. "conf.low" and "conf.high" are accepted as aliases for "ci". The default grouped layout includes "group" on the left. Its header defaults to the source column supplied through ⁠group =⁠ for data frames and to "Model" for bind_forest_models() output.

Optional explicit columns to place on the right side of the forest plot. Accepts built-in names such as "group", "estimate", "ci", and "p", arbitrary original dataframe columns, or numeric positions in the supplied data. "conf.low" and "conf.high" are accepted as aliases for "ci".

Deprecated. Use the corresponding entry in column_labels, such as column_labels = c(term = "Variable").

Deprecated. Use column_labels = c(n = "N") instead.

Deprecated. Use column_labels = c(events = "Events") instead.

Header label for the estimate column. Defaults to the model-derived label when available.

Deprecated. Use column_labels = c(p = "P-value") instead.

Optional named vector used to relabel table column headers. Names should match values supplied to left_columns or right_columns after column resolution, such as "term", "group", "estimate", "ci", "p", or an arbitrary original dataframe column. For grouped data frames, either "group" or the source column supplied through ⁠group =⁠ can relabel the group column. Use this argument instead of the deprecated dedicated header arguments.

Deprecated. Number of digits used when formatting estimates and p-values. Defaults to 2. Use estimate_digits, interval_digits, and p_digits for separate control.

Number of digits used for point estimates.

Number of digits used for confidence interval bounds.

Number of digits used for p-values.

Format string for the estimate column. Use {estimate}, {conf.low}, and {conf.high} as placeholders. The shorthand ⁠{conf.low, conf.high}⁠ is also supported. Defaults to "{estimate} ({conf.low}, {conf.high})", or "{estimate}" when table columns include "ci".

Format string for the confidence interval column when table columns include "ci". Use {conf.low} and {conf.high} as placeholders. The shorthand ⁠{conf.low, conf.high}⁠ is also supported. Defaults to "({conf.low}, {conf.high})".

Text size for table contents. Defaults to 3.2.

Header text size for table column labels. Defaults to 11.

Font face used for table column labels. Defaults to "bold".

Optional font family used for table column labels.

Whether to draw alternating row stripes behind the split table layout. Defaults to the stripe setting used in ggforestplot().

Fill colour used for striped rows. Defaults to the stripe fill used in ggforestplot().

Outline colour for striped rows. Defaults to the stripe outline used in ggforestplot().

Transparency for striped rows. Defaults to the stripe alpha used in ggforestplot().

Optional width allocated to the left table block. By default this is derived from the number of displayed left-side columns relative to plot_width.

Optional width allocated to the forest plot panel. Defaults to 2.5.

Optional width allocated to the right table block. By default this is derived from the number of displayed right-side columns relative to plot_width.

A data frame or data-frame subclass containing coefficient estimates and intervals. Tibbles and data.table objects are supported.

Arguments passed to an as_forest_data() method.

Optional named vector used to relabel displayed terms. Names should match values in the term column and values are the labels to display.

How to sort rows: "none", "descending", or "ascending". Subgroup hierarchies require "none" so their source order is preserved.

Compatibility argument. TRUE is equivalent to estimate_scale = "ratio"; FALSE is equivalent to estimate_scale = "identity" when estimate_scale is not supplied.

Subgroup p-value placement. "overall" displays one omnibus or block-level p-value on the subgroup header; "level" keeps p-values on the individual subgroup estimate rows. For fitted-model methods, this also selects whether p.value contains the omnibus interaction test or the post-estimation test for each derived effect.

Column name holding the model term identifier.

Column name holding the point estimate.

Column name holding the lower confidence bound.

Column name holding the upper confidence bound.

Optional column name used for the displayed row label.

Optional column name used for color-grouping multiple estimates per row. If this column is a factor, its levels control the group legend and vertical dodge order.

Optional column name used to split rows into grouped plot sections.

Optional column name used to identify labeled variable blocks that can be outlined with separator lines.

Optional column name holding sample sizes or other N labels for table helpers.

Optional column name holding event counts or event labels for table helpers.

Optional column name holding p-values.

Semantic scale of the stored estimates. One of "identity", "log", "ratio", "probability", or "risk_difference".

Transformation used for the plotting axis. Defaults to "log10" for ratios and "identity" otherwise.

Short label for the effect measure, such as "Beta", "OR", "HR", "RR", or "RD".

Confidence level represented by the interval columns, or NA when it is unknown.

Numeric null/reference value, or NULL when the effect measure has no universal reference value.

Optional character vector identifying the source model class. The complete fitted model is not retained.

Optional package name identifying the model source.

For data frames, an optional column name defining presentation-only hierarchical subgroup blocks. Missing or empty values identify ordinary standalone estimates. Rows with the same non-empty value must form one contiguous block within each facet. When p.value is mapped, the first nonmissing value for each subgroup and estimate group, when applicable, is displayed on its parent row; child p-value cells are suppressed. Data-frame subgroups are never inferred and do not calculate model contrasts. For fitted-model methods, use "auto" to detect one unambiguous continuous-by-factor interaction, or supply a factor predictor name together with focal to derive covariance-aware post-estimation subgroup effects through marginaleffects. Fitted-model subgroup rows use the canonical p.value column for either the omnibus interaction test or row-level effect tests, according to p_method, so they can share a table column with ordinary coefficient p-values.

Logical; model methods require TRUE because forest data include confidence-interval columns.

Logical; for model methods, whether to retain the intercept term.

For fitted-model methods, the predictor whose conditional effect is estimated within each subgroup level. It may be continuous or a factor. Factor effects compare each non-reference level with the first level. Ignored for data-frame methods.

A non-empty list of fitted model objects supported by an as_forest_data() method.

Optional labels used to identify each model in the forest plot. Defaults to list names when present, otherwise "Model 1", "Model 2", and so on.

NULL, a single logical value, or one logical value per model. NULL uses the canonical scale inferred by as_forest_data() for each model.

Additional arguments passed to as_forest_data(), such as conf.level, intercept, term_labels, or sort_terms.

A forest_data object.

Either a tidy coefficient data frame or a model object supported by broom::tidy().

Column name holding the model term identifiers.

Column name holding the point estimates.

Column name holding the lower confidence bounds.

Column name holding the upper confidence bounds.

Optional column name used for the displayed row labels.

Optional named vector used to relabel displayed terms. Names should match values in the term column and values are the labels to display.

Optional column name used for color-grouping estimates. If this column is a factor, its levels control the group legend and vertical dodge order.

Optional column name used to split rows into faceted plot sections. If this column is a factor, its levels control facet order.

Positioning for facet strip labels.

Optional column name used to identify labeled variable blocks that can be outlined with grid lines.

Optional column name holding sample sizes or other N labels for table helpers.

Optional column name holding event counts or event labels for table helpers.

Optional column name holding p-values.

Logical; if TRUE, transform the estimates and draw the axis on the log scale with the reference line at 1. For model objects, NULL uses the canonical scale when it can be inferred, such as hazard ratios for Cox models.

Confidence level represented by model or data-frame interval columns. Defaults to 0.95.

How to sort rows: "none", "descending", or "ascending". Subgroup hierarchies require "none" so their source order is preserved.

Point size for coefficient markers.

Shape used for coefficient markers.

Line width for confidence intervals.

Deprecated. Use linewidth instead.

Width of the terminal staples on confidence interval lines.

Optional numeric vector of length 2 used to truncate displayed confidence intervals. Intervals extending beyond these limits are clipped to the boundary and marked with arrows when ci_arrows is TRUE.

Logical; if TRUE, draw outward-facing arrows for confidence intervals truncated by ci_limits.

Length of CI truncation arrows in inches.

Arrowhead type for truncated confidence intervals. Passed to grid::arrow().

Horizontal dodging used for grouped estimates.

Logical; if TRUE, draw grid lines around each labeled block identified by separate_groups.

Line type used for separator lines.

Colour used for separator lines.

Line width used for separator lines.

Logical; if TRUE, shade alternating rows.

Fill color used for shaded rows.

Border color for shaded rows.

Transparency for shaded rows.

Numeric x-value where the reference line is drawn, or NULL to hide it. When omitted, the value is taken from the forest_data metadata, such as 0 for additive effects and 1 for ratios.

Optional label drawn alongside the reference line.

Line type for the reference line.

Color for the reference line.

Optional column name defining hierarchical subgroup blocks. Missing or empty values identify ordinary standalone estimates. Each non-empty subgroup must form one contiguous block within a facet. This is a presentation-only mapping; subgroups and contrasts are not inferred. With the default p_method = "overall" forest-data metadata, the first nonmissing p-value for each subgroup and estimate group, when applicable, is displayed on its parent row and child p-value cells are suppressed. p_method = "level" retains p-values on child rows. For fitted models, first call tidy_forest_model() with subgroup, focal, and the desired p_method; direct model calls do not perform post-estimation subgroup inference inside the plotting layer.

Subgroup p-value placement for data-frame input. "overall" displays one p-value on each subgroup header; "level" displays p-values on the subgroup estimate rows. Fitted-model subgroup data inherit this choice from tidy_forest_model().

A fitted model object supported by broom::tidy() or, for mixed models, a broom.mixed tidy method.

Logical; if TRUE, request confidence intervals from broom::tidy().

Confidence level for intervals.

NULL uses the model's conventional coefficient scale, such as odds ratios for logistic models and hazard ratios for Cox models. TRUE or FALSE overrides that behavior.

Logical; if FALSE, drop the intercept term.

Optional named vector used to relabel displayed terms. Names should match model term names and values are the labels to display.

How to sort rows: "none", "descending", or "ascending".

NULL for ordinary coefficient rows, "auto" to detect one unambiguous continuous-by-factor interaction, or the name of a factor defining subgroup levels. Explicit selection also requires focal.

Optional predictor whose conditional effect is estimated within each subgroup level. It may be continuous or a factor. For factors, each non-reference level is contrasted with the first factor level.

Subgroup p-value method. "overall" uses an omnibus Wald test of the selected interaction on the subgroup header. "level" uses the test returned for each subgroup-specific slope or comparison.