% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lisi.R
\name{compute_lisi}
\alias{compute_lisi}
\title{Compute Local Inverse Simpson's Index (LISI)}
\usage{
compute_lisi(
  X,
  meta_data,
  label_colnames,
  perplexity = 30,
  nn_eps = 0,
  use_rann = TRUE,
  nn_method = c("auto", "rann", "fnn", "exact"),
  tol = 1e-05,
  max_iter = 50
)
}
\arguments{
\item{X}{A matrix-like object with cells in rows and embedding/features in columns.}

\item{meta_data}{A data frame with one row per cell.}

\item{label_colnames}{Character vector of column names in \code{meta_data} to evaluate.}

\item{perplexity}{Effective neighborhood size. Defaults to \code{30}.}

\item{nn_eps}{Approximation factor passed to \link[RANN:nn2]{RANN::nn2} when \code{RANN} is available and \code{use_rann = TRUE}.
Defaults to \code{0}.}

\item{use_rann}{Whether to prefer \link[RANN:nn2]{RANN::nn2} over \code{FNN::get.knn} when \code{nn_method = "auto"} decides not to use the package's built-in exact C++ backend.
Defaults to \code{TRUE}.}

\item{nn_method}{Nearest-neighbor backend. Defaults to \code{"auto"},
which prefers the package's exact C++ search only for very small problems.
Larger inputs fall back to \code{RANN}, then \code{FNN}, and only use the exact backend as a last resort.}

\item{tol}{Tolerance used in the binary search for the target perplexity.
Defaults to \code{1e-5}.}

\item{max_iter}{Maximum number of binary-search iterations.
Defaults to \code{50}.}
}
\value{
A data frame with one row per cell and one column per label.
}
\description{
Compute per-cell Local Inverse Simpson's Index (LISI) scores for one or more categorical variables.
This is a clean-room reimplementation of the \code{immunogenomics/LISI}.
}
\examples{
set.seed(1)
X <- rbind(
  matrix(stats::rnorm(100, mean = -2), ncol = 5),
  matrix(stats::rnorm(100, mean = 2), ncol = 5)
)
meta_data <- data.frame(
  batch = rep(c("A", "B"), each = 20),
  group = sample(c("g1", "g2"), 40, replace = TRUE)
)

res <- compute_lisi(
  X, meta_data,
  c("batch", "group"),
  perplexity = 10
)
head(res)
boxplot(res)
}
\references{
Korsunsky I, Millard N, Fan J, et al. Fast, sensitive and accurate
integration of single-cell data with Harmony. \emph{Nature Methods} (2019).
\url{https://www.nature.com/articles/s41592-019-0619-0}

LISI reference implementation:
\url{https://github.com/immunogenomics/LISI}
}
