% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pbcor.R
\name{pbcor}
\alias{pbcor}
\alias{print.pbcor}
\alias{plot.pbcor}
\alias{summary.pbcor}
\alias{print.summary.pbcor}
\title{Percentage bend correlation}
\usage{
pbcor(
  data,
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  p_value = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  beta = 0.2,
  n_boot = 500L,
  seed = NULL,
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE
)

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

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

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

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

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values.
\code{"pairwise"} recomputes each estimate on its own pairwise
complete-case overlap. This is permissive, but different matrix entries
may be based on different rows. \code{"complete"} performs listwise
deletion once across the retained numeric columns and then computes the
estimator on the common complete sample.
With \code{"pairwise"}, each correlation is computed on the overlapping
complete rows for the column pair.}

\item{ci}{Logical (default \code{FALSE}). If \code{TRUE}, attach percentile
bootstrap confidence intervals for each pairwise estimate.}

\item{p_value}{Logical (default \code{FALSE}). If \code{TRUE}, attach the
method-specific large-sample test statistic and two-sided p-value for each
pairwise estimate.}

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

\item{n_threads}{Integer \eqn{\geq 1}. Number of OpenMP threads used for the
point-estimate matrix computation. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{beta}{Bending constant in \code{[0, 0.5)} that sets the cutoff used to
bend standardised deviations toward the interval \eqn{[-1, 1]}. Larger
values cause more observations to be bent and increase resistance to
marginal outliers. Default \code{0.2}. See Details.}

\item{n_boot}{Integer \eqn{\geq 1}. Number of bootstrap resamples used when
\code{ci = TRUE}. Default \code{500}.}

\item{seed}{Optional positive integer used to seed the bootstrap resampling
when \code{ci = TRUE}. If \code{NULL}, the current random-number stream is
used.}

\item{output}{Output representation for the computed estimates.
\itemize{
\item \code{"matrix"} (default): full dense matrix; best when you need
matrix algebra, dense heatmaps, or full compatibility with existing code.
\item \code{"sparse"}: sparse matrix from \pkg{Matrix} containing only
retained entries; best when many values are dropped by thresholding.
\item \code{"edge_list"}: long-form data frame with columns
\code{row}, \code{col}, \code{value}; convenient for filtering, joins,
and network-style workflows.
}}

\item{threshold}{Non-negative absolute-value filter for non-matrix outputs:
keep entries with \code{abs(value) >= threshold}. Use
\code{threshold > 0} when you want only stronger associations (typically
with \code{output = "sparse"} or \code{"edge_list"}). Keep
\code{threshold = 0} to retain all values. Must be \code{0} when
\code{output = "matrix"}.}

\item{diag}{Logical; whether to include diagonal entries in
\code{"sparse"} and \code{"edge_list"} outputs.}

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

\item{digits}{Integer; number of digits 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{...}{Additional arguments passed to the underlying print or plot helper.}

\item{title}{Character; plot title.}

\item{low_color, high_color, mid_color}{Colors used in the heatmap.}

\item{value_text_size}{Numeric text size for overlaid cell values.}

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

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

\item{ci_digits}{Integer; digits used for confidence limits in pairwise
summaries.}

\item{p_digits}{Integer; digits used for p-values in pairwise summaries.}
}
\value{
A symmetric correlation matrix with class \code{pbcor} and
attributes \code{method = "percentage_bend_correlation"},
\code{description}, and \code{package = "matrixCorr"}. When
\code{ci = TRUE}, the returned object 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")}. When \code{p_value = TRUE}, it also carries
an \code{inference} attribute with elements \code{estimate},
\code{statistic}, \code{parameter}, \code{p_value}, \code{n_obs}, and
\code{alternative}. When either inferential option is requested, the
object also carries \code{diagnostics$n_complete}.
}
\description{
Computes all pairwise percentage bend correlations for the numeric columns of
a matrix or data frame. Percentage bend correlation limits the influence of
extreme marginal observations by bending standardised deviations into the
interval \eqn{[-1, 1]}, yielding a Pearson-like measure that is robust to
outliers and heavy tails.
}
\details{
Let \eqn{X \in \mathbb{R}^{n \times p}} be a numeric matrix with rows as
observations and columns as variables. For a column
\eqn{x = (x_i)_{i=1}^n}, let \eqn{m_x = \mathrm{med}(x)} and define
\eqn{\omega_\beta(x)} as the \eqn{\lfloor (1-\beta)n \rfloor}-th order
statistic of \eqn{|x_i - m_x|}. Larger values of \code{beta} reduce
\eqn{\omega_\beta(x)}, so more observations are bent to the bounds
\eqn{-1} and \eqn{1}.

The one-step percentage-bend location is
\deqn{
\hat\theta_{pb}(x) =
\frac{\sum_{i: |\psi_i| \le 1} x_i + \omega_\beta(x)(i_2 - i_1)}
     {n - i_1 - i_2},
\qquad
\psi_i = \frac{x_i - m_x}{\omega_\beta(x)},
}
where \eqn{i_1 = \sum_{i=1}^n \mathbf{1}(\psi_i < -1)} and
\eqn{i_2 = \sum_{i=1}^n \mathbf{1}(\psi_i > 1)}. The bent scores are
\deqn{
a_i = \max\!\left\{-1,\; \min\!\left(1,\frac{x_i - \hat\theta_{pb}(x)}
{\omega_\beta(x)}\right)\right\},
}
and likewise \eqn{b_i} for a second column \eqn{y}. The percentage bend
correlation for the pair \eqn{(x,y)} is
\deqn{
r_{pb}(x,y) =
\frac{\sum_{i=1}^n a_i b_i}
     {\sqrt{\sum_{i=1}^n a_i^2}\sqrt{\sum_{i=1}^n b_i^2}}.
}

In the complete-data path, the bent score vectors are computed once per
column and collected into a matrix \eqn{A = [a_{\cdot 1}, \ldots, a_{\cdot p}]},
after which the correlation matrix is formed from their cross-products:
\deqn{
R_{pb} = D_A^{-1/2} A^\top A D_A^{-1/2},
\qquad
D_A = \mathrm{diag}(a_{\cdot 1}^\top a_{\cdot 1}, \ldots,
a_{\cdot p}^\top a_{\cdot p}).
}
If a column yields an undefined bent-score denominator, the corresponding row
and column are returned as \code{NA}. With \code{na_method = "pairwise"},
each pair is recomputed on its complete-case overlap. As with pairwise
Pearson correlation, this pairwise path can break positive semidefiniteness.

When \code{p_value = TRUE}, the method-specific test statistic for a pairwise
estimate \eqn{r_{pb}} based on \eqn{n_{ij}} complete observations is
\deqn{
T_{ij} = r_{pb,ij}\sqrt{\frac{n_{ij} - 2}{1 - r_{pb,ij}^2}},
}
and the reported p-value is the two-sided Student-\eqn{t} tail probability
with \eqn{n_{ij}-2} degrees of freedom. When \code{ci = TRUE}, the interval
is a percentile bootstrap interval based on \eqn{n_{\mathrm{boot}}}
resamples drawn from the pairwise complete cases. If
\eqn{\tilde r_{pb,(1)} \le \cdots \le \tilde r_{pb,(B)}} denotes the sorted
bootstrap sample of finite estimates with \eqn{B} retained resamples, the
reported limits are
\deqn{
\tilde r_{pb,(\ell)} \quad \text{and} \quad \tilde r_{pb,(u)},
}
where \eqn{\ell = \lfloor (\alpha/2) B + 0.5 \rfloor} and
\eqn{u = \lfloor (1-\alpha/2) B + 0.5 \rfloor} for
\eqn{\alpha = 1 - \mathrm{conf\_level}}. Resamples that yield undefined
estimates are discarded before the percentile limits are formed.

\strong{Computational complexity.} In the complete-data path, forming the
bent scores requires sorting within each column and the cross-product step
costs \eqn{O(n p^2)} with \eqn{O(p^2)} output storage. When
\code{ci = TRUE}, the bootstrap cost is incurred separately for each column
pair.
}
\examples{
set.seed(10)
X <- matrix(rnorm(150 * 4), ncol = 4)
X[sample(length(X), 8)] <- X[sample(length(X), 8)] + 10

R <- pbcor(X)
print(R, digits = 2)
summary(R)
estimate(R)
tidy(R)
plot(R)

## Bootstrap confidence intervals
R_ci <- pbcor(X, ci = TRUE, n_boot = 49, seed = 10)
ci(R_ci)
confint(R_ci)

# Interactive viewing (requires shiny)
if (interactive() && requireNamespace("shiny", quietly = TRUE)) {
  view_corr_shiny(R)
}

}
\references{
Wilcox, R. R. (1994). The percentage bend correlation coefficient.
Psychometrika, 59(4), 601-616. \doi{10.1007/BF02294395}
}
\seealso{
\code{\link[=wincor]{wincor()}}, \code{\link[=skipped_corr]{skipped_corr()}}, \code{\link[=bicor]{bicor()}}
}
\author{
Thiago de Paula Oliveira
}
