% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table2docx.R
\name{table2docx}
\alias{table2docx}
\title{Export Table to Microsoft Word Format (DOCX)}
\usage{
table2docx(
  table,
  file,
  caption = NULL,
  font_size = 8,
  font_family = "Arial",
  format_headers = TRUE,
  bold_significant = TRUE,
  bold_variables = FALSE,
  p_threshold = 0.05,
  indent_groups = FALSE,
  condense_table = FALSE,
  condense_quantitative = FALSE,
  zebra_stripes = FALSE,
  dark_header = FALSE,
  paper = "letter",
  orientation = "portrait",
  width = NULL,
  align = NULL,
  return_ft = 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 DOCX filename. Must have 
\code{.docx} extension. Example: \code{"results.docx"}, \code{"Table1.docx"}.}

\item{caption}{Character string. Optional caption displayed above the table 
in the Word document. Default is \code{NULL}.}

\item{font_size}{Numeric. Base font size in points for table content. 
Default is 8. Typical range: 8-12 points. Headers use slightly larger size.}

\item{font_family}{Character string. Font family name for the table. Must be 
a font installed on the system. Default is \code{"Arial"}. Common options: 
\code{"Times New Roman"}, \code{"Calibri"}, \code{"Helvetica"}.}

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

\item{bold_significant}{Logical. If \code{TRUE}, applies bold formatting to 
\emph{p}-values below the significance threshold. Makes significant results stand 
out. 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{indent_groups}{Logical. If \code{TRUE}, indents factor levels under 
their parent variable using horizontal spacing, creating hierarchical display. 
Useful for categorical 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}. Significantly reduces table 
height. 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{zebra_stripes}{Logical. If \code{TRUE}, applies alternating row shading 
to different variables (not individual rows) for visual grouping. 
Default is \code{FALSE}.}

\item{dark_header}{Logical. If \code{TRUE}, creates a dark background with 
light text for the header row, providing strong visual contrast. 
Default is \code{FALSE}.}

\item{paper}{Character string specifying paper size:
\itemize{
  \item \code{"letter"} - US Letter (8.5" × 11") [default]
  \item \code{"a4"} - A4 (210 mm × 297 mm)
  \item \code{"legal"} - US Legal (8.5" × 14")
}}

\item{orientation}{Character string specifying page orientation:
\itemize{
  \item \code{"portrait"} - Vertical [default]
  \item \code{"landscape"} - Horizontal (for wide tables)
}}

\item{width}{Numeric. Table width in inches. If \code{NULL} (default), 
automatically fits to content and page width. Specify to control exactly.}

\item{align}{Character vector specifying column alignment for each column. 
Options: \code{"left"}, \code{"center"}, or \code{"right"}. If \code{NULL} 
(default), automatically determines based on content (text left, numbers right).
Example: \code{c("left", "left", "center", "right", "right")}.}

\item{return_ft}{Logical. If \code{TRUE}, returns the \pkg{flextable} object 
directly for further customization. If \code{FALSE} (default), returns 
invisibly with \pkg{flextable} object as attribute. See Details for usage. 
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[officer]{read_docx}} 
for document initialization.}
}
\value{
Behavior depends on \code{return_ft}:
  \describe{
    \item{\code{return_ft = FALSE}}{Invisibly returns a list with components:
      \itemize{
        \item \code{file} - Path to created file
        \item \code{caption} - Caption text (if provided)
      }
      The \pkg{flextable} object is accessible via \code{attr(result, "flextable")}
    }
    \item{\code{return_ft = TRUE}}{Directly returns the \pkg{flextable} object for 
      immediate further customization}
  }
  
  In both cases, creates a \code{.docx} file at the specified location.
}
\description{
Converts a data frame, data.table, or matrix to a fully editable Microsoft Word 
document (\code{.docx}) using the \pkg{flextable} and \pkg{officer} packages.
Creates publication-ready tables with extensive formatting options including
typography, alignment, colors, and page layout. Tables can be further edited in
Microsoft Word after creation.
}
\details{
\strong{Package Requirements:}

This function requires:
\itemize{
  \item \strong{\pkg{flextable}} - For creating formatted tables
  \item \strong{\pkg{officer}} - For Word document manipulation
}

Install if needed:
\preformatted{
install.packages(c("flextable", "officer"))
}

\strong{Output Features:}

The generated Word document contains:
\itemize{
  \item Fully editable table (native Word table, not image)
  \item Professional typography and spacing
  \item Proper page setup (size, orientation, margins)
  \item Caption (if provided) as separate paragraph above table
  \item All formatting preserved but editable
  \item Compatible with Word 2007 and later
}

\strong{Further Customization:}

For programmatic customization beyond the built-in options, access the 
\code{flextable} object:

\emph{Method 1: Via attribute (default)}

\preformatted{
result <- table2docx(table, "output.docx")
ft <- attr(result, "flextable")

# Customize flextable
ft <- flextable::bold(ft, i = 1, j = 1, part = "body")
ft <- flextable::color(ft, i = 2, j = 3, color = "red")

# Re-save if needed
doc <- officer::read_docx()
doc <- flextable::body_add_flextable(doc, ft)
print(doc, target = "customized.docx")
}

\emph{Method 2: Direct return}

\preformatted{
ft <- table2docx(table, "output.docx", return_ft = TRUE)

# Customize immediately
ft <- flextable::bg(ft, bg = "yellow", part = "header")
ft <- flextable::autofit(ft)

# Save to new document
doc <- officer::read_docx()
doc <- flextable::body_add_flextable(doc, ft)
print(doc, target = "custom.docx")
}

\strong{Page Layout:}

The function automatically sets up the Word document with:
\itemize{
  \item Specified paper size and orientation
  \item Standard margins (1 inch by default)
  \item Continuous section (no page breaks before table)
  \item Left-aligned table placement
}

For landscape orientation:
\itemize{
  \item Automatically swaps page width and height
  \item Applies landscape property to section
  \item Useful for wide tables with many columns
}

\strong{Table Width Management:}

Width behavior:
\itemize{
  \item \code{width = NULL} - Auto-fits to content and page width
  \item \code{width = 6} - Exactly 6 inches wide
  \item Width distributed evenly across columns by default
  \item Can adjust individual column widths in Word after creation
}

For very wide tables:
\enumerate{
  \item Use \code{orientation = "landscape"}
  \item Use \code{paper = "legal"} for extra width
  \item Reduce \code{font_size}
  \item Use \code{condense_table = TRUE}
  \item Consider breaking across multiple tables
}

\strong{Typography:}

The function applies professional typography:
\itemize{
  \item Column headers: Bold, slightly larger font
  \item Body text: Regular weight, specified font size
  \item Numbers: Right-aligned for easy comparison
  \item Text: Left-aligned for readability
  \item Consistent spacing: Adequate padding in cells
}

Font family must be installed on the system where Word opens the document. 
Common cross-platform choices:
\itemize{
  \item Arial - Sans-serif, highly readable
  \item Times New Roman - Serif, traditional
  \item Calibri - Microsoft default, modern
  \item Helvetica - Sans-serif, professional
}

\strong{Zebra Striping:}

When \code{zebra_stripes = TRUE}:
\itemize{
  \item Alternating variables receive light gray background
  \item All rows of same variable share same shading
  \item Improves visual grouping
  \item Particularly useful for tables with many factor variables
  \item Color can be changed in Word after creation
}

\strong{Dark Header:}

When \code{dark_header = TRUE}:
\itemize{
  \item Header row: Dark gray/black background
  \item Header text: White for high contrast
  \item Modern, professional appearance
  \item Draws attention to column names
}

\strong{Integration with R Markdown/Quarto:}

For R Markdown/Quarto Word output:

\preformatted{
# Create flextable for inline display
ft <- table2docx(results, "temp.docx", return_ft = TRUE)

# Display in R Markdown chunk
ft  # Renders in Word output
}

Or use \code{flextable} directly in chunks:

\preformatted{
flextable::flextable(results)
}
}
\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 Word export
if (requireNamespace("flextable", quietly = TRUE) &&
    requireNamespace("officer", quietly = TRUE)) {
  table2docx(results, file.path(tempdir(), "results.docx"))
}

