% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/skipcor.R
\name{skipped_corr}
\alias{skipped_corr}
\alias{skipped_corr_masks}
\alias{print.skipped_corr}
\alias{plot.skipped_corr}
\alias{summary.skipped_corr}
\alias{print.summary.skipped_corr}
\title{Pairwise skipped correlation}
\usage{
skipped_corr(
  data,
  method = c("pearson", "spearman"),
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  p_value = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  return_masks = FALSE,
  stand = TRUE,
  outlier_rule = c("idealf", "mad"),
  cutoff = sqrt(stats::qchisq(0.975, df = 2)),
  n_boot = 2000L,
  p_adjust = c("none", "hochberg", "ecp"),
  fwe_level = 0.05,
  n_mc = 1000L,
  seed = NULL,
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE
)

skipped_corr_masks(x, var1 = NULL, var2 = NULL)

\method{print}{skipped_corr}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  ci_digits = 4,
  show_ci = NULL,
  show_p = c("auto", "yes", "no"),
  ...
)

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

\method{summary}{skipped_corr}(
  object,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{print}{summary.skipped_corr}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or a data frame with at least two numeric
columns. All non-numeric columns will be excluded.}

\item{method}{Correlation computed after removing projected outliers. One of
\code{"pearson"} (default) or \code{"spearman"}.}

\item{na_method}{Character scalar controlling missing-data handling.
With \code{"error"}, the function requires all retained numeric columns to
be free of missing or non-finite values and aborts otherwise. This is the
recommended setting when you want a single common sample size across all
pairs, reproducible skipped-row diagnostics on the same rows, or bootstrap
inference via \code{ci = TRUE} / \code{p_value = TRUE}.
\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.}

\item{ci}{Logical; if \code{TRUE}, attach percentile-bootstrap confidence
intervals for each skipped correlation using the Wilcox (2015) B2
resampling scheme. Default \code{FALSE}.}

\item{p_value}{Logical; if \code{TRUE}, attach bootstrap p-values for testing
whether each skipped correlation is zero. Default \code{FALSE}.}

\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. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{return_masks}{Logical; if \code{TRUE}, attach compact pairwise skipped-row
indices as an attribute. Default \code{FALSE}.}

\item{stand}{Logical; if \code{TRUE} (default), each variable in the pair is
centred by its median and divided by a robust scale estimate before the
projection outlier search. The scale estimate is the MAD when positive,
with fallback to \eqn{\mathrm{IQR}/1.34898} and then the usual sample
standard deviation if needed. This standardisation affects only outlier
detection, not the final correlation computed on the retained
observations.}

\item{outlier_rule}{One of \code{"idealf"} (default) or \code{"mad"}.
The default uses the ideal-fourths interquartile width of projected
distances; \code{"mad"} uses the median absolute deviation of projected
distances.}

\item{cutoff}{Positive numeric constant multiplying the projected spread in
the outlier rule
\eqn{\mathrm{med}(d_{i\cdot}) + cutoff \times s(d_{i\cdot})}. Larger
values flag fewer observations as outliers; smaller values flag more.
Default \code{sqrt(qchisq(0.975, df = 2))}.}

\item{n_boot}{Integer \eqn{\geq 2}. Number of bootstrap resamples used when
\code{ci = TRUE} or \code{p_value = TRUE}. Default \code{2000}.}

\item{p_adjust}{One of \code{"none"} (default), \code{"hochberg"}, or
\code{"ecp"}. Optional familywise-error procedure applied to the matrix of
bootstrap p-values. \code{"hochberg"} corresponds to method H in Wilcox,
Rousselet, and Pernet (2018); \code{"ecp"} corresponds to their simulated
critical-p-value method ECP.}

\item{fwe_level}{Familywise-error level used when
\code{p_adjust = "hochberg"} or \code{"ecp"}. Default \code{0.05}.}

