% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table2pptx.R
\name{table2pptx}
\alias{table2pptx}
\title{Export Table to Microsoft PowerPoint Format (PPTX)}
\usage{
table2pptx(
  table,
  file,
  caption = NULL,
  font_size = 10,
  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,
  width = NULL,
  align = NULL,
  template = NULL,
  layout = "Title and Content",
  master = "Office Theme",
  left = 0.5,
  top = 1.5,
  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 PPTX filename. Must have 
\code{.pptx} extension. Example: \code{"results.pptx"}, \code{"Slide1.pptx"}.}

\item{caption}{Character string. Optional title displayed in the slide's title 
placeholder or as text box above the table. Default is \code{NULL}.}

\item{font_size}{Numeric. Base font size in points for table content. 
Default is 10. Typical range for presentations: 10-14 points. Larger than 
print documents for visibility at distance.}

\item{font_family}{Character string. Font family name for the table. Must be 
installed on the system. Default is \code{"Arial"}. Common presentation 
fonts: \code{"Calibri"}, \code{"Helvetica"}, \code{"Arial"}.}

\item{format_headers}{Logical. If \code{TRUE}, formats column headers by 
italicizing statistical notation ("\emph{n}", "\emph{p}") 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 important results stand 
out in presentations. 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, creating hierarchical display. Useful for categorical 
variables. Default is \code{FALSE}.}

\item{condense_table}{Logical. If \code{TRUE}, condenses table to essential 
rows only. Automatically sets \code{indent_groups = TRUE}. Crucial for 
fitting content on slides. 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 for visual grouping. Improves readability during 
presentations. Default is \code{FALSE}.}

\item{dark_header}{Logical. If \code{TRUE}, creates dark background with 
light text for header row. Provides strong contrast visible from distance. 
Default is \code{FALSE}.}

\item{width}{Numeric. Table width in inches. If \code{NULL} (default), 
auto-fits to slide width (approximately 9 inches for standard 10-inch slide 
with margins). Specify for exact control.}

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

\item{template}{Character string. Path to custom PPTX template file. If 
\code{NULL} (default), uses officer's default blank template. Use to match 
corporate branding or conference themes.}

\item{layout}{Character string. Name of slide layout to use from template. 
Default is \code{"Title and Content"}. Common layouts:
\itemize{
  \item \code{"Title and Content"} - Standard layout [default]
  \item \code{"Blank"} - Empty slide for maximum control
  \item \code{"Title Only"} - Title area only
  \item \code{"Two Content"} - Title with two content areas
}}

\item{master}{Character string. Name of slide master to use. Default is 
\code{"Office Theme"}. Varies by template. Check template for available masters.}

\item{left}{Numeric. Horizontal position from left edge of slide in inches. 
Default is 0.5. Standard slide is 10 inches wide.}

\item{top}{Numeric. Vertical position from top edge of slide in inches. 
Default is 1.5 (leaves room for title). Standard slide is 7.5 inches tall. 
Adjust based on table size and layout.}

\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_pptx}}.}
}
\value{
Behavior depends on \code{return_ft}:
  \describe{
    \item{\code{return_ft = FALSE}}{Invisibly returns a list with:
      \itemize{
        \item \code{file} - Path to created file
        \item \code{caption} - Caption/title text
        \item \code{layout} - Layout name used
        \item \code{master} - Master name used
        \item \code{template} - Template path (if provided)
        \item \code{position} - List with \code{left} and \code{top} coordinates
      }
      Flextable accessible via \code{attr(result, "flextable")}
    }
    \item{\code{return_ft = TRUE}}{Directly returns the \pkg{flextable} object}
  }
  
  Always creates a \code{.pptx} file at the specified location.
}
\description{
Converts a data frame, data.table, or matrix to a Microsoft PowerPoint slide 
(\code{.pptx}) with a formatted table using the \pkg{flextable} and \pkg{officer}
packages. Creates presentation-ready slides with extensive control over table
formatting, positioning, and layout. Tables can be further edited in PowerPoint
after creation. Ideal for creating data-driven presentations and conference talks.
}
\details{
\strong{Package Requirements:}

Requires:
\itemize{
  \item \strong{\pkg{flextable}} - Table creation and formatting
  \item \strong{\pkg{officer}} - PowerPoint manipulation
}

Install: \code{install.packages(c("flextable", "officer"))}

\strong{Slide Dimensions:}

Standard PowerPoint slide:
\itemize{
  \item Width: 10 inches (25.4 cm)
  \item Height: 7.5 inches (19.05 cm)
  \item Aspect ratio: 4:3 (standard) or 16:9 (widescreen)
}

Safe content area (with margins):
\itemize{
  \item Width: ~9 inches
  \item Height: ~6 inches (accounting for title)
}

\strong{Positioning:}

The \code{left} and \code{top} parameters control table placement:
\itemize{
  \item (0, 0) = Top-left corner of slide
  \item Default (0.5, 1.5) = Standard position with title room
  \item Center: \code{left = (10 - table_width) / 2}
}

When caption is provided:
\itemize{
  \item Attempts to use title placeholder (if layout supports)
  \item Falls back to text box above table
  \item Automatically adjusts table position downward
}

\strong{Slide Layouts:}

Different layouts serve different purposes:

\emph{Title and Content (default):}
\itemize{
  \item Has title and content placeholders
  \item Caption goes in title area
  \item Table in content area
  \item Most common for data slides
}

\emph{Blank:}
\itemize{
  \item No predefined areas
  \item Maximum flexibility
  \item Use absolute positioning (\code{left}, \code{top})
  \item Good for custom layouts
}

\emph{Title-Only:}
\itemize{
  \item Title area only
  \item Large space for table
  \item Good for data-heavy slides
}

\strong{Custom Templates:}

Use organizational or conference templates:
\preformatted{
table2pptx(table, "branded.pptx",
         template = "company_template.pptx",
         layout = "Content Layout",  # Name from template
         master = "Company Theme")   # Name from template
}

To find layout and master names in template:
\preformatted{
pres <- officer::read_pptx("template.pptx")
officer::layout_summary(pres)
}

\strong{Multiple Slides:}

Creating presentations with multiple tables:
\preformatted{
# Each call creates new presentation - combine after
table2pptx(table1, "slide1.pptx", caption = "Results Part 1")
table2pptx(table2, "slide2.pptx", caption = "Results Part 2")

# Then manually combine in PowerPoint, or:
# Use officer to create multi-slide presentation
pres <- officer::read_pptx()

# Add first table
ft1 <- table2pptx(table1, "temp1.pptx", return_ft = TRUE)
pres <- officer::add_slide(pres)
pres <- officer::ph_with(pres, ft1, 
                         location = officer::ph_location(left = 0.5, top = 1.5))

# Add second table
ft2 <- table2pptx(table2, "temp2.pptx", return_ft = TRUE)
pres <- officer::add_slide(pres)
pres <- officer::ph_with(pres, ft2,
                         location = officer::ph_location(left = 0.5, top = 1.5))

print(pres, target = "combined.pptx")
}

\strong{Further Customization:}

Access the \code{flextable} object for advanced formatting:
\preformatted{
ft <- table2pptx(table, "base.pptx", return_ft = TRUE)

# Customize
ft <- flextable::color(ft, j = "p-value", color = "red")
ft <- flextable::bg(ft, i = 1, bg = "yellow")
ft <- flextable::bold(ft, i = ~ estimate > 0, j = "estimate")

# Save to new slide
pres <- officer::read_pptx()
pres <- officer::add_slide(pres)
pres <- officer::ph_with(pres, ft, 
                         location = officer::ph_location(left = 0.5, top = 1.5))
print(pres, target = "custom.pptx")
}
}
\examples{
# Create example data
data(clintrial)
data(clintrial_labels)
tbl <- desctable(clintrial, by = "treatment",
    variables = c("age", "sex"), labels = clintrial_labels)

# Basic PowerPoint export
if (requireNamespace("flextable", quietly = TRUE) &&
    requireNamespace("officer", quietly = TRUE)) {
  table2pptx(tbl, file.path(tempdir(), "example.pptx"))
}

\donttest{
old_width <- options(width = 180)
# Load data
data(clintrial)
data(clintrial_labels)

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

# Example 1: Basic PowerPoint slide
table2pptx(results, file.path(tempdir(), "results.pptx"))

# Example 2: With title
table2pptx(results, file.path(tempdir(), "titled.pptx"),
        caption = "Multivariable Regression Results")

# Example 3: Larger font for visibility
table2pptx(results, file.path(tempdir(), "large_font.pptx"),
        font_size = 12,
        caption = "Main Findings")

# Example 4: Condensed for slide space
table2pptx(results, file.path(tempdir(), "condensed.pptx"),
        condense_table = TRUE,
        caption = "Key Results")

# Example 5: Dark header for emphasis
table2pptx(results, file.path(tempdir(), "dark.pptx"),
        dark_header = TRUE,
        caption = "Risk Factors")

# Example 6: With zebra stripes
table2pptx(results, file.path(tempdir(), "striped.pptx"),
        zebra_stripes = TRUE)

# Example 7: Blank layout with custom positioning
table2pptx(results, file.path(tempdir(), "blank.pptx"),
        layout = "Blank",
        left = 1,
        top = 1.5,
        width = 8)

# Example 8: Get flextable for customization
ft <- table2pptx(results, file.path(tempdir(), "base.pptx"), return_ft = TRUE)

# Customize the returned flextable object
ft <- flextable::color(ft, j = "p-value", color = "darkred")

# Example 9: Presentation-optimized table
table2pptx(results, file.path(tempdir(), "presentation.pptx"),
        caption = "Main Analysis Results",
        font_size = 11,
        condense_table = TRUE,
        zebra_stripes = TRUE,
        dark_header = TRUE,
        bold_significant = TRUE)

# Example 10: Descriptive statistics slide
desc <- desctable(
   data = clintrial,
   by = "treatment",
   variables = c("age", "sex", "bmi"),
   labels = clintrial_labels
)

table2pptx(desc, file.path(tempdir(), "baseline.pptx"),
        caption = "Baseline Characteristics",
        font_size = 10)

# Example 11: Conference presentation style
table2pptx(results, file.path(tempdir(), "conference.pptx"),
        caption = "Study Outcomes",
        font_family = "Calibri",
        font_size = 14,  # Large for big rooms
        dark_header = TRUE,
        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{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 table customization,
\code{\link[officer]{read_pptx}} for PowerPoint manipulation

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