Metadata-Version: 2.4
Name: metaumbra
Version: 1.5.0
Summary: Genome-level presence inference from metaproteomic peptide lists.
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/byemaxx/MetaUmbra
Project-URL: Repository, https://github.com/byemaxx/MetaUmbra
Project-URL: Issues, https://github.com/byemaxx/MetaUmbra/issues
Keywords: metaproteomics,proteomics,bioinformatics,genome inference,peptides
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rpg==2.0.5
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: tqdm
Provides-Extra: gui
Requires-Dist: PySide6; extra == "gui"
Requires-Dist: pyarrow; extra == "gui"
Provides-Extra: gui-pyqt5
Requires-Dist: PyQt5; extra == "gui-pyqt5"
Requires-Dist: pyarrow; extra == "gui-pyqt5"
Provides-Extra: parquet
Requires-Dist: pyarrow; extra == "parquet"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: PySide6; extra == "all"
Requires-Dist: pyarrow; extra == "all"
Dynamic: license-file

# MetaUmbra
[![MetaUmbra](https://raw.githubusercontent.com/byemaxx/MetaUmbra/main/src/metaumbra/assets/baner.png)](https://github.com/byemaxx/MetaUmbra)


## Genome-level presence inference from metaproteomic peptides

MetaUmbra performs genome-level presence inference from metaproteomic peptide lists. It combines sample-depth-aware genome-unique peptide support with weighted shared peptide evidence to identify statistically supported microbial genomes and generate interpretable presence rankings.

## Main features

- Evaluate candidate genome support from metaproteomic peptide tables
- Build genome-specific theoretical peptide references from protein FASTA files
- Support user-defined genome collections, including isolate genomes, strain panels, and MAG catalogs
- Use both unique and shared peptide evidence for genome presence inference
- Calibrate genome-unique peptide counts against sample-specific weak-background genomes by default
- Score multi-sample inputs per sample or user-defined analysis unit without repeated genome digest scans
- Report genome-level p-values, BH-adjusted q-values, and presence scores
- Provide GUI, command-line, and Python workflow support
- Support peptide tables from common metaproteomics workflows such as DIA-NN and MaxQuant

## Workflow overview
[![MetaUmbra workflow](https://raw.githubusercontent.com/byemaxx/MetaUmbra/main/src/metaumbra/assets/workflow.png)](https://github.com/byemaxx/MetaUmbra)


## Installation

MetaUmbra requires Python 3.10 or newer.
Installation is available via pip from [PyPI](https://pypi.org/project/metaumbra/).

```bash
# Install with all features (GUI, parquet support)
pip install metaumbra[all]
```
The default GUI extra uses PySide6. To run the GUI with PyQt5 instead, install `metaumbra[gui-pyqt5]`.

or
```bash
# Install with core features only
pip install metaumbra
```

## Usage

MetaUmbra can be used through either the graphical interface or the command line.

For a detailed walkthrough, including input formats, CLI examples, output interpretation, and troubleshooting, see the [MetaUmbra Usage Guide](docs/usage.md).

### Graphical interface

```bash
metaumbra-gui
```

The GUI supports FASTA digestion, peptide table loading, genome presence scoring, and result export.

### Command line

MetaUmbra provides separate commands for the main workflow steps:

```bash
metaumbra digest --help
metaumbra score --help
metaumbra extract-parquet --help
```

A typical workflow is:

```bash
metaumbra digest ...
metaumbra score ...
```

Use `metaumbra extract-parquet ...` to convert DIA-NN parquet reports to peptide TSV files before scoring.

## Input

MetaUmbra requires:

- Protein FASTA files, with one FASTA file per genome
- An observed peptide table containing peptide sequences

Optional inputs include peptide scores, peptide-level error values, decoy flags, and genome lineage annotations.

All scoring uses one analysis-unit workflow. Select `--unit-mode all-samples`, `per-sample`, or `metadata`; each option builds a sample-to-unit assignment and invokes the same per-unit p/q-value engine. The cohort-wide `all-samples` mode uses a moderately more permissive empirical-background calibration profile, recorded in the run summary, so pooled strong signals do not inflate their own null background.

The default unique-evidence mode is `auto`. Before observed genome significance is evaluated, it partitions candidates by theoretical peptide opportunity and checks whether at least 90% have at least 100 comparable background genomes and at least five expected observations above the configured background quantile. If structurally eligible, it uses `empirical-background`; otherwise the entire panel uses `alpha-upper-bound`. Model selection never uses pilot p-values, pilot q-values, benchmark labels, recovery, or additional-call counts. The decision variables and reason are recorded in `artifacts/diagnostics/unit_empirical_background_calibration.tsv`.

Peptide matching uses `--peptide-normalization-policy il-equivalent` by default. Isoleucine and leucine are both mapped to `J` before observed/theoretical deduplication, matching, degeneracy counting, and unique/shared classification. Use `exact` for a residue-exact sensitivity analysis. Q/K and AD/W are not collapsed. Matched-peptide and theoretical-opportunity caches record the normalization policy and reject incompatible or legacy cache schemas.

## Output

The requested `--output` is a unified results directory.

Default output files:

- `unit_genome_results.tsv`: one row per `analysis_unit_id` x `genome_id`, including q-values and threshold flags.
- `cohort_genome_summary.tsv`: recurrence across analysis units.
- `sample_unit_mapping.tsv`: the validated sample assignment.
- `genome_selection_manifest.json`: the only downstream genome-selection interface.
- `artifacts/`: run metadata, logs, caches, and optional diagnostics.

`genome_selection_manifest.json` uses `metaumbra.genome_selection_manifest.v1` and maps every unit to `sample_ids`, q<=0.05 genomes, and the stricter q<=0.01 subset. Detailed scores stay in `unit_genome_results.tsv`.

Each scoring run records `artifacts/run_parameters.json`, `run.log`, `run_status.json`, and `run_summary.json`. Use `--export-diagnostics` for heavier audit tables under `artifacts/diagnostics/`.

In the current implementation, peptide presence within an analysis unit is defined as the union of sample-level peptide presence across samples assigned to that unit. Only genomes with at least one matched observed peptide enter that unit's BH family. Active genomes with no unique peptide remain in this family but receive `pvalue_simes_closed = pvalue = 1`; shared evidence can corroborate unique evidence but cannot establish presence alone. For other active genomes, the default Simes/closed-testing p-value is `max(pvalue_unique, min(1, 2*min(pvalue_unique, pvalue_shared), max(pvalue_unique, pvalue_shared)))`. BH is then applied separately within each analysis unit. Bonferroni, calibrated/raw HMP, Fisher, and unique-only remain selectable sensitivity analyses.

Key output columns include:

| Column | Description |
| --- | --- |
| `genome_id` | Candidate genome identifier |
| `num_peptides_matched` | Number of observed peptides matched to the genome |
| `num_peptides_unique` | Number of matched peptides unique to the genome |
| `theoretical_unique_peptides` | Theoretical peptides unique to this genome among the analyzed genome set, included for `hypergeometric-opportunity` output |
| `expected_unique_null` | Expected observed genome-unique peptides under the selected unique-evidence null |
| `unique_depth_fold` | Observed unique peptides divided by expected unique peptides under the null |
| `has_unique_evidence` | Whether the genome has at least one observed unique peptide |
| `pvalue_shared` | Shared-peptide knockoff p-value |
| `pvalue_unique` | Unique-evidence p-value |
| `pvalue_simes_intersection` | Two-component Simes intersection p-value |
| `pvalue_simes_closed` | Unique-evidence closed-test p-value; 1 with zero observed unique peptides |
| `pvalue_combined_fisher` | Fisher combination retained for sensitivity comparison |
| `pvalue_combined_harmonic_calibrated` | Factor-2 K=2 calibrated two-component HMP sensitivity value |
| `pvalue_combined_harmonic` | Equal-weight HMP with the configured unique-evidence gate |
| `pvalue_combined_bonferroni` | Two-test Bonferroni minimum-p sensitivity value |
| `pvalue` | Selected genome-level p-value; by default `pvalue_simes_closed` |
| `qvalue` | BH-adjusted genome-level q-value within active genomes of the analysis unit |
| `presence_score` | Ranking score based on q-value |

## Citation

If you use MetaUmbra, please cite:

> Wu Q, Ning Z, Zhang A, Cheng K, Figeys D. MetaUmbra: Statistically Controlled Genome-Level Presence Inference from Metaproteomic Peptides.[J]. [bioRxiv, 2026.04.29.721689.](https://doi.org/10.64898/2026.04.29.721689)

A formal citation will be added after publication.

## Contact

For questions or issues, please use the GitHub issue tracker or contact the corresponding author listed in the associated manuscript.
