% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/auto_correlate.R
\name{auto_correlate}
\alias{auto_correlate}
\title{Automatic correlations}
\usage{
auto_correlate(
  data,
  corr = c("kendall", "pearson", "spearman"),
  ordinal_categories = 7,
  forcePD = TRUE,
  na_data = c("pairwise", "listwise"),
  empty_method = c("none", "zero", "all"),
  empty_value = c("none", "point_five", "one_over"),
  forceReturn = FALSE,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{data}{Matrix or data frame.
Should consist only of variables to be used in the analysis}

\item{corr}{Character (length = 1).
The standard correlation method to be used.
Defaults to \code{"pearson"}.
Using \code{"pearson"} will compute polychoric, tetrachoric, polyserial,
and biserial correlations for categorical and categorical/continuous correlations
by default. To obtain \code{"pearson"} correlations regardless, use \code{\link{cor}}.
Other options of \code{"kendall"} and \code{"spearman"} are provided for
completeness and use \code{\link{cor}}}

\item{ordinal_categories}{Numeric (length = 1).
\emph{Up to} the number of categories \emph{before} a variable is considered continuous.
Defaults to \code{7} categories before \code{8} is considered continuous}

\item{forcePD}{Boolean (length = 1).
Whether positive definite matrix should be enforced.
Defaults to \code{TRUE}}

\item{na_data}{Character (length = 1).
How should missing data be handled?
Defaults to \code{"pairwise"}.
Available options:

\itemize{

\item \code{"pairwise"} --- Computes correlation for all available
cases between two variables

\item \code{"listwise"} --- Computes correlation for all complete
cases in the dataset

}}

\item{empty_method}{Character (length = 1).
Method for empty cell correction in \code{\link[L0ggm]{polychoric_matrix}}.
Defaults to \code{"none"}
Available options:

\itemize{

\item \code{"none"} --- Adds no value (\code{empty_value = "none"})
to the empirical joint frequency table between two variables

\item \code{"zero"} --- Adds \code{empty_value} to the cells with
zero in the joint frequency table between two variables

\item \code{"all"} --- Adds \code{empty_value} to all
in the joint frequency table between two variables

}}

\item{empty_value}{Character (length = 1).
Value to add to the joint frequency table cells in \code{\link[L0ggm]{polychoric_matrix}}.
Defaults to \code{"none"}.
Accepts numeric values between 0 and 1 or specific methods:

\itemize{

\item \code{"none"} --- Adds no value (\code{0}) to the empirical
joint  frequency table between two variables

\item \code{"point_five"} --- Adds \code{0.5} to the cells
defined by \code{empty_method}

\item \code{"one_over"} --- Adds \code{1 / n} where \code{n} equals the
number of cells based on \code{empty_method}. For
\code{empty_method = "zero"}, \code{n} equals the number of zero cells

}}

\item{forceReturn}{Boolean (length = 1).
Whether correlation matrix should be forced to return.
Defaults to \code{FALSE}.
Set to \code{TRUE} to receive the correlation matrix "as is"}

\item{verbose}{Boolean (length = 1).
Whether messages should be printed.
Defaults to \code{FALSE}}

\item{...}{Not actually used but makes it easier for general functionality
in the package}
}
\value{
A symmetric numeric matrix of dimension \eqn{p \times p}, where
\eqn{p} is the number of variables in \code{data}, with values in
\eqn{[-1, 1]} and ones on the diagonal. The correlation method used for
each pair of variables depends on their types when \code{corr = "pearson"}
(the default): polychoric for ordinal-ordinal pairs, polyserial for
ordinal-continuous pairs, and Pearson's for continuous-continuous pairs,
where \emph{ordinal} means having at most \code{ordinal_categories} unique
values. When \code{corr} is \code{"kendall"} or \code{"spearman"},
\code{\link[stats]{cor}} is used for all pairs regardless of variable
type. Row and column names are inherited from \code{data}. When
\code{forcePD = TRUE} (default) and the resulting matrix is not positive
definite, the nearest positive definite matrix is returned via
\code{\link[Matrix]{nearPD}}.
}
\description{
Automatically computes the proper correlations between
continuous and categorical variables. \code{NA} values are not treated
as categories
}
\examples{
# Obtain correlations
R <- auto_correlate(basic_smallworld)

}
\author{
Alexander P. Christensen <alexpaulchristensen@gmail.com>
}
