% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table2tex.R
\name{table2tex}
\alias{table2tex}
\title{Export Table to LaTeX Format}
\usage{
table2tex(
  table,
  file,
  format_headers = TRUE,
  variable_padding = FALSE,
  cell_padding = "normal",
  bold_significant = TRUE,
  bold_variables = FALSE,
  p_threshold = 0.05,
  align = NULL,
  indent_groups = FALSE,
  condense_table = FALSE,
  condense_quantitative = FALSE,
  booktabs = FALSE,
  zebra_stripes = FALSE,
  stripe_color = "gray!20",
  dark_header = FALSE,
  caption = NULL,
  caption_size = NULL,
  label = NULL,
  show_logs = FALSE,
  quiet = FALSE,
  ...
)
}
\arguments{
\item{table}{Data frame, data.table, or matrix to export. Can be output from 
\code{desctable()}, \code{survtable()}, \code{fit()}, \code{uniscreen()},
\code{fullfit()}, \code{compfit()}, \code{multifit()}, or any tabular data.}

\item{file}{Character string specifying the output \code{.tex} filename. Must have 
\code{.tex} extension. Example: \code{"results.tex"}, \code{"table1.tex"}.}

\item{format_headers}{Logical. If \code{TRUE}, formats column headers by 
converting underscores to spaces, italicizing statistical notation ("\emph{n}", 
"\emph{p}"), and applying title case. Default is \code{TRUE}.}

\item{variable_padding}{Logical. If \code{TRUE}, adds vertical spacing around 
variable groups using \code{\\addlinespace} for improved readability. 
Default is \code{FALSE}.}

\item{cell_padding}{Character string or numeric. Vertical padding within cells:
\itemize{
  \item \code{"none"} - No extra padding
  \item \code{"normal"} - Standard padding [default]
  \item \code{"relaxed"} - Increased padding
  \item \code{"loose"} - Maximum padding
  \item Numeric - Custom \code{\\arraystretch} value
}}

\item{bold_significant}{Logical. If \code{TRUE}, wraps significant \emph{p}-values 
in \code{textbf} commands for bold display. Default is \code{TRUE}.}

\item{bold_variables}{Logical. If \code{TRUE}, variable names are displayed
in bold. Default is \code{FALSE}.}

\item{p_threshold}{Numeric. Threshold for bold \emph{p}-value formatting. Only 
used when \code{bold_significant = TRUE}. Default is 0.05.}

\item{align}{Character string or vector specifying column alignment:
\itemize{
  \item \code{"l"} - Left
  \item \code{"c"} - Center  
  \item \code{"r"} - Right
  \item Paragraph column with specified width (p-type)
}
If \code{NULL}, automatically determines based on content. Can specify 
per-column as vector. Default is \code{NULL}.}

\item{indent_groups}{Logical. If \code{TRUE}, uses hspace to 
indent grouped rows, creating hierarchical display. Useful for factor 
variables in regression tables. Default is \code{FALSE}.}

\item{condense_table}{Logical. If \code{TRUE}, condenses table by showing 
only essential rows (single row for continuous, non-reference for binary). 
Automatically sets \code{indent_groups = TRUE}. Default is \code{FALSE}.}

\item{condense_quantitative}{Logical. If \code{TRUE}, condenses continuous 
and survival variables into single rows while preserving all categorical 
variable rows (including binary). Only applies to descriptive tables from 
\code{desctable()}. Automatically sets \code{indent_groups = TRUE}. Unlike 
\code{condense_table}, this does not collapse binary categorical variables. 
Default is \code{FALSE}.}

\item{booktabs}{Logical. If \code{TRUE}, uses booktabs package commands 
(toprule, midrule, bottomrule) for professional 
table rules. Requires booktabs package in LaTeX preamble. 
Default is \code{FALSE}.}

\item{zebra_stripes}{Logical. If \code{TRUE}, adds alternating row colors 
for variable groups using rowcolor command. Requires 
\code{xcolor} package with table option in preamble. Default is \code{FALSE}.}

\item{stripe_color}{Character string. LaTeX color specification for zebra 
stripes (\emph{e.g.,} \code{"gray!20"}, \code{"blue!10"}). Only used when 
\code{zebra_stripes = TRUE}. Default is \code{"gray!20"}.}

\item{dark_header}{Logical. If \code{TRUE}, creates white text on black 
background for header row. Requires \code{xcolor} package with \code{table}
option. Default is \code{FALSE}.}

\item{caption}{Character string. Table caption for LaTeX caption command. 
Supports multi-line captions using double backslash. Default is \code{NULL}.}

\item{caption_size}{Numeric. Caption font size in points. If \code{NULL} (default), 
caption will use the document's default caption size (typically slightly smaller 
than body text). Set to a specific value (\emph{e.g.,} 6, 7, 8, 9) to control caption 
size explicitly. This generates a LaTeX comment for use when wrapping 
the table. Typical range: 6-10 points.}

