% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multiforest.R
\name{multiforest}
\alias{multiforest}
\title{Create Forest Plot for Multivariate Regression}
\usage{
multiforest(
  x,
  title = "Multivariate Analysis",
  effect_label = NULL,
  column = "adjusted",
  digits = 2,
  p_digits = 3,
  conf_level = 0.95,
  font_size = 1,
  annot_size = 3.88,
  header_size = 5.82,
  title_size = 23.28,
  plot_width = NULL,
  plot_height = NULL,
  table_width = 0.6,
  show_n = TRUE,
  show_events = NULL,
  show_predictor = NULL,
  covariates_footer = TRUE,
  indent_predictor = FALSE,
  bold_variables = TRUE,
  center_padding = 4,
  zebra_stripes = TRUE,
  color = NULL,
  null_line = NULL,
  log_scale = NULL,
  labels = NULL,
  units = "in",
  number_format = NULL
)
}
\arguments{
\item{x}{Multifit result object (data.table with class attributes from 
\code{multifit()}).}

\item{title}{Character string specifying the plot title. Default is 
\code{"Multivariate Analysis"}. Use descriptive titles for publication.}

\item{effect_label}{Character string for the effect measure label on the 
forest plot axis. Default is \code{NULL}, which auto-detects based on 
model type (\emph{e.g.,} "Odds Ratio", "Hazard Ratio", "Rate Ratio", "Estimate").}

\item{column}{Character string specifying which results to plot when
\code{multifit()} was called with \code{columns = "both"}. Options are
\code{"adjusted"} (default) or \code{"unadjusted"}. Ignored when the
\code{multifit} result contains only one column type.}

\item{digits}{Integer specifying the number of decimal places for effect 
estimates and confidence intervals. Default is 2.}

\item{p_digits}{Integer specifying the number of decimal places for
\emph{p}-values. Values smaller than \code{10^(-p_digits)} are displayed
as \code{"< 0.001"} (for \code{p_digits = 3}), \code{"< 0.0001"} (for
\code{p_digits = 4}), etc. Default is 3.}

\item{conf_level}{Numeric confidence level for confidence intervals. Must be
between 0 and 1. Default is 0.95 (95\% confidence intervals). The CI
percentage is automatically displayed in column headers (\emph{e.g.,} "90\% CI"
when \code{conf_level = 0.90}).}

\item{font_size}{Numeric multiplier controlling the base font size for all 
text elements. Default is 1.0.}

\item{annot_size}{Numeric value controlling the relative font size for data 
annotations. Default is 3.88.}

\item{header_size}{Numeric value controlling the relative font size for column 
headers. Default is 5.82.}

\item{title_size}{Numeric value controlling the relative font size for the 
main plot title. Default is 23.28.}

\item{plot_width}{Numeric value specifying the intended output width in 
specified \code{units}. Used for optimizing layout. Default is \code{NULL} 
(automatic). Recommended: 10-16 inches.}

\item{plot_height}{Numeric value specifying the intended output height in 
specified \code{units}. Default is \code{NULL} (automatic based on number 
of rows).}

\item{table_width}{Numeric value between 0 and 1 specifying the proportion of 
total plot width allocated to the data table. Default is 0.6 (60\% table, 
40\% forest plot).}

\item{show_n}{Logical. If \code{TRUE}, includes a column showing sample sizes.
Counts describe the observations used in fitting rather than every row
supplied. Default is \code{TRUE}.}

\item{show_events}{Logical. If \code{TRUE}, includes a column showing the 
number of events for each row. Default is \code{TRUE} for binomial and 
survival models, \code{FALSE} for linear models.}

\item{show_predictor}{Logical. If \code{TRUE}, includes the "Predictor" column 
showing which level of a factor predictor is being compared. If \code{FALSE},
omits the column (useful when predictor info is in the caption). Default is 
\code{NULL}, which uses the \code{include_predictor} setting from
\code{multifit()} if available, otherwise \code{TRUE}.}

\item{covariates_footer}{Logical. If \code{TRUE} (default), displays a footer
listing the covariates used in adjusted models. Covariate names are formatted
using the \code{labels} parameter if provided. Only shown when displaying
adjusted results.}

\item{indent_predictor}{Logical. If \code{TRUE}, indents predictor levels
under outcome names, creating a hierarchical display. If \code{FALSE} 
(default), shows outcome and predictor level in separate columns.}

\item{bold_variables}{Logical. If \code{TRUE}, variable names are displayed
in bold. If \code{FALSE} (default), variable names are displayed in plain
text.}

\item{center_padding}{Numeric value specifying horizontal spacing between 
table and forest plot. Default is 4.}

\item{zebra_stripes}{Logical. If \code{TRUE}, applies alternating gray 
background shading to different outcomes for improved readability. 
Default is \code{TRUE}.}

\item{color}{Character string specifying the color for point estimates in 
the forest plot. Default is \code{NULL}, which auto-selects based on
effect type: purple (\code{"#8A61D8"}) for hazard ratios (Cox), teal 
(\code{"#4BA6B6"}) for odds ratios (logistic), blue (\code{"#3F87EE"}) for 
rate/risk ratios (Poisson, Gamma, \emph{etc.}), and green (\code{"#5A8F5A"}) for 
coefficients (linear models).
Use hex codes or R color names for custom colors.}

\item{null_line}{Numeric value for the reference line position. Default is 
\code{NULL}, which uses 1 for ratio measures (OR, HR, RR) and 0 for 
coefficients.}

\item{log_scale}{Logical. If \code{TRUE}, uses log scale for the x-axis.
Default is \code{NULL}, which auto-detects (\code{TRUE} for OR/HR/RR, \code{FALSE} for
coefficients).}

\item{labels}{Named character vector providing custom display labels for 
outcomes and variables. Applied to outcome names in the plot.
Default is \code{NULL}, in which case the labels attached by
\code{multifit()} are used. Original names are used where neither is
available.}

\item{units}{Character string specifying units for plot dimensions: 
\code{"in"} (inches), \code{"cm"}, or \code{"mm"}. Default is \code{"in"}.}

\item{number_format}{Character string or two-element character vector
  controlling thousand and decimal separators in formatted output. Named
  presets:
  \itemize{
    \item \code{"us"} - Comma thousands, period decimal: \code{1,234.56} [default]
    \item \code{"eu"} - Period thousands, comma decimal: \code{1.234,56}
    \item \code{"space"} - Thin-space thousands, period decimal: \code{1 234.56}
      (SI/ISO 31-0)
    \item \code{"none"} - No thousands separator: \code{1234.56}
  }
  Or provide a custom two-element vector \code{c(big.mark, decimal.mark)},
  \emph{e.g.}, \code{c("'", ".")} for Swiss-style: \verb{1'234.56}.

  When \code{NULL} (default), uses
  \code{getOption("summata.number_format", "us")}. Set the global option
  once per session to avoid passing this argument repeatedly:
  \preformatted{
    options(summata.number_format = "eu")
  }}
}
\value{
A \code{ggplot} object containing the complete forest plot. The plot 
  can be:
  \itemize{
    \item Displayed directly: \code{print(plot)}
    \item Saved to file: \code{forestsave(plot, "forest.pdf")}
    \item Further customized with \pkg{ggplot2} functions
  }
  
  The returned object includes an attribute \code{"rec_dims"} 
  accessible via \code{attr(plot, "rec_dims")}, which is a list 
  containing:
  \describe{
    \item{width}{Numeric. Recommended plot width in specified units}
    \item{height}{Numeric. Recommended plot height in specified units}
    \item{units}{Character. The units the dimensions are expressed in,
      matching the \code{units} argument}
  }
  
  These recommendations are automatically calculated based on the number of 
  variables, text sizes, and layout parameters, and are printed to console 
  if \code{plot_width} or \code{plot_height} are not specified.
  \code{forestsave()} reads all three and requires no further handling.

  The returned object also includes an attribute \code{"table_data"}
  accessible via \code{attr(plot, "table_data")}, a data.table holding the
  values drawn in the plot, in the order of the model terms. Sample sizes
  and event counts describe the observations used in fitting rather than
  every row supplied.
}
\description{
Generates a publication-ready forest plot from a \code{multifit()} output
object. The plot displays effect estimates (OR, HR, RR, or coefficients) with
confidence intervals across multiple outcomes, organized by outcome with the
predictor levels shown for each.
}
\details{
\strong{Plot Layout:}

The forest plot is organized with outcomes as grouping headers and predictor
levels (or interaction terms) as rows within each outcome. This provides a
clear visual comparison of how a single predictor affects multiple outcomes.

\enumerate{
  \item \strong{Title}: Centered at top
  \item \strong{Data Table} (left): Contains:
    \itemize{
      \item Outcome column (or grouped headers)
      \item Predictor/Group column
      \item n: Sample sizes (optional)
      \item Events: Event counts (optional, for applicable models)
      \item Effect (95\% CI); \emph{p}-value
    }
  \item \strong{Forest Plot} (right):
    \itemize{
      \item Point estimates (squares)
      \item 95\% confidence intervals
      \item Reference line at null value (1 or 0)
      \item Log scale for ratio measures
    }
}

\strong{Data Source:}

The function extracts effect estimates directly from the multifit output
object's \code{raw_data} attribute, which contains the numeric values
needed for plotting. This approach is efficient and ensures consistency
with the formatted table output.
}
\examples{
data(clintrial)
data(clintrial_labels)
library(survival)

# Create example multifit result
result <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    parallel = FALSE
)

# Example 1: Basic multivariate forest plot
p <- multiforest(result)

\donttest{

old_width <- options(width = 180)

# Example 2: With custom title and labels
plot2 <- multiforest(
    result,
    title = "Treatment Effects Across Clinical Outcomes",
    labels = clintrial_labels
)

# Example 3: Customize appearance
plot3 <- multiforest(
    result,
    color = "#E74C3C",
    zebra_stripes = TRUE,
    labels = clintrial_labels
)

# Example 4: Save with recommended dimensions
forestsave(plot3, file.path(tempdir(), "multioutcome_forest.pdf"))

options(old_width)

}
}
\seealso{
\code{\link{autoforest}} for automatic model detection,
\code{\link{multifit}} for multi-outcome regression analysis,
\code{\link{glmforest}} for single GLM forest plots,
\code{\link{coxforest}} for single Cox model forest plots,
\code{\link{lmforest}} for single linear model forest plots,
\code{\link{uniforest}} for univariable screening forest plots,
  \code{\link{forestsave}} for saving with recommended dimensions

Other visualization functions:
\code{\link[=autoforest]{autoforest()}},
\code{\link[=coxforest]{coxforest()}},
\code{\link[=forestsave]{forestsave()}},
\code{\link[=glmforest]{glmforest()}},
\code{\link[=lmforest]{lmforest()}},
\code{\link[=recdims]{recdims()}},
\code{\link[=uniforest]{uniforest()}}
}
\concept{visualization functions}
