% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table_continuous_lm.R
\name{table_continuous_lm}
\alias{table_continuous_lm}
\title{Continuous-outcome linear-model table}
\usage{
table_continuous_lm(
  data,
  select = tidyselect::everything(),
  by,
  exclude = NULL,
  regex = FALSE,
  weights = NULL,
  vcov = c("classical", "HC0", "HC1", "HC2", "HC3", "HC4", "HC4m", "HC5"),
  contrast = c("auto", "none"),
  statistic = FALSE,
  p_value = TRUE,
  show_n = TRUE,
  show_weighted_n = FALSE,
  effect_size = c("none", "f2"),
  r2 = c("r2", "adj_r2", "none"),
  ci = TRUE,
  labels = NULL,
  ci_level = 0.95,
  digits = 2,
  fit_digits = 2,
  effect_size_digits = 2,
  decimal_mark = ".",
  output = c("default", "data.frame", "long", "tinytable", "gt", "flextable", "excel",
    "clipboard", "word"),
  excel_path = NULL,
  excel_sheet = "Linear models",
  clipboard_delim = "\\t",
  word_path = NULL,
  verbose = FALSE
)
}
\arguments{
\item{data}{A \code{data.frame}.}

\item{select}{Outcome columns to include. If \code{regex = FALSE}, use tidyselect
syntax or a character vector of column names (default:
\code{tidyselect::everything()}). If \code{regex = TRUE}, provide a regular expression
pattern (character string).}

\item{by}{A single predictor column. Accepts an unquoted column name or a
single character column name. The predictor can be numeric, logical,
character, or factor.}

\item{exclude}{Columns to exclude from \code{select}. Supports tidyselect syntax
and character vectors of column names.}

\item{regex}{Logical. If \code{FALSE} (the default), uses tidyselect helpers. If
\code{TRUE}, the \code{select} argument is treated as a regular expression.}

\item{weights}{Optional case weights. Accepts \code{NULL}, an unquoted numeric
column name, a single character column name, or a numeric vector of length
\code{nrow(data)}.}

\item{vcov}{Variance estimator used for uncertainty estimates. One of
\code{"classical"} (default), \code{"HC0"}, \code{"HC1"}, \code{"HC2"}, \code{"HC3"}, \code{"HC4"},
\code{"HC4m"}, or \code{"HC5"}.}

\item{contrast}{Contrast display for categorical predictors. One of:
\itemize{
\item \code{"auto"}: show a single reference contrast only when \code{by} has exactly
two levels.
\item \code{"none"}: suppress difference columns for categorical predictors.
}}

\item{statistic}{Logical. If \code{TRUE}, includes a test-statistic column in the
wide and rendered outputs. Defaults to \code{FALSE}.}

\item{p_value}{Logical. If \code{TRUE}, includes a \code{p} column in the wide and
rendered outputs. Defaults to \code{TRUE}.}

\item{show_n}{Logical. If \code{TRUE}, includes an unweighted \code{n} column in the
wide and rendered outputs. Defaults to \code{TRUE}.}

\item{show_weighted_n}{Logical. If \code{TRUE} and \code{weights} is supplied,
includes a \verb{Weighted n} column equal to the sum of case weights in the
analytic sample. Defaults to \code{FALSE}.}

\item{effect_size}{Character. Effect-size column to include in the wide and
rendered outputs. One of \code{"none"} (the default) or \code{"f2"}.}

\item{r2}{Character. Fit statistic to include in the wide and rendered
outputs. One of \code{"r2"} (the default), \code{"adj_r2"}, or \code{"none"}.}

\item{ci}{Logical. If \code{TRUE}, includes contrast confidence-interval columns
in the wide and rendered outputs when a single contrast is shown.
Defaults to \code{TRUE}.}

\item{labels}{An optional named character vector of outcome labels. Names
must match column names in \code{data}. When \code{NULL} (the default), labels are
auto-detected from variable attributes; if none are found, the column name
is used.}

\item{ci_level}{Confidence level for coefficient and model-based mean
intervals (default: \code{0.95}). Must be between 0 and 1 exclusive.}

\item{digits}{Number of decimal places for descriptive values, regression
coefficients, and test statistics (default: \code{2}).}

\item{fit_digits}{Number of decimal places for model-fit columns (\code{R2} or
adjusted \code{R2}) in wide and rendered outputs (default: \code{2}).}

\item{effect_size_digits}{Number of decimal places for effect-size columns
(\code{f2}) in wide and rendered outputs (default: \code{2}).}

\item{decimal_mark}{Character used as decimal separator. Either \code{"."}
(default) or \code{","}.}

\item{output}{Output format. One of:
\itemize{
\item \code{"default"}: a printed ASCII table, returned invisibly
\item \code{"data.frame"}: a plain wide \code{data.frame}
\item \code{"long"}: a raw long \code{data.frame}
\item \code{"tinytable"} (requires \code{tinytable})
\item \code{"gt"} (requires \code{gt})
\item \code{"flextable"} (requires \code{flextable})
\item \code{"excel"} (requires \code{openxlsx2})
\item \code{"clipboard"} (requires \code{clipr})
\item \code{"word"} (requires \code{flextable} and \code{officer})
}}

\item{excel_path}{File path for \code{output = "excel"}.}

\item{excel_sheet}{Sheet name for \code{output = "excel"} (default:
\code{"Linear models"}).}

\item{clipboard_delim}{Delimiter for \code{output = "clipboard"} (default:
\code{"\\t"}).}

\item{word_path}{File path for \code{output = "word"}.}

\item{verbose}{Logical. If \code{TRUE}, prints messages about ignored
non-numeric selected outcomes (default: \code{FALSE}).}
}
\value{
Depends on \code{output}:
\itemize{
\item \code{"default"}: prints a styled ASCII table and returns the
underlying long \code{data.frame} invisibly, with class
\code{"spicy_continuous_lm_table"}.
\item \code{"data.frame"}: a plain wide \code{data.frame} with one row per outcome
and numeric columns for means, optional contrasts, optional test
statistics, model fit, and sample size.
\item \code{"long"}: a raw \code{data.frame} with one block per outcome and columns
describing estimated means, contrasts, test statistics, model fit, and
sample size.
\item \code{"tinytable"}: a \code{tinytable} object.
\item \code{"gt"}: a \code{gt_tbl} object.
\item \code{"flextable"}: a \code{flextable} object.
\item \code{"excel"} / \code{"word"}: writes to disk and returns the file path.
\item \code{"clipboard"}: copies the wide table and returns it invisibly.
}

If no numeric outcome columns remain after applying \code{select}, \code{exclude},
and \code{regex}, the function emits a warning and returns an empty
\code{data.frame()} regardless of \code{output}.
}
\description{
Builds APA-style summary tables from a series of simple linear models for
one or many continuous outcomes selected with tidyselect syntax.

A single predictor is supplied with \code{by}, and each selected numeric
outcome is fit as \code{lm(outcome ~ by, ...)}. When \code{by} is categorical, the
function returns a model-based mean-comparison table with fitted means by
level derived from the linear model, plus an optional single difference for
dichotomous predictors. When \code{by} is numeric, the table reports the slope
and its confidence interval.

Multiple output formats are available via \code{output}: a printed ASCII table
(\code{"default"}), a plain wide \code{data.frame} (\code{"data.frame"}), a raw long
\code{data.frame} (\code{"long"}), or rendered outputs (\code{"tinytable"}, \code{"gt"},
\code{"flextable"}, \code{"excel"}, \code{"clipboard"}, \code{"word"}).
}
\details{
\code{table_continuous_lm()} is designed for article-style bivariate reporting:
a single predictor supplied with \code{by}, and one simple model per selected
continuous outcome. The model fit is always \code{lm(outcome ~ by, ...)}.

For categorical predictors, the reported means are model-based fitted means
for each level of \code{by}, and the reported contrasts are derived from the same
fitted linear model. For an unweighted \code{lm(y ~ factor)} with classical
variance, these fitted means coincide numerically with the empirical
subgroup means; the "model-based" qualifier matters because (a) under
\code{weights}, the means become weighted least-squares estimates, (b) their
confidence intervals are derived from the model \code{vcov} (classical or \verb{HC*})
rather than from a separate empirical standard error, and (c) the reported
tests, \code{p}-values, and effect sizes all come from the same fitted model,
so means, contrasts, and inference stay internally consistent.

Compared with \code{\link[=table_continuous]{table_continuous()}}, this function is the model-based
companion for users who want to report bivariate mean comparisons in a
linear-model framework. In practice, it is the better choice when you
want heteroskedasticity-consistent standard errors (\code{vcov = "HC*"}),
model fit statistics, or case weights via \code{lm(..., weights = ...)}.
Because the function exists to report a fitted model, its inferential
output is part of the default display: \code{p_value = TRUE} is on by default,
and the model \code{R2} is shown unless explicitly disabled with \code{r2 = "none"}.
Set \code{p_value = FALSE} or \code{r2 = "none"} to suppress them.

Effect size is reported as Cohen's \code{f2}, computed from the model \code{R2} as
\code{R2 / (1 - R2)}. When \code{vcov != "classical"}, standard errors, confidence
intervals, and test statistics use the requested heteroskedasticity-
consistent estimator, while \code{R2} and adjusted \code{R2} remain the ordinary
least-squares fit statistics.

When \code{weights} is supplied, \code{table_continuous_lm()} fits weighted linear
models using \code{lm(..., weights = ...)} and reports weighted model-based
means or slopes accordingly. This is appropriate for case-weighted
analyses and weighted article tables, but it is not a substitute for a
full complex-survey design workflow.

In wide and rendered outputs, \code{n} always reports the unweighted analytic
sample size used for each outcome. When \code{show_weighted_n = TRUE}, an
additional \verb{Weighted n} column reports the sum of case weights for the same
analytic sample.

For dichotomous categorical predictors, the wide outputs report means in
reference-level order and labels the contrast column explicitly as
\code{Delta (level2 - level1)}. For categorical predictors with more than two
levels, no single contrast or contrast confidence interval is shown in the
wide outputs; instead, the table reports level-specific means plus the
overall \code{F} test when \code{statistic = TRUE} (or \code{F(df1, df2)} when the degrees
of freedom are constant across outcomes).

Optional output engines require suggested packages:
\itemize{
\item \pkg{tinytable} for \code{output = "tinytable"}
\item \pkg{gt} for \code{output = "gt"}
\item \pkg{flextable} for \code{output = "flextable"}
\item \pkg{flextable} + \pkg{officer} for \code{output = "word"}
\item \pkg{openxlsx2} for \code{output = "excel"}
\item \pkg{clipr} for \code{output = "clipboard"}
}
}
\examples{
table_continuous_lm(
  sochealth,
  select = c(wellbeing_score, bmi),
  by = sex
)

table_continuous_lm(
  sochealth,
  select = c(wellbeing_score, bmi),
  by = sex,
  output = "data.frame"
)

table_continuous_lm(
  sochealth,
  select = c(wellbeing_score, bmi),
  by = age,
  vcov = "HC3",
  ci = FALSE
)

table_continuous_lm(
  sochealth,
  select = c(wellbeing_score, bmi),
  by = sex,
  weights = weight,
  statistic = TRUE,
  effect_size = "f2",
  show_weighted_n = TRUE
)

\donttest{
if (requireNamespace("tinytable", quietly = TRUE)) {
  table_continuous_lm(
    sochealth,
    select = c(wellbeing_score, bmi),
    by = sex,
    output = "tinytable"
  )
}

if (requireNamespace("gt", quietly = TRUE)) {
  table_continuous_lm(
    sochealth,
    select = c(wellbeing_score, bmi),
    by = sex,
    output = "gt"
  )
}

if (requireNamespace("flextable", quietly = TRUE)) {
  table_continuous_lm(
    sochealth,
    select = c(wellbeing_score, bmi),
    by = sex,
    output = "flextable"
  )
}
}

}
\seealso{
\code{\link[=table_continuous]{table_continuous()}}, \code{\link[=table_categorical]{table_categorical()}}
}
