% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table2rtf.R
\name{table2rtf}
\alias{table2rtf}
\title{Export Table to Rich Text Format (RTF)}
\usage{
table2rtf(
  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 RTF filename. Must have 
\code{.rtf} extension. Example: \code{"results.rtf"}, \code{"Table1.rtf"}.}

\item{caption}{Character string. Optional caption displayed above the table 
in the RTF 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{"Courier New"}.}

\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 flextable 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 (currently unused, reserved for future extensions).}
}
\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 .rtf file at the specified location.
}
\description{
Converts a data frame, data.table, or matrix to a Rich Text Format (\code{.rtf}) 
document using the \pkg{flextable} and \pkg{officer} packages. Creates 
widely compatible tables with extensive formatting options. RTF files can be 
opened and edited in Microsoft Word, LibreOffice, WordPad, and many other word 
processors. Particularly useful for regulatory submissions, cross-platform 
compatibility, and when maximum editability is required.
}
\details{
\strong{Package Requirements:}

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

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

\strong{RTF Format Advantages:}

RTF (Rich Text Format) is a universal document format with several advantages:
\itemize{
  \item \strong{Maximum compatibility} - Opens in virtually all word processors
  \item \strong{Cross-platform} - Works on Windows, Mac, Linux without conversion
  \item \strong{Fully editable} - Native text format, not embedded objects
  \item \strong{Lightweight} - Smaller file sizes than DOCX
  \item \strong{Regulatory compliance} - Widely accepted for submissions (FDA, EMA)
  \item \strong{Long-term accessibility} - Simple text-based format
  \item \strong{Version control friendly} - Text-based, works with diff tools
}

Applications that can open RTF files:
\itemize{
  \item Microsoft Word (Windows, Mac)
  \item LibreOffice Writer
  \item Apache OpenOffice Writer
  \item WordPad (Windows built-in)
  \item TextEdit (Mac built-in)
  \item Google Docs (with import)
  \item Pages (Mac)
  \item Many other word processors
}

\strong{Output Features:}

The generated RTF document contains:
\itemize{
  \item Fully editable table (native RTF 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 RTF 1.5 specification
}

\strong{Further Customization:}

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

\emph{Method 1: Via attribute (default)}
\preformatted{
result <- table2rtf(table, "output.rtf")
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
flextable::save_as_rtf(ft, path = "customized.rtf")
}

\emph{Method 2: Direct return}
\preformatted{
ft <- table2rtf(table, "output.rtf", return_ft = TRUE)

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

# Save to new file
flextable::save_as_rtf(ft, path = "custom.rtf")
}

\strong{Page Layout:}

The function automatically sets up the RTF document with:
\itemize{
  \item Specified paper size and orientation
  \item Standard margins (1 inch by default)
  \item Table positioned at document start
  \item Left-aligned table placement
}

For landscape orientation:
\itemize{
  \item Automatically swaps page dimensions
  \item Applies landscape property
  \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 processor 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
  \item Statistical notation: Italicized appropriately
}
}
\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 RTF export
if (requireNamespace("flextable", quietly = TRUE)) {
  table2rtf(results, file.path(tempdir(), "results.rtf"))
}

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

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

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

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

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

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

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

# Example 9: A4 paper for international submissions
table2rtf(results, file.path(tempdir(), "a4.rtf"),
       paper = "a4")

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

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

# Re-save
flextable::save_as_rtf(ft, path = file.path(tempdir(), "customized.rtf"))

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

# Example 12: Regulatory submission table
table2rtf(results, file.path(tempdir(), "submission.rtf"),
       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
table2rtf(results, file.path(tempdir(), "aligned.rtf"),
       align = c("left", "left", "center", "right", "right"))

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

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

# Example 16: Descriptive statistics for baseline characteristics
desc <- desctable(clintrial, by = "treatment",
   variables = c("age", "sex", "bmi", "stage"), labels = clintrial_labels)

table2rtf(desc, file.path(tempdir(), "baseline.rtf"),
       caption = "Table 1: Baseline Patient Characteristics",
       zebra_stripes = TRUE)

# Example 17: Clinical trial efficacy table
table2rtf(results, file.path(tempdir(), "efficacy.rtf"),
       caption = "Table 3: Primary Efficacy Analysis - Intent to Treat Population",
       font_family = "Courier New",  # Monospace for alignment
       paper = "letter",
       orientation = "landscape",
       condense_table = TRUE)

options(old_width)
}
}
\seealso{
\code{\link{tablesave}} for saving in the format given by the file extension,
\code{\link{table2docx}} for Word documents,
\code{\link{table2pptx}} for PowerPoint slides,
\code{\link{table2pdf}} for PDF output,
\code{\link{table2html}} for HTML tables,
\code{\link{table2tex}} for LaTeX output,
\code{\link[flextable]{flextable}} for the underlying table object,
\code{\link[flextable]{save_as_rtf}} for direct RTF export

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