\item{n_mc}{Integer \eqn{\geq 10}. Number of null Monte Carlo data sets used
when \code{p_adjust = "ecp"} to estimate the critical p-value. Default
\code{1000}.}

\item{seed}{Optional positive integer used to seed the bootstrap resampling
when \code{ci = TRUE} or \code{p_value = TRUE}. If \code{NULL}, a fresh
internal seed is generated.}

\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.skipped_corr}.}

\item{var1, var2}{Optional column names or 1-based column indices used by
\code{\link[=skipped_corr_masks]{skipped_corr_masks()}} to extract the skipped-row indices for one pair.}

\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{ci_digits}{Integer; digits for skipped-correlation confidence limits.}

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

\item{show_p}{One of \code{"auto"}, \code{"yes"}, \code{"no"}. For
\code{print()}, \code{"auto"} keeps the compact matrix-only display;
use \code{"yes"} to also print pairwise p-values.}

\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{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{skipped_corr}.}
}
\value{
A symmetric correlation matrix with class \code{skipped_corr} and
attributes \code{method = "skipped_correlation"}, \code{description}, and
\code{package = "matrixCorr"}. When \code{return_masks = TRUE}, the matrix
also carries a \code{skipped_masks} attribute containing compact pairwise
skipped-row indices. The \code{diagnostics} attribute stores per-pair
complete-case counts and skipped-row counts/proportions. When
\code{ci = TRUE} or \code{p_value = TRUE}, bootstrap inference matrices are
attached via attributes.
}
\description{
Computes all pairwise skipped correlation coefficients for the numeric
columns of a matrix or data frame using a high-performance 'C++' backend.

Skipped correlation detects bivariate outliers using a projection rule and
then computes Pearson or Spearman correlation on the retained observations.
It is designed for situations where marginally robust methods can still be
distorted by unusual points in the joint data cloud.
}
\details{
Let \eqn{X \in \mathbb{R}^{n \times p}} be a numeric matrix with rows as
observations and columns as variables. For a given pair of columns
\eqn{(x, y)}, write the observed bivariate points as
\eqn{u_i = (x_i, y_i)^\top}, \eqn{i=1,\ldots,n}. If \code{stand = TRUE},
each margin is first centred by its median and divided by a robust scale
estimate before outlier detection; otherwise the original pair is used. The
robust scale is the MAD when positive, with fallback to
\eqn{\mathrm{IQR}/1.34898} and then the usual sample standard deviation if
needed. Let \eqn{\tilde u_i} denote the resulting points and let \eqn{c} be
the componentwise median center of the detection cloud.

For each observation \eqn{i}, define the direction vector
\eqn{b_i = \tilde u_i - c}. When \eqn{\|b_i\| > 0}, all observations are
projected onto the line through \eqn{c} in direction \eqn{b_i}. The
projected distances are
\deqn{
d_{ij} \;=\; \frac{|(\tilde u_j - c)^\top b_i|}{\|b_i\|},
\qquad j=1,\ldots,n.
}
For each direction \eqn{i}, observation \eqn{j} is flagged as an outlier if

\deqn{
d_{ij} \;>\; \mathrm{med}(d_{i\cdot}) + g\, s(d_{i\cdot}),
\qquad g = \code{cutoff},
}
where \eqn{s(\cdot)} is either the ideal-fourths interquartile width
(\code{outlier_rule = "idealf"}) or the median absolute deviation
(\code{outlier_rule = "mad"}). An observation is removed if it is flagged
for at least one projection direction. The skipped correlation is then the
ordinary Pearson or Spearman correlation computed from the retained
observations:
\deqn{
r_{\mathrm{skip}}(x,y) \;=\;
\mathrm{cor}\!\left(x_{\mathcal{K}}, y_{\mathcal{K}}\right),
}
where \eqn{\mathcal{K}} is the index set of observations not flagged as
outliers.

Unlike marginally robust methods such as \code{pbcor()}, \code{wincor()},
or \code{bicor()}, skipped correlation is explicitly pairwise because
outlier detection depends on the joint geometry of each variable pair. As a
result, the reported matrix need not be positive semidefinite, even with
complete data.

\strong{Computational notes.} In the complete-data path, each column pair
requires a full bivariate projection search, so the dominant cost is higher
than for marginal robust methods. The implementation evaluates pairs in
'C++'; where available, pairs are processed with 'OpenMP' parallelism. With
\code{na_method = "pairwise"}, each pair is recomputed on its overlap of
non-missing rows. With \code{na_method = "complete"}, rows with any
non-finite value across the retained numeric columns are removed before any
pairwise outlier search. This gives a common row universe for all
skipped-correlation masks.

\strong{Bootstrap inference.} When \code{ci = TRUE} or \code{p_value = TRUE},
the implementation uses the percentile-bootstrap strategy studied by Wilcox
(2015). Each bootstrap replicate resamples whole observation pairs with
replacement, reruns the skipped-correlation outlier detection on the
resampled data, and recomputes the skipped correlation on the retained
observations. This corresponds to Wilcox's B2 method and avoids the
statistically unsatisfactory shortcut of removing outliers only once before
bootstrapping. Bootstrap inference currently requires complete data
(\code{na_method = "error"} or \code{"complete"}). When
\code{p_adjust = "hochberg"}, the
bootstrap p-values are processed with Hochberg's step-up procedure (method H
in Wilcox, Rousselet, and Pernet, 2018). When \code{p_adjust = "ecp"}, the
package follows their ECP method and simulates \code{n_mc} null data sets
from a \eqn{p}-variate normal distribution with identity covariance,
recomputes the pairwise bootstrap p-values for each null data set, stores the
minimum p-value from each run, and estimates the \code{fwe_level} quantile of
that null distribution using the Harrell-Davis estimator. Hypotheses are then
rejected when their observed bootstrap p-values are less than or equal to the
estimated critical p-value. The calibrated H1 procedure from Wilcox,
Rousselet, and Pernet (2018) is not currently implemented.
}
\examples{
set.seed(12)
X <- matrix(rnorm(160 * 4), ncol = 4)
X[1, 1] <- 9
X[1, 2] <- -8

R <- skipped_corr(X, method = "pearson")
print(R, digits = 2)
summary(R)
plot(R)

Rm <- skipped_corr(X, method = "pearson", return_masks = TRUE)
skipped_corr_masks(Rm, 1, 2)

# Example 1:
Xm <- as.matrix(datasets::mtcars[, c("mpg", "disp", "hp", "wt")])
Rm2 <- skipped_corr(Xm, method = "spearman")
print(Rm2, digits = 2)

# Example 2:
Ri <- skipped_corr(Xm, method = "pearson", ci = TRUE, n_boot = 40, seed = 1)
ci(Ri)
confint(Ri)
tidy(Ri)

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

}
\references{
Wilcox, R. R. (2004). Inferences based on a skipped correlation coefficient.
Journal of Applied Statistics, 31(2), 131-143.
\doi{10.1080/0266476032000148821}

Wilcox, R. R. (2015). Inferences about the skipped correlation coefficient:
Dealing with heteroscedasticity and non-normality. Journal of Modern Applied
Statistical Methods, 14(1), 172-188.
\doi{10.22237/jmasm/1430453580}

Wilcox, R. R., Rousselet, G. A., & Pernet, C. R. (2018). Improved methods
for making inferences about multiple skipped correlations. Journal of
Statistical Computation and Simulation, 88(16), 3116-3131.
\doi{10.1080/00949655.2018.1501051}
}
\seealso{
\code{\link[=pbcor]{pbcor()}}, \code{\link[=wincor]{wincor()}}, \code{\link[=bicor]{bicor()}}
}
\author{
Thiago de Paula Oliveira
}
