% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linf.R
\name{linf.cells}
\alias{linf.cells}
\title{Dominant-feature assignment}
\usage{
linf.cells(
  S,
  feature.ids = NULL,
  feature.labels = NULL,
  tie.method = c("first", "random", "error"),
  return.value = FALSE,
  backend = c("auto", "dense", "sparse")
)
}
\arguments{
\item{S}{Numeric matrix (samples x features), typically L-infinity-normalized.}

\item{feature.ids}{Optional character vector of stable feature identifiers,
length \code{ncol(S)}.}

\item{feature.labels}{Optional character vector of display labels, length
\code{ncol(S)}.}

\item{tie.method}{Character. How to resolve ties during dominant-feature
assignment.}

\item{return.value}{Logical. If \code{TRUE}, include a \code{value} vector with row maxima.}

\item{backend}{Character. Matrix backend to use: \code{"auto"},
\code{"dense"}, or \code{"sparse"}. The default \code{"auto"} preserves
sparse input and otherwise uses the dense path.}
}
\value{
A list with components:
\itemize{
\item \code{index}: integer index of the dominant column per sample (\code{NA} for all-zero rows)
\item \code{id}: dominant feature ID per sample (\code{NA} for all-zero rows)
\item \code{label}: dominant column label per sample (\code{NA} for all-zero rows)
\item \code{id.levels}: full feature ID set after \code{make.unique(..., sep = "_")}
\item \code{levels}: full column label set after \code{make.unique(..., sep = "_")}
\item \code{observed.id.levels}: subset of \code{id.levels} that appear in \code{id}
\item \code{observed.levels}: subset of \code{levels} that appear in \code{label}
\item \code{value}: row maxima (only when \code{return.value = TRUE})
}
}
\description{
Assigns each row to the column achieving its maximum.

For each sample (row) of a nonnegative matrix, identifies the dominant
feature as the column with the maximum value. Samples with the same dominant
feature form a depth-1 dominance sample set. Ties are broken by the first
maximum (as in \code{max.col(..., ties.method = "first")}). Rows that are
all zero are assigned \code{NA}.

Feature IDs default to \code{colnames(S)}; if absent, synthetic IDs
\code{"V1", "V2", ..., "Vp"} are generated. Display labels default to the
feature IDs unless \code{feature.labels} is supplied. To guarantee a 1-1
mapping between columns and both IDs and labels, duplicates are
disambiguated via \code{make.unique()}.
}
\examples{
# Basic example with named columns
S <- rbind(
  a = c(A = 10, B = 5,  C = 0),   # -> A
  b = c(A = 0,  B = 0,  C = 0),   # -> NA
  c = c(A = 1,  B = 4,  C = 4)    # tie -> first max: B
)
out <- linf.cells(S)
out$index
out$label
out$levels
out$observed.levels

# Unnamed columns (synthetic labels V1..Vp), duplicate names disambiguated
T <- matrix(c(0,2,  3,1,  0,0), nrow = 3, byrow = TRUE)
colnames(T) <- c("X", "X")  # duplicates -> X, X_1
linf.cells(T)$levels

# With L-infinity normalization in a pipeline
M <- normalize.linf(S)
linf.cells(M)$label

}
\seealso{
\code{\link{normalize.linf}}, \code{\link{linf.csts}}
}
