R/autotable.R

In summata: Publication-Ready Summary Tables and Forest Plots

#' Export Table with Automatic Format Detection
#'
#' Automatically detects the output format based on file extension and exports
#' the table using the appropriate specialized function. Provides a unified interface
#' for table export across all supported formats.
#'
#' @param 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
#'   structure.
#'   
#' @param file Character string specifying the output filename. The file extension
#'   determines the export format:
#'   \itemize{
#'     \item \code{.pdf} - PDF via LaTeX (uses \code{table2pdf()})
#'     \item \code{.docx} - Microsoft Word (uses \code{table2docx()})
#'     \item \code{.html} or \code{.htm} - HTML (uses \code{table2html()})
#'     \item \code{.pptx} - Microsoft PowerPoint (uses \code{table2pptx()})
#'     \item \code{.tex} - LaTeX source (uses \code{table2tex()})
#'     \item \code{.rtf} - Rich Text Format (uses \code{table2rtf()})
#'   }
#'   
#' @param ... Additional arguments passed to the format-specific function. See
#'   the documentation for individual functions for available parameters:
#'   \describe{
#'     \item{PDF}{\code{table2pdf()} - \code{orientation}, \code{paper}, \code{margins},
#'                \code{fit_to_page}, \emph{etc.}}
#'     \item{DOCX}{\code{table2docx()} - \code{font_size}, \code{font_family},
#'                \code{caption}, \emph{etc.}}
#'     \item{HTML}{\code{table2html()} - \code{format_headers}, \code{zebra_stripes},
#'                \emph{etc.}}
#'     \item{PPTX}{\code{table2pptx()} - \code{font_size}, \code{font_family},
#'                \code{caption}, \emph{etc.}}
#'     \item{TEX}{\code{table2tex()} - \code{caption}, \code{format_headers},
#'                \code{align}, \emph{etc.}}
#'     \item{RTF}{\code{table2rtf()} - \code{font_size}, \code{font_family},
#'                \code{caption}, \emph{etc.}}
#'   }
#'   
#'   Common parameters across formats include:
#'   \describe{
#'     \item{\code{caption}}{Table caption (supported by most formats)}
#'     \item{\code{font_size}}{Base font size in points (PDF, DOCX, PPTX, RTF)}
#'     \item{\code{format_headers}}{Format column headers (all formats)}
#'     \item{\code{bold_significant}}{Bold significant \emph{p}-values (all formats)}
#'     \item{\code{p_threshold}}{Threshold for \emph{p}-value bolding (all formats)}
#'     \item{\code{indent_groups}}{Indent factor levels (all formats)}
#'     \item{\code{condense_table}}{Condense to essential rows (all formats)}
#'     \item{\code{zebra_stripes}}{Alternating background colors (most formats)}
#'   }
#'
#' @return Invisibly returns the file path. Called primarily for its side effect
#'   of creating the output file.
#'
#' @details
#' This function provides a convenient wrapper around format-specific export 
#' functions, automatically routing to the appropriate function based on the 
#' file extension. All parameters are passed through to the underlying function,
#' so the full range of format-specific options remains available.
#' 
#' For format-specific advanced features, you may prefer to use the individual
#' export functions directly:
#' \itemize{
#'   \item PDF exports support orientation, paper size, margins, and auto-sizing
#'   \item DOCX/PPTX/RTF support font customization and \pkg{flextable} formatting
#'   \item HTML supports CSS styling, responsive design, and custom themes
#'   \item TeX generates standalone LaTeX source with booktabs styling
#' }
#'
#' @examples
#' # Create example data
#' data(clintrial)
#' data(clintrial_labels)
#' tbl <- desctable(clintrial, by = "treatment",
#'     variables = c("age", "sex"), labels = clintrial_labels)
#'
#' # Auto-detect format from extension
#' if (requireNamespace("xtable", quietly = TRUE)) {
#'   autotable(tbl, file.path(tempdir(), "example.html"))
#' }
#'
#' \donttest{
#' # Load example data
#' data(clintrial)
#' data(clintrial_labels)
#' 
#' # Create a regression table
#' results <- fit(
#'     data = clintrial,
#'     outcome = "os_status",
#'     predictors = c("age", "sex", "treatment"),
#'     labels = clintrial_labels
#' )
#' 
#' # Test that LaTeX can actually compile (needed for PDF export)
#' has_latex <- local({
#'   if (!nzchar(Sys.which("pdflatex"))) return(FALSE)
#'   test_tex <- file.path(tempdir(), "summata_latex_test.tex")
#'   writeLines(c("\\documentclass{article}",
#'                "\\usepackage{booktabs}",
#'                "\\begin{document}", "test",
#'                "\\end{document}"), test_tex)
#'   result <- tryCatch(
#'     system2("pdflatex", c("-interaction=nonstopmode",
#'             paste0("-output-directory=", tempdir()), test_tex),
#'             stdout = FALSE, stderr = FALSE),
#'     error = function(e) 1L)
#'   result == 0L
#' })
#' 
#' # Export automatically detects format from extension
#' autotable(results, file.path(tempdir(), "results.html"))  # Creates HTML file
#' autotable(results, file.path(tempdir(), "results.docx"))  # Creates Word document
#' autotable(results, file.path(tempdir(), "results.pptx"))  # Creates PowerPoint slide
#' autotable(results, file.path(tempdir(), "results.tex"))   # Creates LaTeX source
#' autotable(results, file.path(tempdir(), "results.rtf"))   # Creates RTF document
#' if (has_latex) {
#'   autotable(results, file.path(tempdir(), "results.pdf")) # Creates PDF
#' }
#' 
#' # Pass format-specific parameters
#' if (has_latex) {
#'   autotable(results, file.path(tempdir(), "results.pdf"), 
#'              orientation = "landscape",
#'              paper = "a4",
#'              font_size = 10)
#' }
#' 
#' autotable(results, file.path(tempdir(), "results.docx"),
#'            caption = "Table 1: Logistic Regression Results",
#'            font_family = "Times New Roman",
#'            condense_table = TRUE)
#' 
#' autotable(results, file.path(tempdir(), "results.html"),
#'            zebra_stripes = TRUE,
#'            dark_header = TRUE,
#'            bold_significant = TRUE)
#' 
#' # Works with any summata table output
#' desc <- desctable(clintrial,
#'                   by = "treatment",
#'                   variables = c("age", "sex", "bmi"))
#' if (has_latex) {
#'   autotable(desc, file.path(tempdir(), "demographics.pdf"))
#' }
#' 
#' comparison <- compfit(
#'     data = clintrial,
#'     outcome = "os_status",
#'     model_list = list(
#'         base = c("age", "sex"),
#'         full = c("age", "sex", "treatment", "stage")
#'     )
#' )
#' autotable(comparison, file.path(tempdir(), "model_comparison.docx"))
#'
#' }
#' @seealso
#' \code{\link{table2pdf}}, \code{\link{table2docx}}, \code{\link{table2pptx}},
#' \code{\link{table2html}}, \code{\link{table2rtf}}, \code{\link{table2tex}}
#'
#' @family export functions
#' @export
autotable <- function(table, file, ...) {
    
    if (missing(table) || missing(file)) {
        stop("Both 'table' and 'file' arguments are required")
    }
    
    if (!is.character(file) || length(file) != 1) {
        stop("'file' must be a single character string")
    }
    
    file_ext <- tolower(tools::file_ext(file))
    
    if (file_ext == "") {
        stop(paste0("File '", file, "' has no extension. ",
                    "Please specify one of the following: .pdf, .docx, .pptx, .html, .htm, .rtf, .tex"))
    }
    
    result <- switch(file_ext,
                     "pdf" = {
                         table2pdf(table = table, file = file, ...)
                     },
                     "docx" = {
                         table2docx(table = table, file = file, ...)
                     },
                     "pptx" = {
                         table2pptx(table = table, file = file, ...)
                     },
                     "html" = ,
                     "htm" = {
                         table2html(table = table, file = file, ...)
                     },
                     "rtf" = {
                         table2rtf(table = table, file = file, ...)
                     },
                     "tex" = {
                         table2tex(table = table, file = file, ...)
                     },
                     {
                         stop(paste0("Unsupported file extension: '.", file_ext, "'\n",
                                     "Supported formats are:\n",
                                     "  .pdf   - PDF via LaTeX\n",
                                     "  .docx  - Microsoft Word\n",
                                     "  .pptx  - Microsoft PowerPoint\n",
                                     "  .html  - HTML\n",
                                     "  .htm   - HTML\n",
                                     "  .rtf   - Rich Text Format\n",
                                     "  .tex   - LaTeX source"))
                     }
                     )
    
    invisible(file)
}