Calculate Community Enrichment (CE) from qSIP object(s)
Arguments
- qsip_data_object
A single qSIP object or list of qSIP objects
- confidence
Confidence level for EAF intervals (default 0.95)
- isotope_label
Which samples to calculate CE for: "labeled", "unlabeled", or "both" (default "labeled")
- enrichment_threshold
Threshold for determining which features are enriched (default "positive_eaf"):
"positive_eaf"(recommended): Enrichment threshold at EAF ≥ 0. All features included, but negative EAF values are set to 0. This is the most defensible approach as it uses all available data while respecting the biological constraint that features cannot be depleted below natural abundance. Negative EAF values represent measurement noise and should not reduce community enrichment."significant": Enrichment threshold at lower CI > 0. Most conservative approach that only counts features with statistically significant positive enrichment. May underestimate community enrichment by excluding features with real but uncertain low enrichment."all": No enrichment threshold. All features with raw observed_EAF values, including negatives. Matches the original per-capita calculation but allows biologically impossible negative enrichment to reduce CE estimates. Useful for backwards compatibility but not recommended for new analyses.
- by
Aggregation level for CE calculation (default "source"):
"source": Calculate CE at the sample level (one value per source_mat_id). This is the whole-community enrichment for each sample."feature": Calculate CE at the feature level (one value per feature per source_mat_id). Useful for comparing individual ASV/OTU enrichment across samples.Taxonomy column name (e.g.,
"phylum","class"): Calculate CE at the specified taxonomic level. Column name must exist in the feature_data@taxonomy slot of the qSIP objects. Useful for comparing enrichment across taxonomic groups (e.g., "Deltaproteobacteria vs Gammaproteobacteria").
Value
Data frame with CE calculations containing:
group: Group identifier from qSIP objectsource_mat_id: Sample identifierby: Aggregation level value (source_mat_id, feature_id, or taxonomy value)n_features_total: Total number of features in this aggregation groupn_features_ce: Number of features with EAF > 0 actually contributing to CEproportion_total: Sum of tube_rel_abundance for all features in this group (relative to whole community)proportion_ce: Sum of tube_rel_abundance for features with EAF > 0 in this groupce: Community enrichment - proportion of whole community biomass that is labeled in this groupce_norm: Normalized community enrichment - CE renormalized using source-level proportion_total (0 to 1). Always calculated as ce / source_proportion_total, even when aggregating by feature or taxonomy.label_type: "labeled" or "unlabeled"isotope: Isotope used (e.g., "18O", "13C")isotopolog: Isotopolog used (e.g., "water", "glucose")messages: List of warning/info messages from calculation
Details
Understanding CE vs CE_norm:
ce (Community Enrichment) represents the proportion of the entire original community (including
features removed by upstream quality filters) that has labeled biomass. When proportion_total < 1.0 (e.g., 0.8
means 20% of community abundance was removed by upstream quality filters), CE is relative to the original 100%.
CE values range from 0 to proportion_total.
ce_norm (Normalized Community Enrichment) represents the same enrichment as CE but renormalized to
treat the tested features only as 100% of the community. ce_norm = ce / proportion_total. ce_norm values
range from 0 to 1.
When no upstream quality filtering occurs (proportion_total = 1.0), CE and CE_norm are identical. When upstream filtering occurs, ce_norm > ce because ce_norm excludes those filtered features from the denominator.
Example: If CE = 0.048 and proportion_total = 0.8:
CE interpretation: "4.8% of the whole community (including the 20% removed by upstream quality filters) has labeled biomass"
CE_norm = 0.048 / 0.8 = 0.06: "6% of the tested features (80% of community) have labeled biomass on average"
Important assumption: CE and CE_norm calculations weight features by their relative sequence abundance (tube_rel_abundance), which assumes equal biomass per sequence read. In reality, features may differ in: (1) cell/organism size and biomass, (2) marker gene copy number (e.g., 16S rRNA gene copies per genome can range 1-15+), and (3) DNA extraction efficiency. These factors cause relative abundance to diverge from relative biomass, meaning two features with equal abundance may contribute different amounts of labeled biomass. This is an inherent limitation of amplicon-based qSIP that cannot be computationally corrected. CE and CE_norm should be interpreted as abundance-weighted metrics, not true biomass-weighted metrics.
Aggregation with the by parameter:
When by = "source" (default), one row is returned per sample with whole-community CE values.
When by = "feature" or a taxonomy level, multiple rows are returned per sample. Within a sample,
the CE values across all aggregation groups sum to the whole-community CE. For example, if whole-community
CE = 0.048, then the sum of CE across all phyla in that sample will equal 0.048. The ce_norm values
are always calculated using the source-level proportion_total, maintaining comparability across aggregation
levels.
Deriving additional metrics from feature/taxonomy-level output:
At the feature or taxonomy level, all proportions are relative to the whole community:
ce: Proportion of whole community that is labeled feature/taxonproportion_total: Proportion of whole community that is this feature/taxon (labeled + unlabeled)proportion_total - ce: Proportion of whole community that is unlabeled feature/taxon
To calculate feature/taxon-relative metrics:
EAF (fraction of feature/taxon that is labeled):
ce / proportion_totalUnlabeled fraction of feature/taxon:
(proportion_total - ce) / proportion_totalor equivalently1 - EAF
