% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dcst_landmark_pipeline.R
\name{linf.dcst.landmark.pipeline}
\alias{linf.dcst.landmark.pipeline}
\title{Landmark-aware dCST pipeline}
\usage{
linf.dcst.landmark.pipeline(
  X,
  feature.ids = NULL,
  feature.labels = NULL,
  n0.depth1 = 50,
  n0.depth2 = 25,
  refinement.factor = 2,
  sep = "__",
  low.freq.policy = c("pure", "absorb"),
  rare.label = "RARE_DOMINANT",
  depth1.landmark.types = c("endpoint.max", "endpoint.min", "mean.rep", "median.rep"),
  depth2.landmark.types = c("endpoint.max", "endpoint.min", "mean.rep", "median.rep"),
  landmark.view = c("absorb", "active", "rare"),
  tie.method = c("first", "random", "error"),
  verbose = FALSE,
  backend = c("auto", "dense", "sparse")
)
}
\arguments{
\item{X}{Numeric matrix (samples x features). Must be finite and nonnegative.}

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

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

\item{n0.depth1}{Integer >= 1. Minimum support for a depth-1 dominance
sample set.}

\item{n0.depth2}{Integer >= 1. Minimum support for a depth-2 child lineage.}

\item{refinement.factor}{Numeric > 0. Auto-refinement threshold multiplier
passed to \code{\link{refine.linf.csts}}.}

\item{sep}{Character scalar used to join depth-refined dCST path tokens.}

\item{low.freq.policy}{Character. One of \code{"pure"} or \code{"absorb"}.
Controls the active dCST view while still preserving parallel rare/absorb
views inside the returned dCST objects. The legacy value \code{"rare"} is
still accepted as a deprecated alias for \code{"pure"}.}

\item{rare.label}{Character scalar for rare buckets.}

\item{depth1.landmark.types}{Character vector of landmark types for depth 1.}

\item{depth2.landmark.types}{Character vector of landmark types for depth 2.}

\item{landmark.view}{Character. One of \code{"absorb"}, \code{"active"}, or
\code{"rare"}. Defaults to \code{"absorb"} because landmark reporting is
typically requested on the absorb view.}

\item{tie.method}{Character. Tie handling passed through to
\code{\link{linf.csts}} and \code{\link{linf.landmarks}}.}

\item{verbose}{Logical. Passed to \code{\link{refine.linf.csts}}.}

\item{backend}{Character. Matrix backend to use: \code{"auto"},
\code{"dense"}, or \code{"sparse"}.}
}
\value{
A named list with components:
\itemize{
\item \code{linf.rel}: L-infinity-normalized matrix.
\item \code{dcst.depth1}: depth-1 \code{"linf.csts"} object.
\item \code{dcst.depth2}: depth-2 \code{"linf.csts"} object.
\item \code{landmarks.depth1}: \code{"linf.landmarks"} object at depth 1.
\item \code{landmarks.depth2}: \code{"linf.landmarks"} object at depth 2.
\item \code{params}: compact record of the pipeline arguments used.
}
}
\description{
Small wrapper that normalizes a nonnegative matrix with
\code{\link{normalize.linf}}, computes depth-1 dCSTs with
\code{\link{linf.csts}}, refines once to depth 2 with
\code{\link{refine.linf.csts}}, and then computes landmark points for both
depths with \code{\link{linf.landmarks}}.

The function is intentionally explicit rather than highly abstracted. It
keeps the intermediate objects visible and returns them together in one list
so downstream workflows can inspect the normalized matrix, the depth-1 dCSTs,
the depth-2 dCSTs, and the landmark tables without re-running the pipeline.
}
\examples{
X <- rbind(
  s1 = c(10, 8, 1),
  s2 = c(9, 7, 2),
  s3 = c(8, 2, 7),
  s4 = c(7, 1, 8),
  s5 = c(1, 10, 2),
  s6 = c(2, 9, 1)
)
ids <- c("asv_1", "asv_2", "asv_3")
labels <- c("L. iners 1", "Gard. vaginalis 2", "BVAB1 3")

out <- linf.dcst.landmark.pipeline(
  X,
  feature.ids = ids,
  feature.labels = labels,
  n0.depth1 = 2,
  n0.depth2 = 2,
  refinement.factor = 2,
  low.freq.policy = "pure",
  landmark.view = "absorb",
  verbose = FALSE
)

names(out)
out$dcst.depth2$cst.depth
out$landmarks.depth2$view
}
