% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_sample_subgraph.R
\name{get_sample_subgraph}
\alias{get_sample_subgraph}
\title{Extract sample-level subgraphs from a graph object}
\usage{
get_sample_subgraph(
  graph_obj,
  mat,
  min_abundance = 0,
  select_sample = NULL,
  combine = c("union", "intersect")
)
}
\arguments{
\item{graph_obj}{A \code{tbl_graph} object from
\code{\link{build_graph_from_mat}} or \code{\link{build_graph_from_df}}.
Its node table must contain a \code{name} column matching
\code{rownames(mat)}.}

\item{mat}{Numeric matrix. Rows are OTUs / features (must have rownames
matching graph node names); columns are samples (must have colnames as
sample IDs).}

\item{min_abundance}{Numeric (default = 0). An OTU is considered present in
a sample when \code{mat[OTU, sample] > min_abundance}. The appropriate
value depends on the scale of \code{mat}: e.g. \code{0} for raw or
rarefied counts, \code{0.001} for relative abundance. The function does
not infer data type; the user is responsible for choosing a meaningful
threshold for their data.}

\item{select_sample}{Character vector (default = \code{NULL}). Sample IDs
to extract into a single merged subgraph. Must be a subset of
\code{colnames(mat)}. When \code{NULL}, only per-sample subgraphs are
returned and \code{sub_graph_select} is \code{NULL}.}

\item{combine}{Character. One of \code{"union"} (default) or
\code{"intersect"}. Controls how OTUs from the selected samples are
combined when building \code{sub_graph_select}:
\itemize{
  \item \code{"union"}: keep OTUs present in any of the selected samples.
  \item \code{"intersect"}: keep only OTUs present in all of the
    selected samples.
}
Edges are always the induced edges from \code{graph_obj} between the
surviving nodes.}
}
\value{
A list with three elements:
\itemize{
  \item \code{sub_graph_all}: named list of per-sample \code{tbl_graph}
    subgraphs. Samples with no present OTUs in the graph are dropped from
    this list (but are still recorded in \code{stat_sample}).
  \item \code{stat_sample}: data frame with columns \code{Sample},
    \code{Node}, \code{Edge}, \code{Status}. One row per sample in
    \code{mat}, including samples with empty subgraphs.
  \item \code{sub_graph_select}: a single merged \code{tbl_graph} of the
    nodes combined from \code{select_sample} according to \code{combine},
    or \code{NULL} if \code{select_sample} is \code{NULL} or the
    combination produces an empty node set. The node table of this graph
    carries two additional columns:
    \itemize{
      \item \code{n_present_samples} (integer): how many of the selected
        samples this node appears in.
      \item \code{present_in_samples} (character): comma-separated sample
        IDs the node appears in, ordered following \code{select_sample}.
    }
}
}
\description{
For each sample (column in \code{mat}), OTUs whose abundance exceeds
\code{min_abundance} are treated as present in that sample. The induced
subgraph of \code{graph_obj} on those OTUs is returned. Optionally,
multiple selected samples can be combined into a single merged subgraph
via union or intersection of their present OTUs.
}
\details{
This function is the sample-wise analogue of \code{\link{get_subgraph}},
which splits a graph by its \code{Modularity} node attribute. Unlike module
membership (which is a partition), an OTU can belong to multiple samples,
so a \code{combine} switch is exposed.
}
\examples{
\donttest{
data("otu_rare_relative")
data("tax_tab")
obj <- build_graph_from_mat(
  mat              = otu_rare_relative,
  transfrom.method = "none",
  r.threshold      = 0.7,
  p.threshold      = 0.05,
  method           = "WGCNA",
  cor.method       = "pearson",
  proc             = "bonferroni",
  module.method    = "Fast_greedy",
  node_annotation  = tax_tab,
  top_modules      = 15,
  seed             = 1115
)

# All per-sample subgraphs + per-sample stats
res <- get_sample_subgraph(graph_obj = obj, mat = otu_rare_relative)
head(res$stat_sample)

# Merged subgraph for 3 samples, union of present OTUs
res_u <- get_sample_subgraph(
  graph_obj     = obj,
  mat           = otu_rare_relative,
  select_sample = colnames(otu_rare_relative)[1:3],
  combine       = "union"
)
res_u$sub_graph_select

# Same selection but intersection (core OTUs across the 3 samples)
res_i <- get_sample_subgraph(
  graph_obj     = obj,
  mat           = otu_rare_relative,
  select_sample = colnames(otu_rare_relative)[1:3],
  combine       = "intersect"
)
res_i$sub_graph_select
}
}
