% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/uniforest.R
\name{uniforest}
\alias{uniforest}
\title{Create Forest Plot for Univariable Screening}
\usage{
uniforest(
  x,
  title = "Univariable Screening",
  effect_label = NULL,
  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,
  indent_groups = FALSE,
  condense_table = FALSE,
  bold_variables = FALSE,
  center_padding = 4,
  zebra_stripes = TRUE,
  color = NULL,
  null_line = NULL,
  log_scale = NULL,
  labels = NULL,
  show_footer = TRUE,
  units = "in",
  number_format = NULL
)
}
\arguments{
\item{x}{Univariable screen result object (data.table with class attributes
from \code{uniscreen()}).}

\item{title}{Character string specifying the plot title. Default is 
\code{"Univariable Screening"}. 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", "Coefficient").}

\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}). Note: This parameter affects display only;
the underlying CIs come from the uniscreen result.}

\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{NULL}, which auto-detects
based on model type (\code{TRUE} for binomial/survival, \code{FALSE} for linear).}

\item{indent_groups}{Logical. If \code{TRUE}, indents factor levels
under their parent variable name, creating a hierarchical display. If 
\code{FALSE} (default), shows variable and level in separate columns.}

\item{condense_table}{Logical. If \code{TRUE}, condenses binary categorical 
variables into single rows by showing only the non-reference category. 
Automatically sets \code{indent_groups = TRUE}. Useful for tables with 
many binary variables. Default is \code{FALSE}.}

\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 variables 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 
variables. Applied to predictor names in the plot.
Default is \code{NULL}, in which case the labels attached by the function
that produced \code{x} are used where \code{x} is a \pkg{summata} result
rather than a model object, so that labels supplied once are carried
through the workflow. Original variable names are used where neither is
available.}

\item{show_footer}{Logical. If \code{TRUE}, displays a footer with the
outcome variable name. Default is \code{TRUE}.}

\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{uniscreen()} output
object. The plot displays effect estimates (OR, HR, RR, or coefficients) with
confidence intervals for each predictor tested in univariable analysis against
a single outcome.
}
\details{
The forest plot displays univariable (unadjusted) associations between each
predictor and the outcome. This is useful for:
\itemize{
  \item Visualizing results of initial variable screening
  \item Identifying potential predictors for multivariable modeling
  \item Presenting crude associations alongside adjusted results
  \item Quick visual assessment of effect sizes and significance
}

The plot automatically handles:
\itemize{
  \item Different effect types (OR, HR, RR, coefficients) with appropriate
    axis scaling (log vs linear)
  \item Factor variables with multiple levels (grouped under variable name)
  \item Continuous variables (single row per predictor)
  \item Reference categories for categorical variables
}
}
\examples{
data(clintrial)
data(clintrial_labels)

# Create example uniscreen result
uni_results <- uniscreen(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "smoking", "treatment", "stage"),
    labels = clintrial_labels,
    parallel = FALSE
)

# Example 1: Basic univariable forest plot
p <- uniforest(uni_results, title = "Univariable Associations with Mortality")

\donttest{

old_width <- options(width = 180)

# Example 2: Survival analysis
library(survival)
surv_results <- uniscreen(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "sex", "treatment", "stage"),
    model_type = "coxph",
    labels = clintrial_labels,
    parallel = FALSE
)

# Labels attached by uniscreen() are applied automatically
p2 <- uniforest(surv_results, title = "Univariable Survival Analysis")

# Example 3: Linear regression
lm_results <- uniscreen(
    data = clintrial,
    outcome = "los_days",
    predictors = c("age", "sex", "surgery", "diabetes"),
    model_type = "lm",
    labels = clintrial_labels,
    parallel = FALSE
)

p3 <- uniforest(lm_results, title = "Predictors of Length of Stay")

# Example 4: Customize appearance
p4 <- uniforest(
    uni_results,
    title = "Crude Associations with Mortality",
    color = "#E74C3C",
    indent_groups = TRUE,
    zebra_stripes = TRUE,
    bold_variables = TRUE
)

# Example 5: Save with recommended dimensions
forestsave(p4, file.path(tempdir(), "univariable_forest.pdf"))

options(old_width)

}
}
\seealso{
\code{\link{autoforest}} for automatic model detection,
\code{\link{uniscreen}} for generating univariable screening results,
\code{\link{multiforest}} for multi-outcome forest plots,
\code{\link{coxforest}}, \code{\link{glmforest}}, \code{\link{lmforest}} for
single-model 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[=multiforest]{multiforest()}},
\code{\link[=recdims]{recdims()}}
}
\concept{visualization functions}
