# Bioactivity Score Aggregation

> Use when when you have both (1) a molecular network graph from GNPS with aligned MS/MS features (nodes and edges) and (2) a bioassay-guided fractionation activity matrix (fractions × bioactivity measurements), and you need to determine which molecular features are responsible for observed.

- Skill: `holobiomicslab/bioactivity-score-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/bioactivity-score-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/bioactivity-score-aggregation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/bioactivity-score-aggregation

---


# bioactivity-score-aggregation

## Summary

Compute per-feature bioactivity scores by aggregating bioassay measurements across fractions and mapping them to molecular network nodes. This skill integrates LC-MS/MS feature detection with bioassay-guided fractionation data to annotate molecular networks with quantitative bioactivity potentials.

## When to use

When you have both (1) a molecular network graph from GNPS with aligned MS/MS features (nodes and edges) and (2) a bioassay-guided fractionation activity matrix (fractions × bioactivity measurements), and you need to determine which molecular features are responsible for observed bioactivity to prioritize downstream compound isolation and structural elucidation.

## When NOT to use

- Input is already a feature quantification table without network topology — use this skill to enrich existing networks, not to create them from raw LC-MS data.
- Bioassay data lacks clear fraction-to-sample mapping or has inconsistent retention time / m/z coordinates — alignment will fail or produce spurious matches.
- Goal is structure elucidation or spectral library matching only, without bioactivity prioritization — use MS/MS spectral networking tools (GNPS) directly instead.

## Inputs

- GNPS molecular network graph (node table with feature identifiers, retention time, m/z; edge table with network connections)
- bioassay-guided fractionation activity matrix (rows=fractions, columns=bioactivity measurements; may include replicates or multiple assay endpoints)
- feature quantification table with RT and m/z for each detected feature (e.g., from MZmine2 or Optimus)

## Outputs

- Annotated molecular network with bioactivity scores as node attributes (GraphML, JSON, or CSV format)
- Summary table mapping each feature to its aggregated bioactivity score and associated metadata (RT, m/z, number of active fractions)

## How to apply

Load the GNPS molecular network structure (edges, node identifiers, retention time and m/z for each feature) and the bioassay activity matrix into Python. Match fractionation samples to molecular network features using retention time (RT) and mass-to-charge ratio (m/z) as unique identifiers, typically within a defined tolerance window. For each feature, aggregate bioactivity measurements across all fractions in which that feature was detected, using a summary statistic (sum, mean, or max of activity values). Annotate the molecular network graph with the computed bioactivity score as a node attribute. Export the annotated network in a machine-readable format (GraphML, JSON, or tabular format) compatible with Cytoscape or downstream visualization and filtering tools.

## Related tools

- **GNPS** (Host platform for MS/MS molecular networking; provides the molecular network graph structure (edges, nodes, feature identifiers) that serves as the scaffold for bioactivity annotation.) — http://gnps.ucsd.edu
- **MZmine2** (LC-MS/MS feature detection and alignment; produces the feature quantification table with RT, m/z, and intensities across all fractions, which is used for feature-to-fraction mapping.) — http://mzmine.github.io/
- **Optimus** (Alternative LC-MS/MS feature detection and alignment workflow using OpenMS; produces feature quantification matrix compatible with bioactivity aggregation.) — https://github.com/MolecularCartography/Optimus
- **Jupyter notebook** (Execution environment for the bioactivity score aggregation workflow; provides reproducible, documented integration of data loading, RT/m/z matching, aggregation, and export.) — https://github.com/DorresteinLaboratory/Bioactive_Molecular_Networks
- **Cytoscape** (Network visualization and interactive exploration tool; receives the annotated molecular network (GraphML or JSON) for visual assessment of bioactivity distribution and community structure.) — http://www.cytoscape.org/

## Evaluation signals

- Feature-to-fraction mapping completeness: verify that ≥80% of features with bioactivity signal are matched to network nodes (check for RT/m/z alignment artifacts or coordinate mismatches).
- Bioactivity score distribution: inspect the aggregated scores for expected range (e.g., non-negative for sum/mean, maximum ≤ max(raw assay values)); flag negative or missing values as alignment failures.
- Network annotation schema validation: confirm that every node in the exported network carries a bioactivity score attribute (no null values for detected features) and that the GraphML/JSON is parseable by Cytoscape.
- Reproducibility audit: re-run the Jupyter notebook on the same inputs and verify that bioactivity scores are identical (deterministic aggregation); compare against manually computed scores for a subset of features.
- Downstream enrichment: validate that high-bioactivity features co-occur in network clusters or match known bioactive compound signatures (if reference data available), and that the ranking is consistent with biological/chemical expectations.

## Limitations

- RT and m/z matching is sensitive to instrumental calibration drift and alignment errors; features detected in only one fraction may be assigned spurious bioactivity if background noise is high.
- Aggregation strategy (sum, mean, max) can bias results: sum favors features in many fractions (high noise), mean may downweight rare bioactive metabolites, max ignores dose–response dynamics; choice must be justified per bioassay context.
- Bioassay data structure assumed: the notebook requires a consistent fraction labeling and column naming scheme; non-standard formats (e.g., nested replicates, multi-plate layouts) require manual preprocessing.
- No statistical significance testing: bioactivity scores are descriptive aggregates; no p-values or confidence intervals are computed, so thresholds for 'active' vs. 'inactive' features must be set post-hoc or externally.
- MS/MS validation not included: MS/MS spectral library matching and structure confirmation are required separately (via GNPS or Sirius); bioactivity alone does not annotate chemical identity.

## Evidence

- [intro] The workflow integrates MS/MS molecular networking and bioassay-guided fractionation into the concept of bioactive molecular networking.: "integrates MS/MS molecular networking and bioassay-guided fractionation into the concept of bioactive molecular networking"
- [other] Map fractionation samples to molecular network features using retention time and mass-to-charge ratio matching.: "Map fractionation samples to molecular network features using retention time and mass-to-charge ratio matching"
- [other] Aggregate bioactivity measurements across fractions for each feature, computing a per-feature bioactivity score (e.g., sum, mean, or max of activity values in fractions containing that feature).: "Aggregate bioactivity measurements across fractions for each feature, computing a per-feature bioactivity score (e.g., sum, mean, or max of activity values in fractions containing that feature)"
- [other] Annotate the molecular network with bioactivity scores as node attributes.: "Annotate the molecular network with bioactivity scores as node attributes"
- [other] Export the integrated network with bioactivity annotations in a format compatible with Cytoscape or network visualization tools (e.g., GraphML or JSON).: "Export the integrated network with bioactivity annotations in a format compatible with Cytoscape or network visualization tools (e.g., GraphML or JSON)"
- [readme] a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS: "a feature quantification table (features_quantification_matrix.csv) that contains the aligned list of features and their intensity accross the fractions analyzed by LC-MS/MS"
- [readme] The code is released as a Jupyter notebook for easiness and reproducibility.: "The code is released as a Jupyter notebook for easiness and reproducibility"