% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/m2dt.R
\name{m2dt}
\alias{m2dt}
\title{Convert Model to Data Table}
\usage{
m2dt(
  data,
  model,
  conf_level = 0.95,
  keep_qc_stats = TRUE,
  include_intercept = TRUE,
  terms_to_exclude = NULL,
  reference_rows = TRUE,
  reference_label = "reference",
  skip_counts = FALSE,
  conf_method = NULL
)
}
\arguments{
\item{data}{Data frame or data.table containing the dataset used to fit the
model. Required for computing group-level sample sizes and event counts.
Where the fitted object retains no model frame, the supplied data is
restricted to complete cases across the model variables so that group-level
sample sizes describe the observations actually used in fitting. Group
sample sizes therefore sum to the model-level \code{n}, and both exclude
observations with a missing response.}

\item{model}{Fitted model object. Supported classes include:
\itemize{
  \item \code{glm} - Generalized linear models (logistic, Poisson, \emph{etc.})
  \item \code{lm} - Linear models
  \item \code{coxph} - Cox proportional hazards models
  \item \code{clogit} - Conditional logistic regression
  \item \code{coxme} - Mixed effects Cox models
  \item \code{lmerMod} - Linear mixed effects models
  \item \code{glmerMod} - Generalized linear mixed effects models
}}

\item{conf_level}{Numeric confidence level for confidence intervals. Must be
between 0 and 1. Default is 0.95 (95\% CI).}

\item{keep_qc_stats}{Logical. If \code{TRUE}, includes model quality statistics 
such as AIC, BIC, \emph{R}\eqn{^2}, concordance, and model fit tests. These appear 
as additional columns in the output. Default is \code{TRUE}.}

\item{include_intercept}{Logical. If \code{TRUE}, includes the model intercept 
in output. If \code{FALSE}, removes the intercept row from results. Useful 
for creating cleaner presentation tables. Default is \code{TRUE}.}

\item{terms_to_exclude}{Character vector of term names to exclude from output.
Useful for removing specific unwanted parameters (\emph{e.g.,} nuisance variables,
spline terms). Default is \code{NULL}. Note: If \code{include_intercept = FALSE}, 
"(Intercept)" is automatically added to this list.}

\item{reference_rows}{Logical. If \code{TRUE}, adds rows for reference 
categories of factor variables with appropriate labels and baseline values 
(OR/HR = 1, Coefficient = 0). This makes tables more complete and easier to 
interpret. Default is \code{TRUE}.}

\item{reference_label}{Character string used to label reference category rows
in the output. Appears in the \code{reference} column. Default is \code{"reference"}.}

\item{skip_counts}{Logical. If \code{TRUE}, skips computation of group-level
sample sizes and event counts (faster but less informative). Default is 
\code{FALSE}.}

\item{conf_method}{Character string controlling the confidence interval method.
If \code{NULL} (default), uses \code{getOption("summata.conf_method", "profile")}.
\itemize{
  \item \code{"profile"} - Profile likelihood intervals for GLM and negative
    binomial models (via \code{MASS::confint.glm()}), exact \emph{t}-distribution
    intervals for linear models. Falls back to Wald on profiling failure.
    Quasi-likelihood families always use Wald (no true likelihood).
  \item \code{"wald"} - Wald intervals (coefficient \eqn{\pm} \emph{z}
    \eqn{\times} SE) for all model types. Faster but less accurate near
    boundary conditions or with small subgroups.
}
Cox and mixed-effects models use Wald intervals regardless of this setting.
Set globally with \code{options(summata.conf_method = "wald")} to use Wald
throughout a session.}
}
\value{
A \code{data.table} containing extracted model information with the 
  following standard columns:
  \describe{
    \item{model_scope}{Character. Either "Univariable" (unadjusted model with 
      single predictor) or "Multivariable" (adjusted model with multiple predictors)}
    \item{model_type}{Character. Type of regression (\emph{e.g.,} "Logistic", "Linear", 
      "Cox PH", "Poisson", \emph{etc.})}
    \item{variable}{Character. Variable name (for factor variables, the base 
      variable name without the level)}
    \item{group}{Character. Group/level name for factor variables; empty string 
      for continuous variables}
    \item{n}{Integer. Number of observations used in fitting the model, that
      is complete cases across the model variables}
    \item{n_group}{Integer. Number of those observations at this variable
      level (factor variables only). Group sizes sum to \code{n} within
      each variable}
    \item{events}{Integer. Number of events among the observations used in
      fitting (for survival and logistic models)}
    \item{events_group}{Integer. Number of events at this variable level
      (for survival and logistic models with factor variables). Group counts
      sum to \code{events} within each variable}
    \item{coefficient}{Numeric. Raw regression coefficient (log odds, log hazard, 
      \emph{etc.})}
    \item{se}{Numeric. Standard error of the coefficient}
    \item{OR/HR/RR/Coefficient}{Numeric. Effect estimate - column name depends on 
      model type:
      \itemize{
        \item \code{OR} for logistic regression (odds ratio)
        \item \code{HR} for Cox models (hazard ratio)
        \item \code{RR} for Poisson regression (rate/risk ratio)
        \item \code{Coefficient} for linear models or other GLMs
      }}
    \item{ci_lower}{Numeric. Lower bound of confidence interval for effect estimate}
    \item{ci_upper}{Numeric. Upper bound of confidence interval for effect estimate}
    \item{statistic}{Numeric. Test statistic (z-value for GLM/Cox, t-value for LM)}
    \item{p_value}{Numeric. \emph{p}-value for coefficient test}
    \item{sig}{Character. Significance markers: \code{***} (p < 0.001), \code{**}
      (\emph{p} < 0.01), \code{*} (\emph{p} < 0.05), \code{.} (\emph{p} < 0.10).}
    \item{sig_binary}{Logical. Binary indicator: \code{TRUE} if \emph{p} < 0.05, 
      \code{FALSE} otherwise}
    \item{reference}{Character. Contains \code{reference_label} for reference 
      category rows when \code{reference_rows = TRUE}, empty string otherwise}
  }
}
\description{
Extracts coefficients, confidence intervals, and comprehensive model statistics 
from fitted regression models and converts them to a standardized data.table 
format suitable for further analysis or publication. This is a core utility 
function frequently used internally by other \pkg{summata} regression functions,
although it can be used as a standalone function as well.
}
\details{
This function is the core extraction utility used by \code{fit()} and other
regression functions. It handles the complexities of different model classes
and provides a consistent output format suitable for tables and forest plots.

\strong{Model Type Detection:}
The function automatically detects model type and applies appropriate:
\itemize{
  \item Effect measure naming (OR, HR, RR, Coefficient)
  \item Confidence interval calculation (see below)
  \item Event counting for binary/survival outcomes
}

\strong{Confidence Interval Methods:}
The CI method is selected per model class using \code{stats::confint()}
dispatch:
\itemize{
  \item \strong{GLM/negative binomial}: Profile likelihood via
    \code{MASS::confint.glm()}, except quasi-families which use Wald
  \item \strong{Linear models}: Exact \emph{t}-distribution via
    \code{confint.lm()}
  \item \strong{Cox PH}: Wald intervals (coefficient \eqn{\pm}
    \emph{z} \eqn{\times} SE)
  \item \strong{Mixed-effects models}: Wald intervals
}
Falls back to Wald on profiling failure.

\strong{Mixed Effects Models:}
For \pkg{lme4} models (glmer, lmer), the function extracts fixed effects
only. Random effects variance components are not included in the output
table, as they represent clustering structure rather than predictor effects.
}
\examples{
# Load example data
data(clintrial)

# Example 1: Extract from logistic regression
glm_model <- glm(os_status ~ age + sex + treatment, 
                 data = clintrial, family = binomial)

glm_result <- m2dt(clintrial, glm_model)
glm_result

\donttest{

# Example 2: Extract from linear model
lm_model <- lm(los_days ~ age + sex + surgery, data = clintrial)

lm_result <- m2dt(clintrial, lm_model)
lm_result

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

cox_result <- m2dt(clintrial, cox_model)
cox_result

# Example 4: Exclude intercept for cleaner tables
clean_result <- m2dt(clintrial, glm_model, include_intercept = FALSE)
clean_result

# Example 5: Change confidence level
result_90ci <- m2dt(clintrial, glm_model, conf_level = 0.90)
result_90ci

}

}
\seealso{
\code{\link{fit}} for the main regression interface,
\code{\link{glmforest}}, \code{\link{coxforest}}, \code{\link{lmforest}} for
forest plot visualization
}
\concept{utility functions}
