% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/autoforest.R
\name{autoforest}
\alias{autoforest}
\title{Create Forest Plot with Automatic Model Detection}
\usage{
autoforest(x, data = NULL, title = NULL, ...)
}
\arguments{
\item{x}{One of the following:
\itemize{
  \item A fitted model object: \code{glm}, \code{lm}, \code{coxph}, \emph{etc.}
  \item A \code{fit_result} object from \code{fit()}
  \item A \code{fullfit_result} object from \code{fullfit()}
  \item A \code{uniscreen_result} object from \code{uniscreen()}
  \item A \code{multifit_result} object from \code{multifit()}
}}

\item{data}{Data frame or data.table containing the original data. Required 
when \code{x} is a raw model object. Ignored when \code{x} is a result object
from \code{fit()}, \code{fullfit()}, \code{uniscreen()}, or \code{multifit()}
since these contain embedded data.}

\item{title}{Character string for plot title. If \code{NULL} (default), an 
appropriate title is generated based on the detected model type:
\itemize{
  \item Cox models: "Cox Proportional Hazards Model"
  \item Logistic regression: "Logistic Regression Model"
  \item Poisson regression: "Poisson Regression Model"
  \item Linear regression: "Linear Regression Model"
  \item Uniscreen results: "Univariable [Type] Screening"
  \item Multifit results: "Multivariate [Type] Analysis"
}}

\item{...}{Additional arguments passed to the specific forest plot function.
Common arguments include:
\describe{
  \item{labels}{Named character vector for variable labels}
  \item{digits}{Number of decimal places for estimates (default 2)}
  \item{p_digits}{Number of decimal places for \emph{p}-values (default 3)}
  \item{conf_level}{Confidence level for intervals (default 0.95)}
  \item{show_n}{Logical, show sample sizes (default \code{TRUE})}
  \item{show_events}{Logical, show event counts (default \code{TRUE} for survival/binomial)}
  \item{qc_footnote}{Logical, show model QC stats in footer (default \code{TRUE})}
  \item{zebra_stripes}{Logical, alternating row shading (default \code{TRUE})}
  \item{indent_groups}{Logical, indent factor levels (default \code{FALSE})}
  \item{color}{Color for point estimates}
  \item{table_width}{Proportion of width for table (default 0.6)}
  \item{plot_width, plot_height}{Explicit dimensions}
  \item{units}{Dimension units: \code{"in"}, \code{"cm"}, or \code{"mm"}}
}
See the documentation for the specific forest function for all available options.}
}
\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}
  }
  
  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.
}
\description{
A convenience wrapper function that automatically detects the input type and
routes to the appropriate specialized forest plot function. This eliminates
the need to remember which forest function to call for different model types
or analysis objects, making it ideal for exploratory analysis and rapid prototyping.
}
\details{
This function provides a convenient wrapper around the specialized forest
plot functions, automatically routing to the appropriate function based on
the model class or result type. All parameters are passed through to the
underlying function, so the full range of options remains available.

For model-specific advanced features, individual forest functions may be
called directly.

\strong{Automatic Detection Logic:}

The function uses the following priority order for detection:
\enumerate{
  \item \strong{uniscreen results}: Detected by class \code{"uniscreen_result"} or
    presence of attributes \code{outcome}, \code{predictors}, \code{model_type},
    and \code{model_scope = "Univariable"}. Routes to \code{uniforest()}.
  \item \strong{multifit results}: Detected by presence of attributes 
    \code{predictor}, \code{outcomes}, \code{model_type}, and \code{raw_data}.
    Routes to \code{multiforest()}.
  \item \strong{Cox models}: Classes \code{coxph} or \code{clogit}. Routes to 
    \code{coxforest()}.
  \item \strong{GLM models}: Class \code{glm}. Routes to \code{glmforest()}.
  \item \strong{Linear models}: Class \code{lm} (but not \code{glm}). Routes to 
    \code{lmforest()}.
}
}
\examples{
data(clintrial)
data(clintrial_labels)
library(survival)

# Create example model
glm_model <- glm(surgery ~ age + sex + bmi + smoking,
                 family = binomial, data = clintrial)

# Example 1: Logistic regression model
p <- autoforest(glm_model, data = clintrial)
# Automatically detects GLM and routes to glmforest()

\donttest{

# Example 2: Cox proportional hazards model
cox_model <- coxph(Surv(os_months, os_status) ~ age + sex + treatment + stage,
                   data = clintrial)

plot2 <- autoforest(cox_model, data = clintrial)
# Automatically detects coxph and routes to coxforest()

# Example 3: Linear regression model
lm_model <- lm(biomarker_x ~ age + sex + bmi + treatment, data = clintrial)

plot3 <- autoforest(lm_model, data = clintrial)
# Automatically detects lm and routes to lmforest()

# Example 4: With custom labels and formatting options
plot4 <- autoforest(
    cox_model,
    data = clintrial,
    labels = clintrial_labels,
    title = "Prognostic Factors for Overall Survival",
    zebra_stripes = TRUE,
    indent_groups = TRUE
)

# Example 5: From fit() result - data and labels extracted automatically
fit_result <- fit(
    data = clintrial,
    outcome = "surgery",
    predictors = c("age", "sex", "bmi", "treatment"),
    labels = clintrial_labels
)

plot5 <- autoforest(fit_result)

# Save with recommended dimensions
forestsave(plot5, file.path(tempdir(), "forest.pdf"))

}
}
\seealso{
\code{\link{glmforest}} for GLM forest plots,
\code{\link{coxforest}} for Cox model forest plots,
\code{\link{lmforest}} for linear model forest plots,
\code{\link{uniforest}} for univariable screening forest plots,
\code{\link{multiforest}} for multi-outcome forest plots,
\code{\link{fit}} for single-model regression,
\code{\link{fullfit}} for combined univariable/multivariable regression,
\code{\link{uniscreen}} for univariable screening,
\code{\link{multifit}} for multi-outcome analysis,
  \code{\link{forestsave}} for saving with recommended dimensions

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