% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/latent_corr.R
\name{polyserial}
\alias{polyserial}
\alias{print.polyserial_corr}
\alias{plot.polyserial_corr}
\alias{summary.polyserial_corr}
\alias{print.summary.polyserial_corr}
\title{Polyserial Correlation Between Continuous and Ordinal Variables}
\usage{
polyserial(data, y, na_method = c("error", "pairwise"), ci = FALSE, p_value = FALSE,
  conf_level = 0.95, ...)

\method{print}{polyserial_corr}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{polyserial_corr}(
  x,
  title = "Polyserial correlation heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  show_value = TRUE,
  ...
)

\method{summary}{polyserial_corr}(
  object,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  ci_digits = 3,
  p_digits = 4,
  show_ci = NULL,
  ...
)

\method{print}{summary.polyserial_corr}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{A numeric vector, matrix, or data frame containing continuous
variables.}

\item{y}{An ordinal vector, matrix, or data frame containing ordinal
variables. Supported columns are factors, ordered factors, logical values,
or integer-like numerics.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing values. \code{"pairwise"} uses pairwise
complete cases.}

\item{ci}{Logical (default \code{FALSE}). If \code{TRUE}, attach
model-based large-sample Wald confidence intervals derived from the observed
information matrix of the latent-variable likelihood.}

\item{p_value}{Logical (default \code{FALSE}). If \code{TRUE}, attach
model-based large-sample Wald p-values and test statistics for each
estimated latent correlation.}

\item{conf_level}{Confidence level used when \code{ci = TRUE}. Default is
\code{0.95}.}

\item{...}{Additional arguments passed to \code{print()}.}

\item{x}{An object of class \code{summary.polyserial_corr}.}

\item{digits}{Integer; number of decimal places to print.}

\item{n}{Optional row threshold for compact preview output.}

\item{topn}{Optional number of leading/trailing rows to show when truncated.}

\item{max_vars}{Optional maximum number of visible columns; \code{NULL} derives this
from console width.}

\item{width}{Optional display width; defaults to \code{getOption("width")}.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{title}{Plot title. Default is \code{"Polyserial correlation heatmap"}.}

\item{low_color}{Color for the minimum correlation.}

\item{high_color}{Color for the maximum correlation.}

\item{mid_color}{Color for zero correlation.}

\item{value_text_size}{Font size used in tile labels.}

\item{show_value}{Logical; if \code{TRUE} (default), overlay numeric values
on the heatmap tiles.}

\item{object}{An object of class \code{polyserial_corr}.}

\item{ci_digits}{Integer; digits for confidence limits in the pairwise
summary.}

\item{p_digits}{Integer; digits for p-values in the pairwise summary.}
}
\value{
If both \code{data} and \code{y} are vectors, a numeric scalar. Otherwise a
numeric matrix of class \code{polyserial_corr} with rows corresponding to
the continuous variables in \code{data} and columns to the ordinal variables
in \code{y}. Matrix outputs carry attributes \code{method},
\code{description}, and \code{package = "matrixCorr"}. When
\code{p_value = TRUE}, the returned object also carries an \code{inference}
attribute with elements \code{estimate}, \code{statistic}, \code{parameter},
\code{p_value}, and \code{n_obs}. When \code{ci = TRUE}, it also carries a
\code{ci} attribute with elements \code{est}, \code{lwr.ci},
\code{upr.ci}, \code{conf.level}, and \code{ci.method}, plus
\code{attr(x, "conf.level")}. Scalar outputs keep the same point estimate
and gain the same metadata only when inference is requested.
}
\description{
Computes polyserial correlations between continuous variables in \code{data}
and ordinal variables in \code{y}. Both pairwise vector mode and rectangular
matrix/data-frame mode are supported.
}
\details{
The polyserial correlation assumes a latent bivariate normal model between a
continuous variable and an unobserved continuous propensity underlying an
ordinal variable. Let
\eqn{(X, Z)^\top \sim N_2(0, \Sigma)} with
\eqn{\mathrm{corr}(X,Z)=\rho}, and suppose the observed ordinal response
\eqn{Y} is formed by cut-points
\eqn{-\infty = \beta_0 < \beta_1 < \cdots < \beta_K = \infty}:
\deqn{
Y = k \iff \beta_{k-1} < Z \le \beta_k.
}
After standardising the observed continuous variable \eqn{X}, the thresholds
are estimated from the marginal proportions of \eqn{Y}. Conditional on an
observed \eqn{x_i}, the category probability is
\deqn{
\Pr(Y_i = k \mid X_i = x_i, \rho)
=
\Phi\!\left(\frac{\beta_k - \rho x_i}{\sqrt{1-\rho^2}}\right)
-
\Phi\!\left(\frac{\beta_{k-1} - \rho x_i}{\sqrt{1-\rho^2}}\right).
}
The returned estimate maximises the log-likelihood
\deqn{
\ell(\rho) = \sum_{i=1}^{n}\log \Pr(Y_i = y_i \mid X_i = x_i, \rho)
}
over \eqn{\rho \in (-1,1)} via a one-dimensional Brent search in C++.

\strong{Assumptions.} The coefficient is appropriate when the ordinal
variable is viewed as the discretised version of a latent normal variable
that is jointly normal with the observed continuous variable. The optional
p-values and confidence intervals adopt this latent-normal interpretation
and use the same likelihood that defines the polyserial estimate. These
inferential quantities are therefore model-based and should not be
interpreted as distribution-free summaries.

\strong{Inference.} When \code{ci = TRUE} or \code{p_value = TRUE}, the
function refits the pairwise polyserial model by maximum likelihood and
obtains the observed information matrix numerically in C++. The reported
confidence interval is a Wald interval
\eqn{\hat\rho \pm z_{1-\alpha/2}\operatorname{SE}(\hat\rho)}, and the
reported p-value is from the large-sample Wald \eqn{z}-test for
\eqn{H_0:\rho = 0}. These inferential quantities are only computed when
explicitly requested.

In vector mode a single estimate is returned. In matrix/data-frame mode,
every numeric column of \code{data} is paired with every ordinal column of
\code{y}, producing a rectangular matrix of continuous-by-ordinal
polyserial correlations.

\strong{Computational complexity.} If \code{data} has \eqn{p_x} continuous
columns and \code{y} has \eqn{p_y} ordinal columns, the matrix path computes
\eqn{p_x p_y} separate one-parameter likelihood optimisations.
}
\examples{
\dontshow{if (requireNamespace("mnormt", quietly = TRUE)) withAutoprint(\{ # examplesIf}
set.seed(125)
n <- 1000
Sigma <- matrix(c(
  1.00, 0.30, 0.55, 0.20,
  0.30, 1.00, 0.25, 0.50,
  0.55, 0.25, 1.00, 0.40,
  0.20, 0.50, 0.40, 1.00
), 4, 4, byrow = TRUE)

Z <- mnormt::rmnorm(n = n, mean = rep(0, 4), varcov = Sigma)
X <- data.frame(x1 = Z[, 1], x2 = Z[, 2])
Y <- data.frame(
  y1 = ordered(cut(
    Z[, 3],
    breaks = c(-Inf, -0.5, 0.7, Inf),
    labels = c("low", "mid", "high")
  )),
  y2 = ordered(cut(
    Z[, 4],
    breaks = c(-Inf, -1.0, 0.0, 1.0, Inf),
    labels = c("1", "2", "3", "4")
  ))
)

ps <- polyserial(X, Y)
print(ps, digits = 3)
summary(ps)
estimate(ps)
tidy(ps)
ps_ci <- polyserial(X, Y, ci = TRUE)
ci(ps_ci)
confint(ps_ci)
plot(ps)
\dontshow{\}) # examplesIf}
}
\references{
Olsson, U., Drasgow, F., & Dorans, N. J. (1982). The polyserial
correlation coefficient. \emph{Psychometrika}, 47(3), 337-347.
}
\author{
Thiago de Paula Oliveira
}
