% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypercube_embedding.R
\name{linf.hypercube.embedding}
\alias{linf.hypercube.embedding}
\title{Extended homogeneous-coordinate hypercube embedding}
\usage{
linf.hypercube.embedding(
  X,
  reference,
  lambda = NULL,
  sigma.quantile = 0.95,
  sigma.target = 0.95,
  feature.ids = NULL,
  feature.labels = NULL,
  tol = 0,
  backend = c("auto", "dense", "sparse")
)
}
\arguments{
\item{X}{Nonnegative numeric matrix with samples in rows and features in
columns.}

\item{reference}{Reference component. May be a column index, feature ID, or
feature label.}

\item{lambda}{Positive numeric scalar. If \code{NULL}, choose a data-scaled value
using \code{sigma.quantile} and \code{sigma.target}.}

\item{sigma.quantile}{Quantile of positive finite-reference \eqn{\|z\|_1}
values used when \code{lambda = NULL}.}

\item{sigma.target}{Target value of \eqn{\sigma_\lambda(t)} at the selected
quantile when \code{lambda = NULL}.}

\item{feature.ids}{Optional stable feature identifiers, length \code{ncol(X)}.}

\item{feature.labels}{Optional display labels, length \code{ncol(X)}.}

\item{tol}{Nonnegative tolerance. Reference entries \verb{<= tol} are treated as
zero, and L-infinity norms \verb{<= tol} are treated as zero.}

\item{backend}{Matrix backend: \code{"auto"}, \code{"dense"}, or \code{"sparse"}. Sparse
inputs are accepted, but the returned embedding is a dense matrix because
homogeneous-coordinate embeddings are generally dense.}
}
\value{
A numeric matrix with \code{nrow(X)} rows and \code{ncol(X) - 1} columns. The
columns correspond to the non-reference components. Attributes record the
reference component, lambda choice, and finite/boundary row counts.
}
\description{
Computes the zero-aware hypercube embedding associated with one reference
component of a nonnegative compositional matrix. For rows with positive
reference component, the function forms the ordinary homogeneous ratios
against that reference and radially maps them into the unit cube. For rows
whose reference component is zero, it uses the L-infinity boundary extension
so that the embedding remains defined.
}
\details{
Let \eqn{x = (x_1,\ldots,x_p)} be a nonnegative row and let \eqn{k} be the
reference component. When \eqn{x_k > 0}, define
\eqn{z = x_{-k}/x_k}. The embedded row is
\deqn{
  \sigma_\lambda(\|z\|_1)\frac{z}{\|z\|_\infty},
  \qquad
  \sigma_\lambda(t) = 1 - \exp(-\lambda t).
}
When \eqn{x_k = 0}, the embedded row is the L-infinity-normalized boundary
vector
\deqn{
  x_{-k}/\|x_{-k}\|_\infty.
}
All-zero rows are mapped to all-zero embedded rows by convention.

If \code{lambda} is not supplied, it is chosen from the positive finite-reference
rows so that \code{sigma.target} is attained at the \code{sigma.quantile} quantile of
\eqn{\|z\|_1}. This is a numerical scaling convention for finite datasets; it
does not change the reference component or the boundary extension rule.
}
\examples{
X <- rbind(
  c(A = 2, B = 1, C = 1),
  c(A = 0, B = 2, C = 1)
)
linf.hypercube.embedding(X, reference = "A", lambda = log(2))

}