\donttest{
old_width <- options(width = 180)
# Example 2: With caption
table2docx(results, file.path(tempdir(), "captioned.docx"),
        caption = "Table 1: Multivariable Logistic Regression Results")

# Example 3: Landscape orientation for wide tables
table2docx(results, file.path(tempdir(), "wide.docx"),
        orientation = "landscape")

# Example 4: Custom font and size
table2docx(results, file.path(tempdir(), "custom_font.docx"),
        font_family = "Times New Roman",
        font_size = 11)

# Example 5: Hierarchical display
table2docx(results, file.path(tempdir(), "indented.docx"),
        indent_groups = TRUE)

# Example 6: Condensed table
table2docx(results, file.path(tempdir(), "condensed.docx"),
        condense_table = TRUE)

# Example 7: With zebra stripes
table2docx(results, file.path(tempdir(), "striped.docx"),
        zebra_stripes = TRUE)

# Example 8: Dark header style
table2docx(results, file.path(tempdir(), "dark.docx"),
        dark_header = TRUE)

# Example 9: A4 paper for international journals
table2docx(results, file.path(tempdir(), "a4.docx"),
        paper = "a4")

# Example 10: Get flextable for customization
result <- table2docx(results, file.path(tempdir(), "base.docx"))
ft <- attr(result, "flextable")

# Customize the flextable
ft <- flextable::bold(ft, i = 1, part = "body")
ft <- flextable::color(ft, j = "p-value", color = "blue")

# Example 11: Direct flextable return
ft <- table2docx(results, file.path(tempdir(), "direct.docx"), return_ft = TRUE)
ft <- flextable::bg(ft, bg = "yellow", part = "header")

# Example 12: Publication-ready table
table2docx(results, file.path(tempdir(), "publication.docx"),
        caption = "Table 2: Adjusted Odds Ratios for Mortality",
        font_family = "Times New Roman",
        font_size = 10,
        indent_groups = TRUE,
        zebra_stripes = FALSE,
        bold_significant = TRUE)

# Example 13: Custom column alignment
table2docx(results, file.path(tempdir(), "aligned.docx"),
        align = c("left", "left", "center", "right", "right"))

# Example 14: Disable significance bolding
table2docx(results, file.path(tempdir(), "no_bold.docx"),
        bold_significant = FALSE)

# Example 15: Stricter significance threshold
table2docx(results, file.path(tempdir(), "strict.docx"),
        bold_significant = TRUE,
        p_threshold = 0.01)

options(old_width)
}
}
\seealso{
\code{\link{tablesave}} for saving in the format given by the file extension,
\code{\link{table2pptx}} for PowerPoint slides,
\code{\link{table2pdf}} for PDF output,
\code{\link{table2html}} for HTML tables,
\code{\link{table2rtf}} for Rich Text Format,
\code{\link{table2tex}} for LaTeX output,
\code{\link[flextable]{flextable}} for the underlying table object,
\code{\link[officer]{read_docx}} for Word document manipulation

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