Skip to contents

Count Feature Carriers Within a Basin in a gfc.flow Object

Source: R/gfc_flow.R
basin.feature.carriers.Rd

Given a gfc.flow object, a basin identifier, and a samples-by-features matrix X, compute for each feature (column of X) the number k and proportion p of basin vertices for which X[vertex, feature] > eps.

The basin identifier basin.id may be an extremum label (e.g., "M1", "m3", "sM2", "sm7") or a numeric vertex index (1-based) corresponding to an extremum present in gfc.flow$summary.all / gfc.flow$summary. When numeric, type can be used to disambiguate.

Usage

# S3 method for class 'feature.carriers'
basin(
  object,
  basin.id,
  X,
  eps = 0,
  type = c("auto", "min", "max"),
  match.by = c("index", "rownames"),
  drop.missing = TRUE,
  include.extremum = TRUE,
  unique = TRUE,
  sort = TRUE,
  gfc.flow = object,
  ...
)

Arguments

object

A gfc.flow object from compute.gfc.flow.

basin.id

Basin identifier: a single character label or a single numeric vertex index (1-based).

X

A numeric matrix (or data.frame coercible to a numeric matrix) with samples/vertices in rows and features in columns. If basin.id resolves to numeric vertex indices, row names are not required. If you prefer to match by sample IDs, ensure rownames(X) are present and pass match.by="rownames".

eps

A non-negative numeric threshold. A feature is considered present in a vertex if X > eps. Default is 0.

type

Character string. Only used when basin.id is numeric. One of "auto" (default), "min", or "max".

match.by

Character string controlling how basin vertices are mapped to rows of X. One of:

  • "index" (default): treat basin vertices as 1-based row indices into X

  • "rownames": treat basin vertices as row names of X (requires rownames)

drop.missing

Logical; only relevant for match.by="rownames". If TRUE (default), silently drop basin vertices not found in rownames(X). If FALSE, error if any are missing.

include.extremum

Logical; if TRUE (default), ensure the extremum vertex is included in the basin vertex set (defensive).

unique

Logical; if TRUE (default), unique the resolved vertex set.

sort

Logical; if TRUE (default), sort the resolved vertex set.

gfc.flow

Backward-compatible alias for object.

...

Additional arguments (currently ignored).

Value

A data.frame with columns:

  • k: integer counts of basin vertices with X > eps

  • p: numeric proportions k / n.vertices

Row names correspond to colnames(X).

Examples

if (FALSE) { # \dontrun{
## By basin label
res.M1 <- basin.feature.carriers(gfc.flow.res, "M1", X.rel, eps = 0)

## By extremum vertex index
res.v <- basin.feature.carriers(gfc.flow.res, 1147, X.rel, eps = 1e-6, type = "max")
} # }