\item{label}{Character string. LaTeX label for cross-references. 
Example: \code{"tab:regression"}. Default is \code{NULL}.}

\item{show_logs}{Logical. If \code{TRUE}, displays informational messages 
about required LaTeX packages and formatting options applied. If 
\code{FALSE}, suppresses these messages. Default is \code{FALSE}.}

\item{quiet}{Logical. Suppress progress and confirmation messages, such
as the notice reporting the file written. Errors and warnings are
unaffected. Default is \code{FALSE}.}

\item{...}{Additional arguments passed to \code{\link[xtable]{xtable}}.}
}
\value{
Invisibly returns the file path, matching \code{tablesave()} and
  \code{forestsave()}. Called for its side effect of creating a \code{.tex}
  file at the specified location containing a LaTeX tabular environment.
}
\description{
Converts a data frame, data.table, or matrix to LaTeX source code suitable for 
inclusion in LaTeX documents. Generates publication-quality table markup with 
extensive formatting options including booktabs styling, color schemes, and 
hierarchical displays. Output can be directly \code{\\input{}} or \code{\\include{}} 
into LaTeX manuscripts. Requires \pkg{xtable} for export.
}
\details{
\strong{Output Format:}

The function generates a standalone LaTeX tabular environment that can be:
\enumerate{
  \item Included in documents with \code{\\input} command
  \item Embedded in table/figure environments
  \item Used in manuscript classes (\code{article}, \code{report}, \emph{etc.})
}

The output includes:
\itemize{
  \item Complete tabular environment with proper alignment
  \item Horizontal rules (\code{\\hline} or \code{booktabs} rules)
  \item Column headers with optional formatting
  \item Data rows with automatic escaping of special characters
  \item Optional caption and label commands
}

\strong{Required LaTeX Packages:}

The following are required in the LaTeX document preamble:

\emph{Always required:}
\preformatted{
\\usepackage[T1]{fontenc}
\\usepackage[utf8]{inputenc}
\\usepackage{array}
\\usepackage{graphicx}  % If using resizebox
}

\emph{Optional (based on parameters):}
\preformatted{
\\usepackage{booktabs}  % For booktabs = TRUE
\\usepackage[table]{xcolor}  % For zebra_stripes or dark_header
}

\strong{Booktabs Style:}

When \code{booktabs = TRUE}, the table uses publication-quality rules:
\itemize{
  \item \code{\\toprule} - Heavy rule at top
  \item \code{\\midrule} - Medium rule below headers
  \item \code{\\bottomrule} - Heavy rule at bottom
  \item No vertical rules (\code{booktabs} style)
  \item Better spacing around rules
}

This is the preferred style for most academic journals.

\strong{Color Features:}

\emph{Zebra Stripes:}
Creates alternating background colors for visual grouping:
\preformatted{
zebra_stripes = TRUE
stripe_color = "gray!20"  # 20\% gray
stripe_color = "blue!10"  # 10\% blue  
}

\emph{Dark Header:}
Creates high-contrast header row:
\preformatted{
dark_header = TRUE  # Black background, white text
}

Both require the xcolor package with the table option in the document preamble.

\strong{Integration with LaTeX Documents:}

\emph{Basic inclusion:}
\preformatted{
\\begin{table}[htbp]
  \\centering
  \\caption{Regression Results}
  \\label{tab:regression}
  \\input{results.tex}
\\end{table}
}

\emph{With resizing:}
\preformatted{
\\begin{table}[htbp]
  \\centering
  \\caption{Results}
  \\resizebox{\\textwidth}{!}{\\input{results.tex}}
\\end{table}
}

\emph{Landscape orientation:}
\preformatted{
\\usepackage{pdflscape}
\\begin{landscape}
  \\begin{table}[htbp]
    \\centering
    \\input{wide_results.tex}
  \\end{table}
\\end{landscape}
}

\strong{Caption Formatting:}

Captions in the \code{caption} parameter are written as LaTeX comments in 
the output file for reference. For actual LaTeX captions, wrap the table 
in a table environment (see examples above).

\strong{Special Characters:}

The function automatically escapes LaTeX special characters in the data:
\itemize{
  \item Ampersand, percent, dollar sign, hash, underscore
  \item Left and right braces
  \item Tilde and caret (using \code{textasciitilde} and \code{textasciicircum})
}

Variable names and labels should not include these characters unless 
intentionally using LaTeX commands.
}
\examples{
data(clintrial)
data(clintrial_labels)

# Create example table
results <- fit(
   data = clintrial,
   outcome = "os_status",
   predictors = c("age", "sex", "treatment", "stage"),
   labels = clintrial_labels
)

# Example 1: Basic LaTeX export
if (requireNamespace("xtable", quietly = TRUE)) {
  table2tex(results, file.path(tempdir(), "basic.tex"))
}

\donttest{
# Example 2: With booktabs for publication
table2tex(results, file.path(tempdir(), "publication.tex"),
       booktabs = TRUE,
       caption = "Multivariable logistic regression results",
       label = "tab:regression")

# Example 3: Multi-line caption with abbreviations
table2tex(results, file.path(tempdir(), "detailed.tex"),
       booktabs = TRUE,
       caption = "Table 1: Risk Factors for Mortality\\\\\\\\
                 aOR = adjusted odds ratio; CI = confidence interval\\\\\\\\
                 Model adjusted for age, sex, treatment, and disease stage",
       label = "tab:mortality")

# Example 4: Hierarchical display with indentation
table2tex(results, file.path(tempdir(), "indented.tex"),
       indent_groups = TRUE,
       booktabs = TRUE)

# Example 5: Condensed table (reduced height)
table2tex(results, file.path(tempdir(), "condensed.tex"),
       condense_table = TRUE,
       booktabs = TRUE)

# Example 6: With zebra stripes
table2tex(results, file.path(tempdir(), "striped.tex"),
       zebra_stripes = TRUE,
       stripe_color = "gray!15",
       booktabs = TRUE)
# Remember to add \usepackage[table]{xcolor} to the LaTeX document

# Example 7: Dark header style
table2tex(results, file.path(tempdir(), "dark_header.tex"),
       dark_header = TRUE,
       booktabs = TRUE)
# Requires \usepackage[table]{xcolor}

# Example 8: Custom cell padding
table2tex(results, file.path(tempdir(), "relaxed.tex"),
       cell_padding = "relaxed",
       booktabs = TRUE)

# Example 9: Custom column alignment (auto-detected by default)
table2tex(results, file.path(tempdir(), "custom_align.tex"),
       align = c("c", "c", "c", "c", "c", "c", "c"))

# Example 10: No header formatting (keep original names)
table2tex(results, file.path(tempdir(), "raw_headers.tex"),
       format_headers = FALSE)

# Example 11: Disable significance bolding
table2tex(results, file.path(tempdir(), "no_bold.tex"),
       bold_significant = FALSE,
       booktabs = TRUE)

# Example 12: Stricter significance threshold
table2tex(results, file.path(tempdir(), "strict_sig.tex"),
       bold_significant = TRUE,
       p_threshold = 0.01,  # Bold only if p < 0.01
       booktabs = TRUE)

# Example 13: With caption size control
table2tex(results, file.path(tempdir(), "caption_size.tex"),
       caption_size = 6,
       caption = "Table 1 - Results with Compact Caption\\\\\\\\
                 Smaller caption fits better on constrained pages")

# Example 14: Complete publication-ready table
table2tex(results, file.path(tempdir(), "final_table1.tex"),
       booktabs = TRUE,
       caption = "Table 1: Multivariable Analysis of Mortality Risk Factors",
       label = "tab:main_results",
       indent_groups = TRUE,
       zebra_stripes = FALSE,  # Many journals prefer no stripes
       bold_significant = TRUE,
       cell_padding = "normal")

# Example 15: Descriptive statistics table
desc_table <- desctable(clintrial, by = "treatment",
   variables = c("age", "sex", "bmi"), labels = clintrial_labels)

table2tex(desc_table, file.path(tempdir(), "table1_descriptive.tex"),
       booktabs = TRUE,
       caption = "Table 1: Baseline Characteristics",
       label = "tab:baseline")

# Example 16: Model comparison table
models <- list(
   base = c("age", "sex"),
   full = c("age", "sex", "treatment", "stage")
)

# Information criteria assume a common sample, so the candidate
# predictors are restricted to complete cases before comparison
comparison_data <- na.omit(clintrial[, c("os_status", "age", "sex", "treatment", "stage")])

comparison <- compfit(
   data = comparison_data,
   outcome = "os_status",
   model_list = models
)

table2tex(comparison, file.path(tempdir(), "model_comparison.tex"),
       booktabs = TRUE,
       caption = "Model Comparison Statistics",
       label = "tab:models")

}
}
\seealso{
\code{\link{tablesave}} for saving in the format given by the file extension,
\code{\link{table2pdf}} for direct PDF output,
\code{\link{table2html}} for HTML tables,
\code{\link{table2docx}} for Word documents,
\code{\link{table2pptx}} for PowerPoint,
\code{\link{table2rtf}} for Rich Text Format,
\code{\link{fit}} for regression tables,
\code{\link{desctable}} for descriptive tables

Other export functions:
\code{\link[=table2docx]{table2docx()}},
\code{\link[=table2html]{table2html()}},
\code{\link[=table2pdf]{table2pdf()}},
\code{\link[=table2pptx]{table2pptx()}},
\code{\link[=table2rtf]{table2rtf()}},
\code{\link[=tablesave]{tablesave()}}
}
\concept{export functions}
