Merge pull request #18 from CompOmics/new-api

IM2Deep 2.0 API

Author: RalfG

.github/workflows/publish.yml

@@ -1,39 +1,49 @@
 name: Publish
 
 on:
-  workflow_dispatch:
   release:
     types: [created]
+  workflow_dispatch:
 
 jobs:
-  publish:
+  build-python-package:
     runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/im2deep
     permissions:
-      id-token: write
+      contents: read
+
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version-file: "pyproject.toml"
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip build
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
       - name: Build
-        run: python -m build
+        run: uv build --no-sources
+
+      - name: Upload dists
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
 
-      - name: Install
-        run: pip install dist/im2deep-*.whl
+  publish-python-package:
+    needs: build-python-package
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
 
-      - name: Test package
-        run: |
-          im2deep --help
+    steps:
+      - name: Download dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yml

@@ -0,0 +1,79 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-python-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Lint
+        uses: astral-sh/ruff-action@v3
+        with:
+          src: "im2deep"
+
+      - name: Check formatting
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "format --check --diff im2deep"
+          src: "im2deep"
+
+  typecheck-python-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --group dev
+
+      - name: Type check
+        run: uv run ty check im2deep
+
+  test-python-package:
+    needs: [lint-python-package, typecheck-python-package]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Prune cache
+        run: uv cache prune --ci

.gitignore

@@ -111,4 +111,7 @@ IM2Deep.code-workspace
 
 # Testing
 test_data/
-test.ipynb
+test.ipynb
+
+# Profiles
+profiles/

CONTRIBUTING.md

@@ -23,8 +23,8 @@ cd IM2Deep
 python -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate
 
-# Install in development mode
-pip install -e .[dev,test]
+# Install dependencies (core + dev group)
+uv sync --group dev
 ```
 
 ## Code Standards

README.md

@@ -4,45 +4,98 @@ Collisional cross-section prediction for (modified) peptides.
 ---
 ## Introduction
 
-IM2Deep is a CCS predictor for (modified) peptides.
-It is able to accurately predict CCS for modified peptides, even if the modification wasn't observed during training.
+IM2Deep is a deep learning-based CCS predictor for (modified) peptides. It accurately predicts collisional cross-section (CCS) values for modified peptides, even if the modification wasn't observed during training. The tool supports both single-conformer and multi-conformer predictions for peptide ions.
 
 ## Installation
 Install with pip:
 
-`pip install im2deep`
-
-If you want to use the multi-output model for CCS prediction of multiconformational peptide ions, use the following installation command:
+```bash
+pip install im2deep
+```
 
-`pip install 'im2deep[er]'`
+For local development/docs:
+```bash
+uv sync --group dev --group docs
+```
 
 ## Usage
-### Basic CLI usage:
-```sh
+
+### Command Line Interface (CLI)
+
+**Basic prediction:**
+```bash
 im2deep <path/to/peptide_file.csv>
 ```
-If you want to calibrate your predictions (HIGHLY recommended), please provide a calibration file:
-```sh
-im2deep <path/to/peptide_file.csv> --calibration-file <path/to/peptide_file_with_CCS.csv>
+
+**With calibration (HIGHLY recommended):**
+```bash
+im2deep <path/to/peptide_file.csv> --calibration-precursors <path/to/calibration_file.csv>
 ```
-To use the multi-output prediction model on top of the original model, provide the -e flag 
-(make sure you have the optional dependencies installed!):
-```sh
-im2deep <path/to/peptide_file.csv> --calibration-file <path/to/peptide_file_with_CCS.csv> -e
+
+**Calibration options:**
+- `--calibrate-per-charge`: Calculate separate calibration shift factors per charge state (recommended, default true)
+- `--use-charge-state`: Charge state for global calibration when --calibrate-per-charge is disabled
+
+**Multi-conformer prediction:**
+To use the multi-output prediction model (requires optional dependencies):
+```bash
+im2deep <path/to/peptide_file.csv> --calibration-precursors <path/to/calibration_file.csv> --multi
+```
+
+**Output options:**
+```bash
+im2deep <path/to/peptide_file.csv> --output-file predictions.csv
 ```
-For an overview of all CLI arguments, run `im2deep --help`.
 
