% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/transfer_dcsts.R
\name{transfer.dcsts}
\alias{transfer.dcsts}
\title{Transfer samples into a frozen dCST hierarchy}
\usage{
transfer.dcsts(
  X,
  csts,
  depth = NULL,
  view = c("absorb", "active", "rare"),
  match.by = c("feature.ids", "feature.labels"),
  feature.ids = NULL,
  feature.labels = NULL,
  tie.method = c("support", "first", "random", "error"),
  carry.forward.terminal.depths = TRUE,
  sep = NULL,
  backend = c("auto", "dense", "sparse")
)
}
\arguments{
\item{X}{Nonnegative sample-by-feature matrix to transfer. Columns may be in
any order and may include features not present in \code{csts}; missing
retained features are treated as zero.}

\item{csts}{A fitted \code{"linf.csts"} object produced by
\code{\link{linf.csts}} and optionally refined by
\code{\link{refine.linf.csts}} or \code{\link{refine.linf.csts.iter}}.}

\item{depth}{Integer vector of requested depths. Defaults to all fitted
depths in \code{csts}.}

\item{view}{Which fitted hierarchy view to transfer into. \code{"absorb"}
uses \code{cst.levels.absorb}; \code{"rare"} uses
\code{cst.levels.rare}; \code{"active"} uses \code{cst.levels}.}

\item{match.by}{Whether columns in \code{X} are aligned to
\code{csts$feature.ids} or \code{csts$feature.labels}.}

\item{feature.ids}{Optional feature identifiers for columns of \code{X}.
Defaults to \code{colnames(X)}.}

\item{feature.labels}{Optional feature labels for columns of \code{X}.
Defaults to \code{feature.ids}.}

\item{tie.method}{How to resolve ties among frozen child lineages with equal
sample abundance. \code{"support"} chooses the tied lineage with largest
reference support and then lexical order; \code{"first"} uses frozen child
order; \code{"random"} samples one tied lineage; \code{"error"} stops.}

\item{carry.forward.terminal.depths}{Logical. If \code{TRUE}, an unmatched
depth-1 sample may fall back to its dominant retained feature. Terminal
lineages at later depths are assigned only when they appear as realized
stable lineage sets in the fitted hierarchy.}

\item{sep}{Separator used in lineage labels. Defaults to \code{csts$sep} or
\code{"__"}.}

\item{backend}{Matrix backend; passed to the internal matrix preparer.}
}
\value{
A list of class \code{"linf.dcst.transfer"} with components:
\itemize{
\item \code{assignment}: character matrix of transferred labels for the
requested depths.
\item \code{all.depths}: character matrix for all fitted depths.
\item \code{depth}: requested depth vector.
\item \code{view}, \code{match.by}, \code{tie.method}: settings used.
}
}
\description{
Assigns rows of a new sample-by-feature matrix into the realized lineage sets
of a fitted \code{"linf.csts"} hierarchy. The hierarchy is not refit: each
sample is walked through the frozen tree by choosing, at each depth, the
realized child lineage whose newly added feature has the largest abundance in
that sample.
}
\examples{
X <- rbind(
  s1 = c(A = 10, B = 2, C = 1),
  s2 = c(A = 9, B = 3, C = 1),
  s3 = c(A = 1, B = 10, C = 2),
  s4 = c(A = 1, B = 9, C = 3)
)
M <- normalize.linf(X)
fit <- linf.csts(M, n0 = 2, low.freq.policy = "absorb")
transfer.dcsts(X, fit)$assignment

}
