% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fboxplot.R
\name{f_boxplot}
\alias{f_boxplot}
\alias{f_boxplot.formula}
\alias{f_boxplot.data.frame}
\alias{f_boxplot_worker}
\title{Generate a Boxplot Report of a data.frame}
\usage{
f_boxplot(x, ...)

\method{f_boxplot}{formula}(formula, data, ...)

\method{f_boxplot}{data.frame}(x, ...)

f_boxplot_worker(
  formula = NULL,
  data,
  fancy_names = NULL,
  output_type = "pdf",
  outliers = TRUE,
  coef = 1.5,
  limit_columns = 7,
  save_as = NULL,
  save_in_wdir = FALSE,
  close_generated_files = FALSE,
  open_generated_files = interactive(),
  boxplot_explanation = TRUE,
  detect_factors = TRUE,
  jitter = FALSE,
  width = 8,
  height = 7,
  units = "in",
  res = 300,
  las = 2
)
}
\arguments{
\item{x}{A data.frame or formula (dispatches to the right method).}

\item{...}{Further arguments forwarded to \code{f_boxplot_worker},
such as \code{fancy_names}, \code{title}, \code{fill}, etc.}

\item{formula}{A formula specifying the factor to be plotted. More response variables can be added using \code{-} or \code{+} (e.g., \code{response1 + response2 ~ predictor}) to generate multiple boxplots. If the formula is omitted and only \code{data} is provided all data will be used for creating boxplots.}

\item{data}{A \code{data.frame} containing the data to be used for creating boxplots.}

\item{fancy_names}{An optional named vector mapping column names in \code{data} to more readable names for display in plots (name map). Defaults to \code{NULL}.}

\item{output_type}{Character string, specifying the output format: \code{"pdf"}, \code{"word"}, \code{"rmd"} or \code{"png"}. The option \code{"rmd"} saves rmd code in the output object not in a file. Default is \code{"pdf"}.}

\item{outliers}{Logical. If \code{TRUE}, scans for outliers using Tukey's fences and if they exist, adds them to the report using \code{f_outliers}. Default \code{TRUE}.}

\item{coef}{Numeric. The multiplier for the Interquartile Range (IQR) used for outlier detection. Default \code{1.5}.}

\item{limit_columns}{Integer or \code{NULL}. Defines the number of columns shown in the outlier table. Default = \code{7}. \code{NULL} = all columns are shown.}

\item{save_as}{Character string specifying the output file path (without extension).
If a full path is provided, output is saved to that location.
If only a filename is given, the file is saved in \code{tempdir()}.
If only a directory is specified (providing an existing directory with trailing slash),
the file is named "dataname_BoxPlot" in that directory. If an extension is provided the output format specified with option "output_type" will be overruled.
Defaults to \code{file.path(tempdir(), "dataname_BoxPlot.pdf")}.}

\item{save_in_wdir}{Logical. If \code{TRUE}, saves the file in the working directory. Default is \code{FALSE}, this avoid unintended changes to the global environment. If \code{save_as} location is specified \code{save_in_wdir} is overwritten by \code{save_as}.}

\item{close_generated_files}{Logical. Closes open Excel or Word (NOT pdf) files before writing, depending on the output format. Works on Windows (taskkill), macOS (pkill) and Linux (pkill/soffice). Default \code{FALSE}. \strong{WARNING:} Always save your work before using this option!!}

\item{open_generated_files}{Logical. Whether to open the generated output
files after creation. Defaults to \code{TRUE} in an interactive R session
and \code{FALSE} otherwise (e.g. in scripts or automated pipelines).
Set to \code{TRUE} or \code{FALSE} to override this behaviour explicitly.}

\item{boxplot_explanation}{A logical value indicating whether to include an explanation of how to interpret boxplots in the report. Defaults to \code{TRUE}.}

\item{detect_factors}{A logical value indicating whether to automatically detect factor variables in the dataset. Defaults to \code{TRUE}.}

\item{jitter}{A logical value, if \code{TRUE} all data per boxplot is shown, if \code{FALSE} (default) individual data points (except for outliers) are omitted.}

\item{width}{Numeric, png figure width default \code{8} inch}

\item{height}{Numeric, png figure height default \code{7} inch}

\item{units}{Character string, png figure units default \code{"in"} = inch, other options are: \code{"px"} = Pixels, \code{"cm"} = centimeters, \code{"mm"} = millimeters.}

\item{res}{Numeric, png figure resolution default 300 dpi}

\item{las}{An integer (\code{0} t/m \code{3}), \code{las = 0}: Axis labels are parallel to the axis. \code{las = 1}: Axis labels are always horizontal. \code{las = 2}: Axis labels are perpendicular to the axis. (default setting). \code{las = 3}: Axis labels are always vertical.}
}
\value{
The return value depends on \code{output_type}:
\itemize{
  \item \code{"pdf"} and \code{"word"}: Writes a report file to \code{save_as} (or \code{tempdir()} by default) and returns \code{NULL} invisibly. The file can optionally be opened with \code{open_generated_files = TRUE}.
  \item \code{"png"}: Writes one PNG file per response x factor combination into the directory given by \code{save_as} and returns \code{NULL} invisibly.
  \item \code{"rmd"}: Returns the generated R Markdown content as a single character string (invisibly). No file is written and nothing is printed to the console. The caller can \code{cat()} the string, assign it to a variable, or embed it in a larger report (see Examples).
}
}
\description{
Generates boxplots for all numeric variables in a given dataset, grouped by factor variables. The function automatically detects numeric and factor variables. It allows two output formats ('pdf', 'Word') and includes an option to add a general explanation about interpreting boxplots.
}
\details{
The function performs the following steps:
\itemize{
\item Detects numeric and factor variables in the dataset.
\item Generates boxplots for each numeric variable grouped by each factor variable.
\item Outputs the report in the specified format ('pdf', 'Word' or 'Rmd').
}

If \code{output_type = "rmd"} is used it is adviced to use it in a chunk with \{r, echo=FALSE, results='asis'\}

If no factor variables are detected, the function stops with an error message since factors are required for creating boxplots.

This function will plot all numeric and factor candidates, use the function \code{subset()} to prepare a selection of columns before submitting to \code{f_boxplot()}.

Note that there is an optional \code{jitter} option to plot all individual data points over the boxplots.

This function requires [Pandoc](https://github.com/jgm/pandoc/releases/tag) (version 1.12.3 or higher), a universal document converter.

\bold{Windows:} Install Pandoc and ensure the installation folder \cr (e.g., "C:/Users/your_username/AppData/Local/Pandoc") is added to your system PATH.

\bold{macOS:} If using Homebrew, Pandoc is typically installed in "/usr/local/bin". Alternatively, download the .pkg installer and verify that the binary's location is in your PATH.

\bold{Linux:} Install Pandoc through your distribution's package manager (commonly installed in "/usr/bin" or "/usr/local/bin") or manually, and ensure the directory containing Pandoc is in your PATH.

If Pandoc is not found, this function may not work as intended.
}
\examples{
\donttest{
# Example usage:
data(iris)

new_names = c(
  "Sepal.Length" = "Sepal length (cm)" ,
  "Sepal.Width" = "Sepal width (cm)",
  "Petal.Length" = "Petal length (cm)",
  "Petal.Width" = "Petal width (cm)",
  "Species" = "Cultivar"
)

# Use the whole data.frame to generate an MS Word report and don't open it.
f_boxplot(iris,
           fancy_names = new_names,
           output_type = "word"
           )

# Use a formula to plot several response parameters (response 1 + response 2 etc)
# and generate a rmd output without boxplot_explanation.
data(mtcars)
f_boxplot(hp + disp ~ gear*cyl,
           data=mtcars,
           boxplot_explanation = FALSE,
           output_type = "word"
           )

# Capture the R Markdown output as a string and render it inline.
# Use output_type = "rmd" to get the markdown back as a character value
# instead of writing a file. Useful for embedding in a larger knitr document.
rmd <- f_boxplot(iris,
                 output_type         = "rmd",
                 boxplot_explanation = FALSE,
                 outliers            = FALSE
                 )

# Display it in the console
cat(rmd)

# ...or splice it into a knitr child chunk with results = "asis":
#   ```{r, echo=FALSE, results='asis'}
#   cat(rmd)
#   ```
}

}
\author{
Sander H. van Delden  \email{plantmind@proton.me} \cr
}
