% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hsic.R
\name{hsic}
\alias{hsic}
\alias{print.hsic}
\alias{summary.hsic}
\alias{print.summary.hsic}
\alias{plot.hsic}
\title{Pairwise Hilbert-Schmidt Independence Criterion}
\usage{
hsic(
  data,
  kernel = c("gaussian", "linear", "laplace", "polynomial"),
  bandwidth = c("median", "silverman", "scott"),
  normalise = TRUE,
  estimator = c("biased", "unbiased"),
  na_method = c("error", "pairwise", "complete"),
  p_value = FALSE,
  B = 499L,
  seed = NULL,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE
)

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

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

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

\method{plot}{hsic}(
  x,
  title = NULL,
  low_color = "white",
  high_color = "steelblue1",
  value_text_size = 4,
  show_value = TRUE,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or data frame with at least two numeric columns.
Non-numeric columns are dropped.}

\item{kernel}{Kernel used to build univariate Gram matrices. Supported
options are \code{"gaussian"} (RBF), \code{"linear"}, \code{"laplace"}, and
\code{"polynomial"}.}

\item{bandwidth}{Bandwidth rule for Gaussian and Laplace kernels.
\code{"median"} uses the upper median of finite off-diagonal pairwise
distances divided by \eqn{\sqrt{2}}, with fallback \code{0.001} for degenerate
columns. \code{"silverman"} uses Silverman's univariate rule, and \code{"scott"}
uses Scott's univariate rule. Linear and polynomial kernels ignore this
argument.}

\item{normalise}{Logical. If \code{TRUE}, return the normalised kernel
independence correlation. If \code{FALSE}, return raw HSIC.}

\item{estimator}{HSIC estimator. \code{"biased"} uses the stable V-statistic
\eqn{n^{-2}\mathrm{tr}(KHLH)}. \code{"unbiased"} uses the U-statistic estimator
with zero diagonal Gram matrices and requires at least four complete
observations per pair.}

\item{na_method}{Missing-data handling. \code{"error"} rejects missing, \code{NaN}, and
infinite values; \code{"complete"} performs one listwise finite-row deletion;
\code{"pairwise"} recomputes each pair on its pairwise complete rows.}

\item{p_value}{Logical. If \code{TRUE}, attach permutation p-values for the HSIC
independence test.}

\item{B}{Positive integer. Number of permutations used when
\code{p_value = TRUE}.}

\item{seed}{Optional positive integer seed for reproducible permutation
inference. The seed is passed to the C++ permutation engine and does not
mutate the user's global R RNG state.}

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

\item{output}{Output representation: \code{"matrix"}, \code{"sparse"}, or
\code{"edge_list"}.}

\item{threshold}{Non-negative absolute-value filter for non-matrix outputs.
Must be \code{0} when \code{output = "matrix"}.}

\item{diag}{Logical; whether to include diagonal entries in sparse and
edge-list outputs.}

\item{x}{An object of class \code{hsic}.}

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

\item{width}{Optional display width.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}; accepted for compatibility with
shared matrix-printing methods.}

\item{...}{Additional arguments passed to print or plot methods.}

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

\item{title}{Optional plot title.}

\item{low_color}{Colour for low HSIC values.}

\item{high_color}{Colour for high HSIC values.}

\item{value_text_size}{Font size for tile labels.}

\item{show_value}{Logical; whether to overlay numeric values on the heatmap.}
}
\value{
A matrix-like correlation result. With \code{normalise = TRUE}, entries
are normalised kernel independence correlations and the diagonal is \code{1}
when the variable has positive kernel self-dependence. With
\code{normalise = FALSE}, entries are raw HSIC estimates. Attributes record the
kernel, bandwidth rule, estimator, raw HSIC matrix, diagnostics, and
optional permutation inference.
}
\description{
Computes pairwise kernel dependence measures for the numeric columns of a
matrix or data frame using the Hilbert-Schmidt Independence Criterion
(HSIC). By default, \code{hsic()} returns a normalised kernel independence
correlation in \verb{[0, 1]}, analogous to a distance-correlation matrix.
}
\details{
For paired observations \eqn{(x_i, y_i)}, HSIC measures the squared
Hilbert-Schmidt norm of the RKHS cross-covariance operator. With centred Gram
matrices \eqn{K_c = HKH} and \eqn{L_c = HLH}, the biased empirical estimator
is
\deqn{
  \widehat{\mathrm{HSIC}}_b =
  \frac{1}{n^2}\mathrm{tr}(KHLH)
  =
  \frac{1}{n^2}\sum_{ij} (K_c)_{ij}(L_c)_{ij}.
}

With \code{normalise = TRUE}, the returned matrix contains the kernel
independence correlation
\deqn{
  \widehat{\mathrm{kCor}}(X,Y) =
  \frac{\widehat{\mathrm{HSIC}}(X,Y)}
       {\sqrt{\widehat{\mathrm{HSIC}}(X,X)
              \widehat{\mathrm{HSIC}}(Y,Y)}}.
}
The raw HSIC matrix is stored in \code{attr(x, "hsic_raw")}. When
\code{estimator = "unbiased"}, raw HSIC can be slightly negative in finite
samples; these signed raw values are retained in \code{hsic_raw}, while the
displayed normalised coefficient is clipped only for the user-facing matrix.

Kernel formulas are:
Gaussian \eqn{\exp(-|x_i - x_j|^2 / (2\sigma^2))}, Laplace
\eqn{\exp(-|x_i - x_j| / \sigma)}, linear \eqn{x_i x_j}, and polynomial
\eqn{(x_i x_j + 1)^2}. For \code{bandwidth = "median"}, \eqn{\sigma} is the
upper median of \eqn{\{|x_i - x_j|: i < j\}} divided by \eqn{\sqrt{2}}; if
this is non-finite or non-positive, \eqn{\sigma = 0.001}.

For \code{p_value = TRUE}, the test statistic is the raw HSIC estimate. The null
distribution is generated by permuting one variable within each pair, and the
p-value is \eqn{(1 + \#\{T_b \geq T_{\mathrm{obs}}\})/(B + 1)}. This is an
\eqn{O(B n^2)} pairwise procedure and can be expensive for large matrices or
large \code{B}.

The polynomial kernel currently uses the fixed form
\eqn{(x_i x_j + 1)^2}. More polynomial controls can be added later without
changing the main HSIC object contract.
}
\examples{
set.seed(1)
x <- rnorm(200)
y <- rnorm(200)
H0 <- hsic(cbind(x = x, y = y))
H0

set.seed(2)
x <- rnorm(200)
y <- x^2 + rnorm(200, sd = 0.1)
H1 <- hsic(cbind(x = x, y = y))
H1

set.seed(3)
X <- cbind(a = rnorm(80), b = rnorm(80), c = rnorm(80))
H_perm <- hsic(X, p_value = TRUE, B = 19, seed = 1)
summary(H_perm)
estimate(H_perm)
tidy(H_perm)

}
\references{
Gretton, A., Bousquet, O., Smola, A., & Schoelkopf, B. (2005).
Measuring statistical dependence with Hilbert-Schmidt norms.
\emph{Algorithmic Learning Theory}.

Gretton, A., Fukumizu, K., Teo, C. H., Song, L., Schoelkopf, B., & Smola,
A. J. (2007). A kernel statistical test of independence.
\emph{Advances in Neural Information Processing Systems}.

Gretton, A., Bousquet, O., Smola, A., & Schoelkopf, B. (2005).
Kernel methods for measuring independence.
\emph{Journal of Machine Learning Research}, 6, 2075-2129.

Pfister, N., Buhlmann, P., Scholkopf, B., & Peters, J. (2018).
Kernel-based tests for joint independence.
\emph{Journal of the Royal Statistical Society: Series B}, 80(1), 5-31.
}
\author{
Thiago de Paula Oliveira
}
