% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kendall_corr.R
\name{kendall_tau}
\alias{kendall_tau}
\alias{print.kendall_matrix}
\alias{plot.kendall_matrix}
\alias{summary.kendall_matrix}
\alias{print.summary.kendall_matrix}
\title{Pairwise (or Two-Vector) Kendall's Tau Rank Correlation}
\usage{
kendall_tau(
  data,
  y = NULL,
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  conf_level = 0.95,
  ci_method = c("fieller", "if_el", "brown_benedetti"),
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  ...
)

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

\method{plot}{kendall_matrix}(
  x,
  title = "Kendall's Tau correlation heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)

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

\method{print}{summary.kendall_matrix}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{For matrix/data frame mode, a numeric matrix or a data frame with at least
two numeric columns. All non-numeric columns are excluded. For two-vector
mode, a numeric vector \code{x}.}

\item{y}{Optional numeric vector \code{y} of the same length as \code{data}
when \code{data} is a vector. If supplied, the function computes the
Kendall correlation \emph{between \code{data} and \code{y}} using a
low-overhead scalar path and returns a single number.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values.
\code{"pairwise"} recomputes each correlation 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 (default \code{FALSE}). If \code{TRUE}, attach pairwise
confidence intervals for the off-diagonal Kendall correlations in
matrix/data-frame mode.}

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

\item{ci_method}{Confidence-interval engine used when \code{ci = TRUE}.
Supported Kendall methods are \code{"fieller"} (default),
\code{"brown_benedetti"}, and \code{"if_el"}.}

\item{n_threads}{Integer \eqn{\geq 1}. Number of OpenMP threads. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\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{...}{Additional arguments passed to \code{ggplot2::theme()} or other
\code{ggplot2} layers.}

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

\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{ci_digits}{Integer; digits for Kendall confidence limits in the
pairwise summary.}

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

\item{title}{Plot title. Default is \code{"Kendall's Tau correlation
heatmap"}.}

\item{low_color}{Color for the minimum tau value. Default is
\code{"indianred1"}.}

\item{high_color}{Color for the maximum tau value. Default is
\code{"steelblue1"}.}

\item{mid_color}{Color for zero correlation. Default is \code{"white"}.}

\item{value_text_size}{Font size for displaying correlation values. Default
is \code{4}.}

\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{kendall_matrix}.}
}
\value{
\itemize{
\item If \code{y} is \code{NULL} and \code{data} is a matrix/data frame: a
symmetric numeric matrix where entry \code{(i, j)} is the Kendall's tau
correlation between the \code{i}-th and \code{j}-th numeric columns. When
\code{ci = TRUE}, the object also carries a \code{ci} attribute with
elements \code{est}, \code{lwr.ci}, \code{upr.ci}, \code{conf.level}, and
\code{ci.method}. Pairwise complete-case sample sizes are stored in
\code{attr(x, "diagnostics")$n_complete}.
\item If \code{y} is provided (two-vector mode): a single numeric scalar,
the Kendall's tau correlation between \code{data} and \code{y}.
}

Invisibly returns the \code{kendall_matrix} object.

A \code{ggplot} object representing the heatmap.
}
\description{
Computes pairwise Kendall's tau correlations for numeric data using a
high-performance 'C++' backend. Optional confidence intervals are available
for matrix and data-frame input.
}
\details{
Kendall's tau is a rank-based measure of association between two variables.
For a dataset with \eqn{n} observations on variables \eqn{X} and \eqn{Y},
let \eqn{n_0 = n(n - 1)/2} be the number of unordered pairs, \eqn{C} the
number of concordant pairs, and \eqn{D} the number of discordant pairs.
Let \eqn{T_x = \sum_g t_g (t_g - 1)/2} and \eqn{T_y = \sum_h u_h (u_h - 1)/2}
be the numbers of tied pairs within \eqn{X} and within \eqn{Y}, respectively,
where \eqn{t_g} and \eqn{u_h} are tie-group sizes in \eqn{X} and \eqn{Y}.

The tie-robust Kendall's tau-b is:
\deqn{ \tau_b = \frac{C - D}{\sqrt{(n_0 - T_x)\,(n_0 - T_y)}}. }
When there are no ties (\eqn{T_x = T_y = 0}), this reduces to tau-a:
\deqn{ \tau_a = \frac{C - D}{n(n-1)/2}. }

The function automatically handles ties. In degenerate cases where a
variable is constant (\eqn{n_0 = T_x} or \eqn{n_0 = T_y}), the tau-b
denominator is zero and the correlation is undefined (returned as \code{NA}
off the diagonal).

When \code{na_method = "pairwise"}, each \eqn{(i,j)} estimate is recomputed
on the pairwise complete-case overlap of columns \eqn{i} and \eqn{j}.
Confidence intervals use the observed pairwise-complete Kendall estimate and
the same pairwise complete-case overlap.

With \code{ci_method = "fieller"}, the interval is built on the Fisher-style
transformed scale \eqn{z = \operatorname{atanh}(\hat\tau)} using Fieller's
asymptotic standard error
\deqn{ \operatorname{SE}(z) = \sqrt{\frac{0.437}{n - 4}}, }
where \eqn{n} is the pairwise complete-case sample size. The interval is then
mapped back with \code{tanh()} and clipped to \eqn{[-1, 1]} for numerical
safety. This is the default Kendall CI and is intended to be the fast,
production-oriented choice.

With \code{ci_method = "brown_benedetti"}, the interval is computed on the
Kendall tau scale using the Brown-Benedetti large-sample variance for
Kendall's tau-b. This path is tie-aware, remains on the original Kendall
scale, and is intended as a conventional asymptotic alternative when a
direct tau-scale interval is preferred.

With \code{ci_method = "if_el"}, the interval is computed in 'C++' using an
influence-function empirical-likelihood construction built from the
linearised Kendall estimating equation. The lower and upper limits are found
by solving the empirical-likelihood ratio equation against the
\eqn{\chi^2_1}-cutoff implied by \code{conf_level}. This method is slower
than \code{"fieller"} and is intended for specialised inference.

\strong{Performance:}
\itemize{
\item In the \strong{two-vector mode} (\code{y} supplied), the C++ backend uses a
raw-double path with minimal overhead.
\item In the \strong{matrix/data-frame mode}, the no-missing estimate-only path
uses the Knight (1966) \eqn{O(n \log n)} algorithm. Pairwise-complete
inference paths recompute each pair on its complete-case overlap; the
\code{"brown_benedetti"} interval adds tie-aware large-sample variance
calculations and \code{"if_el"} adds extra per-pair likelihood solving.
}
}
\note{
Missing values are rejected when \code{na_method = "error"}. Columns
with fewer than two usable observations are excluded. Confidence intervals
are not available in the two-vector interface.
}
\examples{
# Basic usage with a matrix
mat <- cbind(a = rnorm(100), b = rnorm(100), c = rnorm(100))
kt <- kendall_tau(mat)
print(kt)
summary(kt)
plot(kt)

# Confidence intervals
kt_ci <- kendall_tau(mat[, 1:3], ci = TRUE)
print(kt_ci, show_ci = "yes")
summary(kt_ci)
estimate(kt_ci)
tidy(kt_ci)
ci(kt_ci)
confint(kt_ci)

# Two-vector mode (scalar path)
x <- rnorm(1000); y <- 0.5 * x + rnorm(1000)
kendall_tau(x, y)

# Including ties
tied_df <- data.frame(
  v1 = rep(1:5, each = 20),
  v2 = rep(5:1, each = 20),
  v3 = rnorm(100)
)
kt_tied <- kendall_tau(tied_df, ci = TRUE, ci_method = "fieller")
print(kt_tied, show_ci = "yes")

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

}
\references{
Kendall, M. G. (1938). A New Measure of Rank Correlation. \emph{Biometrika},
30(1/2), 81-93.

Knight, W. R. (1966). A Computer Method for Calculating Kendall's Tau with
Ungrouped Data. \emph{Journal of the American Statistical Association},
61(314), 436-439.

Fieller, E. C., Hartley, H. O., & Pearson, E. S. (1957). Tests for rank
correlation coefficients. I. \emph{Biometrika}, 44(3/4), 470-481.

Brown, M. B., & Benedetti, J. K. (1977). Sampling behavior of tests for
correlation in two-way contingency tables. \emph{Journal of the American
Statistical Association}, 72(358), 309-315.

Huang, Z., & Qin, G. (2023). Influence function-based confidence intervals
for the Kendall rank correlation coefficient. \emph{Computational
Statistics}, 38(2), 1041-1055.

Croux, C., & Dehon, C. (2010). Influence functions of the Spearman and
Kendall correlation measures. \emph{Statistical Methods & Applications},
19, 497-515.
}
\seealso{
\code{\link{print.kendall_matrix}}, \code{\link{plot.kendall_matrix}}
}
\author{
Thiago de Paula Oliveira
}
