% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fcorplot.R
\name{f_corplot}
\alias{f_corplot}
\title{Correlation Plots with Factor Detection and Multiple Correlation Coefficients}
\usage{
f_corplot(
  data,
  detect_factors = TRUE,
  factor_table = FALSE,
  factor_exclude = NULL,
  factor_select = NULL,
  unique_num_treshold = 8,
  repeats_threshold = 2,
  color_factor = "auto",
  shape_factor = "auto",
  print_legend = TRUE,
  fancy_names = NULL,
  ordinal_vars = NULL,
  width = 15,
  height = 15,
  res = 600,
  pointsize = 10,
  close_generated_files = FALSE,
  open_generated_files = interactive(),
  output_type = "word",
  save_as = NULL,
  save_in_wdir = FALSE
)
}
\arguments{
\item{data}{A \code{data.frame} containing the dataset. Must include at least
two numeric variables.}

\item{detect_factors}{Logical. If \code{TRUE}, factor variables are
automatically detected for colouring and shaping points. Default \code{TRUE}.}

\item{factor_table}{Logical. If \code{TRUE}, prints a detailed table of
converted factors to the console. Default \code{FALSE}.}

\item{factor_exclude}{A character vector specifying the names of the columns NOT to convert into factors. If \code{NULL}, no columns are excluded. Default is \code{NULL}.}

\item{factor_select}{A character vector specifying the names of the columns to convert into factors. If \code{NULL}, the function automatically detects columns that should be factors based on their data type and unique value count. Default is \code{NULL}.}

\item{unique_num_treshold}{Numeric. A threshold of the amount of unique numbers a numeric column should have to keep it numeric, i.e. omit factor conversion. Default \code{8}.}

\item{repeats_threshold}{Numeric. A threshold of the minimal number of repeats a numeric column should have to convert it to a factor. Default \code{2}.}

\item{color_factor}{Character. Name of the factor variable used for point
colours; \code{"auto"} selects automatically. Default \code{"auto"}.}

\item{shape_factor}{Character. Name of the factor variable used for point
shapes; \code{"auto"} selects automatically. Default \code{"auto"}.}

\item{print_legend}{Logical. If \code{TRUE}, a separate legend file is
created. Default \code{TRUE}.}

\item{fancy_names}{Named character vector or \code{NULL}. Maps column names
to display names used in the plot and legend.}

\item{ordinal_vars}{Character vector or \code{NULL}. Names of variables to
treat as ordinal. Ordered factors are coerced to integer ranks; other
non-numeric types are coerced similarly. Their diagonal labels are
italicised and Pearson \eqn{r}{r} is greyed and bracketed for any pair that
involves them. Ordinal variables are included in the correlation panels but
excluded from aesthetic factor detection. Default \code{NULL}.}

\item{width}{Numeric. Plot width in centimetres. Default 15.}

\item{height}{Numeric. Plot height in centimetres. Default 15.}

\item{res}{Numeric. Resolution in DPI. Default 600.}

\item{pointsize}{Numeric. Base font size. Default 8.}

\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{output_type}{Character. One of \code{"pdf"}, \code{"word"},
\code{"png"}, or \code{"rmd"}. Default \code{"word"}.}

\item{save_as}{Character or \code{NULL}. Output file path without extension.
A full path, a filename, or a directory (with trailing slash) are all
accepted. Providing an extension overrides \code{output_type}.
Default saves to \code{tempdir()}.}

\item{save_in_wdir}{Logical. If \code{TRUE}, saves to the working directory.
Overridden by \code{save_as}. Default \code{FALSE}.}
}
\value{
No value is returned to the R environment. Output files are saved
  and opened automatically.
}
\description{
Creates correlation plots for numeric variables in a data frame. The upper
triangle displays Pearson \eqn{r}{r}, Spearman \eqn{\rho}{rho}, and Kendall
\eqn{\tau}{tau} simultaneously for each pair. Factor variables are automatically detected and
used for grouping, i.e. point colouring and shaping. Ordinal variables are supported via
\code{ordinal_vars}: their diagonal labels are italicised and Pearson \eqn{r}{r}
is greyed and bracketed for any pair that involves them.A separate legend file documents both
the grouping factors and the meaning of all three correlation symbols.
}
\details{
\itemize{
  \item \strong{Three correlations per panel:} Every upper-triangle panel
    shows \eqn{r}{r} (Pearson), \eqn{\rho}{rho} (Spearman), and \eqn{\tau}{tau}
    (Kendall) stacked vertically, so the reader can choose the most
    appropriate coefficient for each variable pair.
  \item \strong{Ordinal variables:} Specify column names with
    \code{ordinal_vars}. Those variables appear in italic on the diagonal.
    For any pair where at least one variable is ordinal, Pearson \eqn{r}{r} is
    shown greyed and in parentheses to signal it is technically inappropriate;
    Spearman and Kendall remain prominent.
  \item \strong{Factor detection:} Only unordered factors are used for
    colour/shape aesthetics. Ordered factors (\code{is.ordered()}) are
    treated as ordinal data, not as grouping variables.
  \item \strong{Legend:} The legend file documents the grouping factor levels
    (when present) and always includes an explanation of all three
    correlation symbols whenever a legend is generated.
  \item \strong{Constant columns:} Zero-variance columns produce \code{NA}
    in all correlation panels.
}

This function requires [Pandoc](https://github.com/jgm/pandoc/releases/tag) (version 1.12.3 or higher), a universal document converter.
\itemize{
\item \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.
\item \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.
\item \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.

\item If Pandoc is not found, this function may not work as intended.
}
}
\examples{
data(mtcars)
mtcars_sub <- subset(mtcars, select = -c(am, qsec, vs))
f_corplot(mtcars_sub,
          color_factor = "gear",
          shape_factor = "cyl",
          output_type  = "png"
          )

# With ordinal variables
data(iris)
fancy_names <- c(Sepal.Length = "Sepal Length (cm)",
                 Sepal.Width  = "Sepal Width (cm)")
f_corplot(iris,
          fancy_names  = fancy_names,
          ordinal_vars = "Petal.Width",
          output_type  = "png",
          open_generated_files = FALSE)

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