protrider 0.9.1__tar.gz

protrider-0.9.1/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

protrider-0.9.1/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest tests/ -q
+
+      - name: Run CLI smoke test
+        run: |
+          uv run protrider run --config config.yaml
+          uv run protrider plot --config config.yaml all

protrider-0.9.1/.gitignore

@@ -0,0 +1,12 @@
+protrider/.ipynb_checkpoints/*
+**/*egg-info
+**/__pycache__
+**/.ipynb_checkpoints
+protrider-simulation/
+output/*
+logs/*
+.vscode/*
+**/.pytest_cache
+.venv/
+wandb/*
+*.pt

protrider-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gagneur Lab, Technical University of Munich
+
+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.

protrider-0.9.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: protrider
+Version: 0.9.1
+Summary: PROTRIDER - Protein outlier detection method
+Author: Ines Scheller, George Tsitsiridis, Christian Mertes, Vicente A Yépez, Ata Jadid Ahari
+Author-email: Daniela Klaproth-Andrade <daniela.andrade@tum.de>, Julien Gagneur <gagneur@in.tum.de>
+License: MIT License
+        
+        Copyright (c) 2025 Gagneur Lab, Technical University of Munich
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/gagneurlab/PROTRIDER
+Project-URL: Bug Tracker, https://github.com/gagneurlab/PROTRIDER/issues
+Project-URL: Publication, https://doi.org/10.1093/bioinformatics/btaf628
+Keywords: proteomics,mass spectrometry,outlier detection,autoencoder,bioinformatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyaml
+Requires-Dist: torch
+Requires-Dist: tqdm
+Requires-Dist: optht
+Requires-Dist: pydeseq2
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: seaborn
+Requires-Dist: plotnine
+Requires-Dist: pyarrow
+Requires-Dist: fastparquet
+Provides-Extra: wandb
+Requires-Dist: wandb; extra == "wandb"
+Dynamic: license-file
+
+# PROTRIDER
+
+[![Tests](https://github.com/gagneurlab/PROTRIDER/actions/workflows/tests.yml/badge.svg)](https://github.com/gagneurlab/PROTRIDER/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+PROTRIDER is an autoencoder-based method to call protein outliers from mass spectrometry-based proteomics datasets.
+
+Have a look at our [paper](https://doi.org/10.1093/bioinformatics/btaf628) for information about our work.
+
+<details open>
+<summary><b>Table of Contents</b></summary>
+
+- [🚀 Quickstart](#-quickstart)
+- [⚙️ Installation](#️-installation)
+- [📖 Usage](#-usage)
+  - [🗂️ Configuration](#️-configuration)
+  - [📤 Output](#-output)
+  - [▶️ Run](#️-run)
+- [📄 License](#-license)
+- [📚 Citation](#-citation)
+
+</details>
+
+## 🚀 Quickstart
+
+```bash
+# 1. Install
+pip install .
+
+# 2. Run on the included sample data
+protrider run --config config.yaml
+
+# 3. Plot results
+protrider plot --config config.yaml all
+```
+
+Results are written to the directory specified by `out_dir` in `config.yaml` (default: `output/`). The key output file is `protrider_summary.csv`, which contains outlier calls with p-values, z-scores, and fold changes for every sample–protein pair.
+
+## ⚙️ Installation
+
+PROTRIDER was tested using Python 3.14 on Linux. We recommend a dedicated conda environment:
+
+```bash
+conda create --name protrider_env python=3.14
+conda activate protrider_env
+pip install .
+```
+
+Verify the installation:
+
+```bash
+protrider --help
+```
+
+More information on conda environments can be found in [Conda's user guide](https://docs.conda.io/projects/conda/en/latest/user-guide/).
+
+## 📖 Usage
+
+### 🗂️ Configuration
+
+All parameters are set in a YAML configuration file. A template is provided as `config.yaml`.
+
+Input files are specified in the config:
+
+- **`input_intensities`**: CSV, TSV, or Parquet file with protein intensities (columns = samples, rows = proteins)
+- **`sample_annotation`** (optional): CSV or TSV file with sample covariates (one row per sample)
+
+An example dataset is included under `sample_data/`.
+
+<details open>
+<summary><b>Configuration parameters</b></summary>
+
+| Parameter | Description |
+|-----------|-------------|
+| `out_dir` | Output directory |
+| `input_intensities` | Path to protein intensities file |
+| `sample_annotation` | Path to sample annotations file (optional) |
+| `index_col` | Column name containing protein IDs |
+| `cov_used` | List of covariate column names from the annotation file (optional) |
+| `find_q_method` | Method to determine latent dimension: `OHT` (default), `gs`, `bs` (binary search), or an integer |
+| `pval_dist` | Distribution for p-value calculation: `t` (default) or `gaussian` |
+| `n_epochs` | Number of training epochs (default: `100`) |
+| `checkpoint_path` | Path to save/load model checkpoint (optional) |
+
+</details>
+
+### 📤 Output
+
+The key output file is `protrider_summary.csv`, which contains outlier calls with p-values, z-scores, and fold changes for every sample–protein pair.
+
+<details>
+<summary><b>Output files</b></summary>
+
+| File | Description |
+|------|-------------|
+| `protrider_summary.csv` | Long-format summary with outlier calls for all sample–protein pairs |
+| `pvals.csv` | Two-sided p-values (samples × proteins) |
+| `pvals_adj.csv` | BH/BY-adjusted p-values |
+| `pvals_one_sided.csv` | Left-sided p-values |
+| `zscores.csv` | Z-scores |
+| `residuals.csv` | Model residuals (observed − predicted) |
+| `log2fc.csv` | Log2 fold changes |
+| `fc.csv` | Fold changes |
+| `output.csv` | Autoencoder reconstructed values |
+| `processed_input.csv` | Preprocessed input passed to the autoencoder |
+| `additional_info.csv` | Model metadata (latent dimension, learning rate, loss) |
+| `train_losses.csv` | Per-epoch training loss |
+| `fit_parameters.csv` | Per-protein distribution fit parameters |
+| `config.yaml` | Saved configuration for reproducibility |
+
+</details>
+
+### ▶️ Run
+
+Run the pipeline:
+
+```bash
+protrider run --config config.yaml
+```
+
+Generate plots:
+
+```bash
+# All plots
+protrider plot --config config.yaml all
+
+# Individual plot types
+protrider plot --config config.yaml pvals
+protrider plot --config config.yaml aberrant_per_sample
+protrider plot --config config.yaml training_loss
+protrider plot --config config.yaml encoding_dim
+
+# Expected vs observed for a specific protein
+protrider plot --config config.yaml expected_vs_observed --protein_id <protein_id>
+```
+
+<details>
+<summary><b>Model checkpointing</b></summary>
+
+PROTRIDER automatically saves trained models and reuses them in subsequent runs, skipping retraining if a checkpoint exists. By default the model is saved to `<out_dir>/model.pt`.
+
+To use a custom checkpoint location, set `checkpoint_path` in your config:
+
+```yaml
+checkpoint_path: models/my_model.pt
+```
+
+To force retraining, delete the checkpoint file or point to a new path.
+
+</details>
+
+<details>
+<summary><b>Python API</b></summary>
+
+```python
+import protrider
+
+config = protrider.ProtriderConfig(
+    out_dir='output/',
+    input_intensities='data/protein_intensities.csv',
+    sample_annotation='data/sample_annotations.csv',
+    index_col='protein_ID',
+    cov_used=['AGE', 'SEX'],
+    n_epochs=100,
+)
+
+# Run
+result, model_info, fit_params, gs_result = protrider.run(config)
+
+# Save results
+result.save(config.out_dir, format='wide')   # individual CSV files
+result.save(config.out_dir, format='long')   # protrider_summary.csv
+model_info.save(config.out_dir)
+config.save(config.out_dir)
+
+# Generate plots (omit out_dir to get plot objects without saving)
+model_info.plot_training_loss(config.out_dir)
+result.plot_aberrant_per_sample(config.out_dir)
+hist_plot, qq_plot = result.plot_pvals(config.out_dir)
+result.plot_expected_vs_observed('protein_123', config.out_dir)
+
+# Access results as DataFrames
+result.df_pvals        # p-values
+result.df_pvals_adj    # adjusted p-values
+result.df_Z            # z-scores
+result.df_res          # residuals
+result.log2fc          # log2 fold changes
+result.fc              # fold changes
+```
+
+</details>
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## 📚 Citation
+
+If you use PROTRIDER, please cite:
+
+```bibtex
+@article{10.1093/bioinformatics/btaf628,
+    author = {Klaproth-Andrade, Daniela and Scheller, Ines F and Tsitsiridis, Georgios and Loipfinger, Stefan and Mertes, Christian and Smirnov, Dmitrii and Prokisch, Holger and Yépez, Vicente A and Gagneur, Julien},
+    title = {PROTRIDER: Protein abundance outlier detection from mass spectrometry-based proteomics data with a conditional autoencoder},
+    journal = {Bioinformatics},
+    pages = {btaf628},
+    year = {2025},
+    month = {11},
+    issn = {1367-4811},
+    doi = {10.1093/bioinformatics/btaf628},
+    url = {https://doi.org/10.1093/bioinformatics/btaf628},
+}
+```

protrider-0.9.1/README.md

@@ -0,0 +1,214 @@
+# PROTRIDER
+
+[![Tests](https://github.com/gagneurlab/PROTRIDER/actions/workflows/tests.yml/badge.svg)](https://github.com/gagneurlab/PROTRIDER/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+PROTRIDER is an autoencoder-based method to call protein outliers from mass spectrometry-based proteomics datasets.
+
+Have a look at our [paper](https://doi.org/10.1093/bioinformatics/btaf628) for information about our work.
+
+<details open>
+<summary><b>Table of Contents</b></summary>
+
+- [🚀 Quickstart](#-quickstart)
+- [⚙️ Installation](#️-installation)
+- [📖 Usage](#-usage)
+  - [🗂️ Configuration](#️-configuration)
+  - [📤 Output](#-output)
+  - [▶️ Run](#️-run)
+- [📄 License](#-license)
+- [📚 Citation](#-citation)
+
+</details>
+
+## 🚀 Quickstart
+
+```bash
+# 1. Install
+pip install .
+
+# 2. Run on the included sample data
+protrider run --config config.yaml
+
+# 3. Plot results
+protrider plot --config config.yaml all
+```
+
+Results are written to the directory specified by `out_dir` in `config.yaml` (default: `output/`). The key output file is `protrider_summary.csv`, which contains outlier calls with p-values, z-scores, and fold changes for every sample–protein pair.
+
+## ⚙️ Installation
+
+PROTRIDER was tested using Python 3.14 on Linux. We recommend a dedicated conda environment:
+
+```bash
+conda create --name protrider_env python=3.14
+conda activate protrider_env
+pip install .
+```
+
+Verify the installation:
+
+```bash
+protrider --help
+```
+
+More information on conda environments can be found in [Conda's user guide](https://docs.conda.io/projects/conda/en/latest/user-guide/).
+
+## 📖 Usage
+
+### 🗂️ Configuration
+
+All parameters are set in a YAML configuration file. A template is provided as `config.yaml`.
+
+Input files are specified in the config:
+
+- **`input_intensities`**: CSV, TSV, or Parquet file with protein intensities (columns = samples, rows = proteins)
+- **`sample_annotation`** (optional): CSV or TSV file with sample covariates (one row per sample)
+
+An example dataset is included under `sample_data/`.
+
+<details open>
+<summary><b>Configuration parameters</b></summary>
+
+| Parameter | Description |
+|-----------|-------------|
+| `out_dir` | Output directory |
+| `input_intensities` | Path to protein intensities file |
+| `sample_annotation` | Path to sample annotations file (optional) |
+| `index_col` | Column name containing protein IDs |
+| `cov_used` | List of covariate column names from the annotation file (optional) |
+| `find_q_method` | Method to determine latent dimension: `OHT` (default), `gs`, `bs` (binary search), or an integer |
+| `pval_dist` | Distribution for p-value calculation: `t` (default) or `gaussian` |
+| `n_epochs` | Number of training epochs (default: `100`) |
+| `checkpoint_path` | Path to save/load model checkpoint (optional) |
+
+</details>
+
+### 📤 Output
+
+The key output file is `protrider_summary.csv`, which contains outlier calls with p-values, z-scores, and fold changes for every sample–protein pair.
+
+<details>
+<summary><b>Output files</b></summary>
+
+| File | Description |
+|------|-------------|
+| `protrider_summary.csv` | Long-format summary with outlier calls for all sample–protein pairs |
+| `pvals.csv` | Two-sided p-values (samples × proteins) |
+| `pvals_adj.csv` | BH/BY-adjusted p-values |
+| `pvals_one_sided.csv` | Left-sided p-values |
+| `zscores.csv` | Z-scores |
+| `residuals.csv` | Model residuals (observed − predicted) |
+| `log2fc.csv` | Log2 fold changes |
+| `fc.csv` | Fold changes |
+| `output.csv` | Autoencoder reconstructed values |
+| `processed_input.csv` | Preprocessed input passed to the autoencoder |
+| `additional_info.csv` | Model metadata (latent dimension, learning rate, loss) |
+| `train_losses.csv` | Per-epoch training loss |
+| `fit_parameters.csv` | Per-protein distribution fit parameters |
+| `config.yaml` | Saved configuration for reproducibility |
+
+</details>
+
+### ▶️ Run
+
+Run the pipeline:
+
+```bash
+protrider run --config config.yaml
+```
+
+Generate plots:
+
+```bash
+# All plots
+protrider plot --config config.yaml all
+
+# Individual plot types
+protrider plot --config config.yaml pvals
+protrider plot --config config.yaml aberrant_per_sample
+protrider plot --config config.yaml training_loss
+protrider plot --config config.yaml encoding_dim
+
+# Expected vs observed for a specific protein
+protrider plot --config config.yaml expected_vs_observed --protein_id <protein_id>
+```
+
+<details>
+<summary><b>Model checkpointing</b></summary>
+
+PROTRIDER automatically saves trained models and reuses them in subsequent runs, skipping retraining if a checkpoint exists. By default the model is saved to `<out_dir>/model.pt`.
+
+To use a custom checkpoint location, set `checkpoint_path` in your config:
+
+```yaml
+checkpoint_path: models/my_model.pt
+```
+
+To force retraining, delete the checkpoint file or point to a new path.
+
+</details>
+
+<details>
+<summary><b>Python API</b></summary>
+
+```python
+import protrider
+
+config = protrider.ProtriderConfig(
+    out_dir='output/',
+    input_intensities='data/protein_intensities.csv',
+    sample_annotation='data/sample_annotations.csv',
+    index_col='protein_ID',
+    cov_used=['AGE', 'SEX'],
+    n_epochs=100,
+)
+
+# Run
+result, model_info, fit_params, gs_result = protrider.run(config)
+
+# Save results
+result.save(config.out_dir, format='wide')   # individual CSV files
+result.save(config.out_dir, format='long')   # protrider_summary.csv
+model_info.save(config.out_dir)
+config.save(config.out_dir)
+
+# Generate plots (omit out_dir to get plot objects without saving)
+model_info.plot_training_loss(config.out_dir)
+result.plot_aberrant_per_sample(config.out_dir)
+hist_plot, qq_plot = result.plot_pvals(config.out_dir)
+result.plot_expected_vs_observed('protein_123', config.out_dir)
+
+# Access results as DataFrames
+result.df_pvals        # p-values
+result.df_pvals_adj    # adjusted p-values
+result.df_Z            # z-scores
+result.df_res          # residuals
+result.log2fc          # log2 fold changes
+result.fc              # fold changes
+```
+
+</details>
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## 📚 Citation
+
+If you use PROTRIDER, please cite:
+
+```bibtex
+@article{10.1093/bioinformatics/btaf628,
+    author = {Klaproth-Andrade, Daniela and Scheller, Ines F and Tsitsiridis, Georgios and Loipfinger, Stefan and Mertes, Christian and Smirnov, Dmitrii and Prokisch, Holger and Yépez, Vicente A and Gagneur, Julien},
+    title = {PROTRIDER: Protein abundance outlier detection from mass spectrometry-based proteomics data with a conditional autoencoder},
+    journal = {Bioinformatics},
+    pages = {btaf628},
+    year = {2025},
+    month = {11},
+    issn = {1367-4811},
+    doi = {10.1093/bioinformatics/btaf628},
+    url = {https://doi.org/10.1093/bioinformatics/btaf628},
+}
+```

protrider-0.9.1/config.yaml

@@ -0,0 +1,75 @@
+# path to output directory to store result files
+out_dir: output
+
+# csv input file containing intensities. Columns are samples and rows are proteins.
+input_intensities: sample_data/protrider_sample_dataset.tsv
+
+# column name in the input file indicating the column name containing the protein names/IDs
+index_col: "protein_ID"
+
+# csv file containing sample annotations
+# sample_annotation: sample_data/sample_annotations.tsv
+
+## Preprocessing params
+# maximum percentage of missing values per protein
+max_allowed_NAs_per_protein: 0.3
+# transformation funtion to apply to the data before model fitting. options are log10, log2, and log
+# set this to null if the data is already log-transformed
+log_func_name: "log"
+
+# names of columns in the sample annotation file to be passed as covariates to the autoencoder.
+# leaving this empty results in no covariates passed to the model
+cov_used:
+# - SEX
+# - AGE
+# - "BATCH_RUN"
+
+# seed parameter for reproducibility
+seed: 42
+
+## Grid search outlier injection params
+inj_freq: 1e-3
+inj_mean: 3
+inj_sd: 1.6
+gs_epochs: 100
+
+## Model params
+autoencoder_training: True ## when set to false, it returns values after (PCA) initialization without training
+
+n_layers: 1 # number of layers for the autoencoder model
+n_epochs: 100 # number of training epochs
+lr: 1e-4 # learning rate
+batch_size:
+
+find_q_method: "OHT" # option to find latent space dimension. Options: OHT, gs or an integer value
+init_pca: True # PCA initialization
+h_dim: # hidden dimension, only for n_layers>1
+
+## Presence absence modelling
+presence_absence: False
+lambda_presence_absence: 0.5
+
+## Stat params
+pval_dist: 't' # Distribution choice for P-value computation. Options: gaussian, t
+pval_adj: 'by' # Multiple testing correction. Options: by, bh
+pval_sided: 'two-sided'
+common_degrees_freedom: False # whether to use common degrees of freedom; more stable for small datasets
+pseudocount: 0.01 # for FC computation
+
+## Reporting params
+outlier_threshold: 0.1
+report_all: True
+
+verbose: False
+device: 'gpu'
+
+## Model checkpoint
+# Path to save/load model checkpoint (optional)
+# If None: saves to out_dir/model.pt (or model_fold_N.pt for CV)
+# If specified and exists: loads model from this path and skips training
+# If specified and doesn't exist: trains and saves to this path
+# checkpoint_path: 'checkpoint.pt'
+
+use_wandb: False
+# wandb_project: 'protrider_test'
+# wandb_name: 'test_run'