Detect metabolites that change not only in abundance, but in how they co-regulate with the rest of the metabolome.
PhenoRewire is a Python command-line tool for phenotype-aware metabolomics network rewiring. It identifies features whose correlation neighbourhood reorganises between biological states, providing a complementary signal to differential abundance and helping reveal coordinated metabolic shifts that standard analyses may miss.
Status: in active development. Intended for research use. Feedback, issues, and pull requests are welcome.
Many metabolomics studies focus on which metabolites go up or down between groups. PhenoRewire asks a different question: did the way metabolites co-vary with each other change?
Given a feature table, sample metadata, and a configuration file, PhenoRewire:
- selects metabolite features statistically associated with a phenotype or time contrast
- builds one Spearman correlation network per biological state
- quantifies rewiring edge by edge — identifying connections gained, lost, or reversed between states
- ranks features by how much their correlation context changed
- exports GraphML networks for Cytoscape and CSV tables for spreadsheet review
PhenoRewire is intended for hypothesis generation. It identifies correlational reorganisation, not causal mechanisms.
A metabolite can show substantial rewiring with no significant change in mean abundance, and vice versa. These two signals are complementary. Rewiring analysis is particularly useful when:
- classical differential abundance yields long lists with no clear priorities
- you suspect coordinated metabolic shifts that are not visible at the individual-feature level
- you want to identify hub metabolites whose co-regulation context changes between groups or timepoints
PhenoRewire is not a replacement for differential abundance. It is a complementary tool for hypothesis generation and candidate prioritisation.
After a standard run, the key outputs are:
| Output | Location | Description |
|---|---|---|
priority_rewired_nodes.csv |
triage/ |
Ranked list of the most rewired metabolites |
rewiring_summary.csv |
triage/ |
Global rewiring counts for the entire comparison |
rewiring_network_phenotype.graphml |
triage/ |
Full rewiring network for Cytoscape (phenotype mode) |
rewiring_network_temporal.graphml |
triage/ |
Full rewiring network for Cytoscape (temporal mode) |
final_report.md |
report/ |
Narrative run summary with scoring formulas and a reproducibility block |
Optional 2D annotation outputs (with --run-2dnetwork):
| Output | Location | Description |
|---|---|---|
annotation_summary.csv |
2dnetwork/ |
One row per prioritised feature with neighbour counts and annotation confidence |
annotation_expansion.csv |
2dnetwork/ |
One row per (feature, neighbour) pair across the molecular network |
annotation_first_neighbours.csv |
2dnetwork/ |
First-hop neighbours only |
For column definitions and interpretation guidance, see docs/interpret_phenotype.md, docs/interpret_temporal.md, and docs/interpret_2d_network.md.
PhenoRewire installs from this repository. It is not yet available on PyPI.
git clone https://github.com/ldellavedova/PhenoRewire
cd PhenoRewire
conda env create -f environment.yml
conda activate phenorewire
pip install -e .
phenorewire --helpenvironment.yml pins Python 3.11. The package metadata supports Python >=3.9.
git clone https://github.com/ldellavedova/PhenoRewire
cd PhenoRewire
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -e .
phenorewire --helpRequired for --plot-networks and the standalone 2D figure script:
pip install "phenorewire[viz]"The repository includes synthetic example data in data/ and ready-to-use configs at the repository root. Output files are written to results/ locally; this directory is gitignored and not committed.
phenorewire --config config_phenotype.yamlOutput directory: results/phenotype_example/
Key outputs:
results/phenotype_example/triage/priority_rewired_nodes.csvresults/phenotype_example/triage/rewiring_network_phenotype.graphmlresults/phenotype_example/report/final_report.md
config_temporal.yaml is a ready-to-use template for temporal (time-course) data. The bundled synthetic data was designed for the phenotype mode and does not contain a meaningful temporal signal, so running this command with the demo data will exit early at the feature selection step. Use config_temporal.yaml as the starting point for your own time-course dataset.
phenorewire --config config_temporal.yamlThe bundled phenotype config also points to a small demo molecular network:
phenorewire --config config_phenotype.yaml --run-2dnetworkExpected outputs in results/phenotype_example/2dnetwork/:
annotation_summary.csvannotation_expansion.csvannotation_first_neighbours.csv
See docs/interpret_2d_network.md and 2d_network/README.md for the standalone publication-figure workflow.
One row per metabolite feature. The column names are configurable; the bundled example uses:
| Column | Example name | Config key |
|---|---|---|
| Feature identifier | feature_id |
FEATURE_ID_COL |
| m/z | mz |
MZ_COL |
| Retention time | rt |
RT_COL |
| Name (optional) | name |
NAME_COL |
| Sample intensities | Sample_001, Sample_002, … |
detected by INTENSITY_REGEX |
One row per sample. The column names are configurable; the bundled example uses:
| Column | Example name | Config key |
|---|---|---|
| Sample identifier | sample_id |
META_SAMPLE_COL |
| Group or phenotype | group_label |
used in GROUP_DEFINITION |
| Timepoint | timepoint |
META_TIME_COL |
Sample identifiers in metadata.csv must match the intensity column names in feature_table.csv, after stripping any prefix or suffix handled by INTENSITY_REGEX.
Use config_phenotype.yaml for phenotype comparisons and config_temporal.yaml for temporal comparisons. Both files are fully annotated templates — copy one, edit the paths and group labels, and run. All available parameters are documented inline in the config files.
The technical parameter reference is in docs/architecture.md.
Full documentation is in docs/:
| Doc | Description |
|---|---|
docs/interpret_phenotype.md |
Output column definitions — phenotype mode |
docs/interpret_temporal.md |
Output column definitions — temporal mode |
docs/interpret_2d_network.md |
Output column definitions — 2D annotation |
docs/architecture.md |
Technical architecture and module overview |
docs/troubleshooting.md |
Common problems and fixes |
docs/tutorials/ |
Step-by-step tutorial notebooks and walkthrough |
| Path | Description |
|---|---|
phenorewire/ |
Installable Python package and CLI entry point |
phenorewire/twodn/ |
2D molecular network annotation and plotting helpers |
docs/ |
User and technical documentation |
docs/tutorials/ |
Tutorial notebooks and output walkthrough |
data/ |
Bundled synthetic example inputs |
2d_network/ |
Standalone two-layer figure workflow |
dev/tests/ |
Unit and integration test suite |
dev/benchmarks/ |
Performance benchmarking and simulation scripts |
config_phenotype.yaml |
Ready-to-run phenotype config template |
config_temporal.yaml |
Ready-to-run temporal config template |
environment.yml |
Conda environment specification |
Note: PhenoRewire has not yet been formally published. If you use this tool in a manuscript, please check this repository for an updated citation. In the meantime, please cite the repository URL and version (v0.1.0).
MIT License — free to use, modify, and distribute with attribution.
Contributions are welcome. To report a bug or request a feature, open an issue on GitHub. See CONTRIBUTING.md for code contribution guidelines.
For questions or feedback, open an issue on GitHub or contact the maintainer at l.dellavedova@uu.nl.