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

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

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

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

\method{print}{summary.biserial_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}{A binary vector, matrix, or data frame. In data-frame mode, only
two-level columns are retained.}

\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
approximate large-sample confidence intervals derived from a Fisher
\eqn{z}-transformation of the biserial estimate.}

\item{p_value}{Logical (default \code{FALSE}). If \code{TRUE}, attach
model-based large-sample p-values, test statistics, and degrees of freedom
for each biserial estimate.}

\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.biserial_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{"Biserial 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{ci_text_size}{Text size for confidence intervals in the heatmap.}

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

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

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

\item{p_digits}{Integer; digits for biserial 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{biserial_corr} with rows corresponding to
the continuous variables in \code{data} and columns to the binary variables
in \code{y}. Matrix outputs carry attributes \code{method},
\code{description}, and \code{package = "matrixCorr"}. When
\code{p_value = TRUE}, the object also carries an \code{inference}
attribute with matrices \code{estimate}, \code{statistic},
\code{parameter}, \code{p_value}, and \code{n_obs}. When \code{ci = TRUE},
it additionally carries a \code{ci} attribute with matrices
\code{lwr.ci} and \code{upr.ci}, 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 biserial correlations between continuous variables in \code{data}
and binary variables in \code{y}. Both pairwise vector mode and rectangular
matrix/data-frame mode are supported.
}
\details{
The biserial correlation is the special two-category case of the polyserial
model. It assumes that a binary variable \eqn{Y} arises by thresholding an
unobserved standard-normal variable \eqn{Z} that is jointly normal with a
continuous variable \eqn{X}. Writing \eqn{p = P(Y = 1)} and
\eqn{q = 1-p}, let \eqn{z_p = \Phi^{-1}(p)} and \eqn{\phi(z_p)} be the
standard-normal density evaluated at \eqn{z_p}. If \eqn{\bar x_1} and
\eqn{\bar x_0} denote the sample means of \eqn{X} in the two observed groups
and \eqn{s_x} is the sample standard deviation of \eqn{X}, the usual
biserial estimator is
\deqn{
r_b =
\frac{\bar x_1 - \bar x_0}{s_x}
\frac{pq}{\phi(z_p)}.
}
This is exactly the estimator implemented in the underlying C++ kernel.

\strong{Assumptions.} The biserial coefficient is appropriate when the
observed binary variable is viewed as a thresholded version of an
unobserved continuous latent variable that is jointly normal with the
observed continuous variable. The optional p-values and confidence
intervals adopt this latent-normal interpretation together with the usual
large-sample approximations used for correlation coefficients. These
inferential quantities are therefore model-based and should not be
interpreted as distribution-free summaries.

\strong{Inference.} When \code{p_value = TRUE}, the package reports the
large-sample \eqn{t}-statistic
\deqn{
t = r_b \sqrt{\frac{n - 2}{1 - r_b^2}},
}
referenced to a Student \eqn{t}-distribution with \eqn{n - 2} degrees of
freedom. When \code{ci = TRUE}, the package forms an approximate Fisher
\eqn{z}-interval by transforming \eqn{r_b} with
\eqn{z = \operatorname{atanh}(r_b)}, using standard error
\eqn{1 / \sqrt{n - 3}}, and mapping the limits back with
\eqn{\tanh(\cdot)}. The CI is therefore an internal large-sample
extension and is only computed when explicitly requested.

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

Unlike the point-biserial correlation, which is just Pearson correlation on a
0/1 coding of the binary variable, the biserial coefficient explicitly
assumes an underlying latent normal threshold model and rescales the mean
difference accordingly.

\strong{Computational complexity.} If \code{data} has \eqn{p_x} continuous
columns and \code{y} has \eqn{p_y} binary columns, the matrix path computes
\eqn{p_x p_y} closed-form estimates with negligible extra memory beyond the
output matrix.
}
\examples{
\dontshow{if (requireNamespace("mnormt", quietly = TRUE)) withAutoprint(\{ # examplesIf}
set.seed(126)
n <- 1000
Sigma <- matrix(c(
  1.00, 0.35, 0.50, 0.25,
  0.35, 1.00, 0.30, 0.55,
  0.50, 0.30, 1.00, 0.40,
  0.25, 0.55, 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(
  g1 = Z[, 3] > stats::qnorm(0.65),
  g2 = Z[, 4] > stats::qnorm(0.55)
)

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

Fisher, R. A. (1921). On the probable error of a coefficient of
correlation deduced from a small sample. \emph{Metron}, 1, 3-32.
}
\author{
Thiago de Paula Oliveira
}
