IM2Deep 2.0 API

.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Python package test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        system: [["3.11", "ubuntu-latest"], ["3.12", "macos-latest"], ["3.12", "ubuntu-latest"]]
+    runs-on: ${{ matrix.system[1] }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.system[0] }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.system[0] }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 pytest
+          pip install --editable .[test]
+      - name: Lint with flake8
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Test with pytest
+        run: |
+          pytest

.gitignore

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

README.md

@@ -4,45 +4,93 @@ 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`
+```bash
+pip install im2deep
+```
 
-If you want to use the multi-output model for CCS prediction of multiconformational peptide ions, use the following installation command:
+## Usage
 
-`pip install 'im2deep[er]'`
+### Command Line Interface (CLI)
 
-## Usage
-### Basic CLI usage:
-```sh
+**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>
+```
+
+**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
 ```
-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
+
+For a complete overview of all CLI arguments, run:
+```bash
+im2deep --help
 ```
-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)
+### Python API
+
+IM2Deep can also be used programmatically:
+
+```python
+from im2deep import predict, predict_and_calibrate
+from psm_utils import PSMList
 
-For example:
+# 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 +102,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 +119,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

@@ -39,16 +39,13 @@
 __version__ = "1.2.0"
 
 # Import main functionality for easier access
-from im2deep.im2deep import predict_ccs
-from im2deep.calibrate import linear_calibration
+from importlib.metadata import version
 from im2deep.utils import ccs2im, im2ccs
-from im2deep._exceptions import IM2DeepError, CalibrationError
 
+__version__: str = version("im2deep")
 __all__ = [
-    "predict_ccs",
-    "linear_calibration",
+    "predict",
+    "calibrate_and_predict",
     "ccs2im",
     "im2ccs",
-    "IM2DeepError",
-    "CalibrationError",
 ]