-## Input files
-Both peptide and calibration files are expected to be comma-separated values (CSV) with the following columns:
-  - `seq`: unmodified peptide sequence
-  - `modifications`: every modifications should be listed as `location|name`, separated by a pipe character (`|`)
-     between the location, the name, and other modifications. `location` is an integer counted starting at 1 for the
-     first AA. 0 is reserved for N-terminal modifications, -1 for C-terminal modifications. `name` has to correspond
-     to a Unimod (PSI-MS) name.
-  - `charge`: peptide precursor charge
-  - `CCS`: collisional cross-section (only for calibration file)
+For a complete overview of all CLI arguments, run:
+```bash
+im2deep --help
+```
+
+### Python API
+
+IM2Deep can also be used programmatically:
 
-For example:
+```python
+from im2deep import predict, predict_and_calibrate
+from psm_utils import PSMList
+
+# Load your peptides as PSMList
+psm_list = PSMList(psm_list=[...])  # or use psm_utils.io.read_file()
+
+# Simple prediction
+predictions = predict(psm_list)
+
+# Prediction with calibration
+psm_list_calibration = PSMList(psm_list=[...])  # Must contain CCS values
+calibrated_predictions = predict_and_calibrate(
+    psm_list=psm_list,
+    psm_list_cal=psm_list_calibration
+)
+```
+
+## Input Files
+
+### Standard Format
+IM2Deep accepts any format supported by [psm_utils](https://github.com/compomics/psm_utils), including:
+- Peptide Record (.peprec)
+- MaxQuant msms.txt
+- MSFragger PSM files
+- And more...
+
+### Legacy CSV Format
+Alternatively, use comma-separated values (CSV) with the following columns:
+
+- **`seq`**: Unmodified peptide sequence
+- **`modifications`**: Modifications listed as `location|name`, separated by pipe (`|`) characters
+  - `location`: Integer starting at 1 for the first amino acid
+    - `0` = N-terminal modification
+    - `-1` = C-terminal modification
+  - `name`: Must correspond to a Unimod (PSI-MS) name
+- **`charge`**: Peptide precursor charge state
+- **`CCS`**: Collisional cross-section (only required for calibration files)
+
+**Example:**
 
 ```csv
 seq,modifications,charge,CCS
@@ -54,6 +107,11 @@ DEELIHLDGK,,2,383.8693416055445
 IPQEKCILQTDVK,5|Butyryl|6|Carbamidomethyl,3,516.2079366048176
 ```
 
+## Important Notes
+
+- **Calibration**: Highly recommended for accurate predictions. Calibration corrects for systematic differences between predicted and observed CCS values.
+- **Charge states**: IM2Deep predictions are reliable for charge states up to z=6. PSMs with higher charge states are automatically filtered out during validation.
+
 ## Citing
 If you use IM2Deep within the context of [(TI)MS<sup>2</sup>Rescore](https://github.com/compomics/ms2rescore), please cite the following:
 > **TIMS²Rescore: A DDA-PASEF optimized data-driven rescoring pipeline based on MS²Rescore.**
@@ -66,4 +124,3 @@ In other cases, please cite the following:
 > _Anal. Chem._ (2025) [doi:10.1021/acs.analchem.5c01142](https://pubs.acs.org/doi/10.1021/acs.analchem.5c01142)
 
 
-

im2deep/__init__.py

@@ -20,35 +20,20 @@
     >>> from psm_utils.psm_list import PSMList
     >>> predictions = predict_ccs(psm_list, calibration_data)
 
-Dependencies:
-    - deeplc: For deep learning model infrastructure
-    - psm_utils: For peptide and PSM handling
-    - pandas: For data manipulation
-    - numpy: For numerical computations
-    - click: For command-line interface
-
-Authors:
-    - Robbe Devreese
-    - Robbin Bouwmeester
-    - Ralf Gabriels
-
-License:
-    Apache License 2.0
 """
 
-__version__ = "1.1.1"
+from importlib.metadata import PackageNotFoundError, version
 
-# Import main functionality for easier access
-from im2deep.im2deep import predict_ccs
-from im2deep.calibrate import linear_calibration
+from im2deep.core import predict, predict_and_calibrate
 from im2deep.utils import ccs2im, im2ccs
-from im2deep._exceptions import IM2DeepError, CalibrationError
 
+try:
+    __version__: str = version("im2deep")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for version in pyproject.toml
 __all__ = [
-    "predict_ccs",
-    "linear_calibration",
+    "predict",
+    "predict_and_calibrate",
     "ccs2im",
     "im2ccs",
-    "IM2DeepError",
-    "CalibrationError",
 ]