Metadata-Version: 2.5
Name: proteoform-regions
Version: 0.1.0
Summary: Proteoform-aware region inference and detection-bias quantification from bottom-up proteomics peptide tables
Project-URL: Homepage, https://github.com/ShoabSaadat/proteoform-regions
Project-URL: Documentation, https://shoabsaadat.github.io/proteoform-regions
Project-URL: Repository, https://github.com/ShoabSaadat/proteoform-regions
Project-URL: Changelog, https://github.com/ShoabSaadat/proteoform-regions/blob/main/CHANGELOG.md
Author: Shoaib Saadat
License: MIT License
        
        Copyright (c) 2026 Shoaib Saadat
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: bottom-up,detected region,detection bias,isoelectric point,mass spectrometry,peptide,precursor masking,proteoform,proteomics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: biopython<2,>=1.83
Requires-Dist: lxml<7,>=4.9
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas<4,>=2.2
Requires-Dist: pyteomics<7,>=5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests<3,>=2.31
Requires-Dist: scipy<2,>=1.11
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: ipykernel>=6; extra == 'dev'
Requires-Dist: nbmake>=1.5; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter>=0.25; extra == 'docs'
Requires-Dist: mkdocs-material>=9; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: io
Requires-Dist: openpyxl>=3.1; extra == 'io'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.8; extra == 'plots'
Description-Content-Type: text/markdown

# proteoform-regions

[![CI](https://github.com/ShoabSaadat/proteoform-regions/actions/workflows/ci.yml/badge.svg)](https://github.com/ShoabSaadat/proteoform-regions/actions/workflows/ci.yml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ShoabSaadat/proteoform-regions/blob/main/LICENSE)
[![Code style: typed](https://img.shields.io/badge/style-typed-333333.svg)](https://mypy-lang.org)

**Proteoform-aware region inference and detection-bias quantification from bottom-up proteomics peptide tables.**

`proteoform-regions` is the software implementation of the pipeline described in
*"Basic-peptide depletion and precursor masking in bottom-up proteomics"* (Saadat et al., 2026).
It ingests heterogeneous bottom-up peptide-level result tables (MaxQuant, DIA-NN, Spectronaut,
Progenesis, mzIdentML, glycopeptide exports, FragPipe PSM tables), harmonizes them into a
single tiered evidence schema, computes peptide/region physicochemistry (pI, MW, net charge),
stitches detected regions from peptide evidence, and quantifies acidic/basic detection bias
with digestion-matched tryptic backgrounds.

## What this package does and adds

When scientists hunt for disease biomarkers in blood plasma, they use **bottom-up proteomics**: proteins are chopped into peptides, the peptides are measured, and findings are reported as if the whole proteins had been measured. But the instrument never saw the whole protein — it saw fragments, and which fragments are detected is biased (some ionize poorly, some are missed entirely). The "protein" in the report is therefore an annotated guess built from patchy evidence, and its stated chemistry (charge balance, size) can misrepresent the actual molecular evidence underneath.

`proteoform-regions` performs the honest re-reading. Feed it the peptide tables any major search engine produces (MaxQuant, DIA-NN, Spectronaut, Progenesis, mzIdentML, FragPipe, glycopeptide exports — 10 formats), and it:

1. **maps every detected fragment** to its exact address on the parent protein;
2. **stitches overlapping fragments into detected regions** — the stretches of the protein actually observed;
3. **computes each region's real chemistry** (pI, MW, charge) instead of inheriting the whole protein's;
4. **grades every claim by confidence** — from single-peptide to multi-peptide region to top-down-validated;
5. **quantifies detection bias** against digestion-matched tryptic backgrounds with full statistics (permutation nulls, meta-analysis).

**What it adds to science:** (i) a correction lens for the thousands of already-deposited public biomarker datasets — re-read what was reported against what was actually detected, no new experiments required; (ii) a reproducible benchmark — shipped parameters, checksum-pinned test data, and a freeze-parity suite demonstrating it reproduces the source publication's statistics exactly; (iii) methodological transparency — every previously hidden constant (stitching gap, seeds, thresholds) is an exposed, documented parameter.

**Scope honesty:** this tool detects and grades *regions* of proteins — it does not claim to identify complete proteoforms. Top-down benchmarking shows bottom-up regions cover proteoform sequence space well but do not delimit proteoform boundaries; the tool's vocabulary and confidence taxonomy enforce that distinction.

## Install

```bash
pip install proteoform-regions            # core
pip install "proteoform-regions[io]"      # + xlsx PSM tables (FragPipe exports)
pip install "proteoform-regions[plots]"   # + plotting helpers
```

## Quickstart

```python
import proteoform_regions as pfr

studies = pfr.load_cohort("cohort.yaml")  # declarative study configs
evidence, stats = pfr.harmonize(studies, "data/raw")  # tiered evidence table
mapping, proteins = pfr.map_to_uniprot(evidence)  # UniProt snapshot-pinned
features = pfr.compute_features(evidence, mapping, proteins, calculator="bjellqvist")
background = pfr.build_background(protein_sequences)  # digestion-matched tryptic peptides
regions = pfr.stitch_regions(features, mapping)  # gap-25 single-linkage regions
bias = pfr.quantify_bias(features, background)  # RQ1 permutation + RQ2 OR meta-analysis

report = pfr.run("cohort.yaml", "run/")  # all stages + artifacts + sha256 manifest
```

Or from the command line:

```console
$ proteoform-regions run --study cohort.yaml --out-dir run/
$ proteoform-regions bias --features run/processed_feature_table.csv \
    --background run/processed_tryptic_background.csv --out results.json
$ proteoform-regions benchmark    # frozen ExPASy/UniProt engine benchmark, offline
```

## Documentation

Hosted documentation (installation, quickstart, walkthrough on a new dataset, CLI + API
reference): <https://shoabsaadat.github.io/proteoform-regions>

New-dataset walkthrough (FragPipe PSMs → regions, fully offline on committed sample data):
[`docs/sadeghi_walkthrough.ipynb`](docs/sadeghi_walkthrough.ipynb) — the notebook executes
headless in CI, and its sample assets live in
[`examples/walkthrough/`](examples/walkthrough/) (50-PSM Sheet12 sample + dated UniProt
snapshot; never the 181 MB raw sheet).

## Method provenance

Every numerical default in this package (pK tables, the 7–60 aa digest length filter, the
≤25-residue region-stitching gap, seed-42 permutation settings, unconditional 0.5 zero-cell
correction) mirrors a pre-specified parameter of the source publication and is covered by
unit and freeze-parity tests. The package is the parametrized form of the paper's
Supplementary Methods.

## License

MIT — see [LICENSE](https://github.com/ShoabSaadat/proteoform-regions/blob/main/LICENSE).
