linf.cells: Dominant-feature assignment

In linf: L-Infinity Normalization and Dominant Community State Types

Dominant-feature assignment

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 max.col(..., ties.method = "first")). Rows that are all zero are assigned NA.

Feature IDs default to colnames(S); if absent, synthetic IDs "V1", "V2", ..., "Vp" are generated. Display labels default to the feature IDs unless feature.labels is supplied. To guarantee a 1-1 mapping between columns and both IDs and labels, duplicates are disambiguated via make.unique().

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

S	Numeric matrix (samples x features), typically L-infinity-normalized.
feature.ids	Optional character vector of stable feature identifiers, length ncol(S).
feature.labels	Optional character vector of display labels, length ncol(S).
tie.method	Character. How to resolve ties during dominant-feature assignment.
return.value	Logical. If TRUE, include a value vector with row maxima.
backend	Character. Matrix backend to use: "auto", "dense", or "sparse". The default "auto" preserves sparse input and otherwise uses the dense path.

Value

A list with components:

• index: integer index of the dominant column per sample (NA for all-zero rows)

• id: dominant feature ID per sample (NA for all-zero rows)

• label: dominant column label per sample (NA for all-zero rows)

• id.levels: full feature ID set after make.unique(..., sep = "_")

• levels: full column label set after make.unique(..., sep = "_")

• observed.id.levels: subset of id.levels that appear in id

• observed.levels: subset of levels that appear in label

• value: row maxima (only when return.value = TRUE)

See Also

normalize.linf, linf.csts

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

linf documentation built on Aug. 5, 2026, 9:08 a.m.