Merge release branch for v2.0.0

.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/

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --group docs
+    - uv run python -m sphinx -T -b dirhtml docs/source $READTHEDOCS_OUTPUT/html

CHANGELOG.md

@@ -7,25 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-07-13
+
 ### Added
+- New `core` module with `predict` and `predict_and_calibrate` as main public API
+- New `calibration` module replacing `calibrate`, with `Calibration` and `LinearCCSCalibration` classes
+- New `constants` module for default model paths and configuration
+- New `exceptions` module (public, replacing private `_exceptions`)
+- New `_model_ops` module for PyTorch model loading and inference
+- New `_io_helpers` module (split from `utils`) for file parsing and I/O
+- Architecture subpackage (`_architectures`) with modular components: activations, blocks, callbacks, losses, helpers
+- Multi-conformer CCS prediction support (`IM2DeepMulti`)
+- PyTorch Lightning-based model architectures replacing Keras models
+- `num_threads` argument to control Torch CPU parallelization
+- Profiling support in CLI (`--profile` flag)
+- Test suite with tests for calibration, CLI, constants, core, exceptions, integration, losses, model ops, and utils
+- CI workflow for tests and type checking
 - This CHANGELOG file
-- Comprehensive documentation with API reference, development guide, and tutorial
-- Enhanced error handling with custom exceptions
-- Input validation throughout the codebase
-- Type hints for better code clarity
-- Detailed logging with different verbosity levels
 
 ### Changed
-- Improved function signatures with better parameter validation
-- Enhanced docstrings with NumPy style documentation
-- Better error messages with more context
-- Improved CLI with better help text and validation
-- More robust file handling with proper encoding
-- Enhanced calibration functions with edge case handling
+- **Breaking:** Public API changed from `predict_ccs`/`linear_calibration` to `predict`/`predict_and_calibrate`
+- **Breaking:** Minimum Python version raised from 3.10 to 3.11
+- **Breaking:** Switched from Keras/TensorFlow models to PyTorch Lightning models (`.ckpt`)
+- Switched build system from setuptools to uv
+- CLI restructured as click command group with `predict` as default command
+- Renamed reference data files for clarity
+- Linting moved from black/isort to ruff
+- Upgrade `deeplc` dependency to `deeplc>=4.0.0b1,<5`
+- Added explicit lower/upper version bounds to all core dependencies.
 
-### Fixed
-- Import error handling for optional dependencies
-- File path validation in CLI
-- Memory management improvements
-- Edge cases in CCS/ion mobility conversions
-- Calibration edge cases with insufficient data
+### Removed
+- `im2deep.py` module (replaced by `core.py`)
+- `calibrate.py` module (replaced by `calibration.py`)
+- `predict_multi.py` module (functionality merged into architecture subpackage)
+- Keras model files
+- Removed pinned `numpy==1.26.0` dependency
+- Removed `im2deeptrainer` optional dependency

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,107 @@ 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`
+With Python 3.11 or higher, install with pip:
 
-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
+```
+
+We recommend using a [venv](https://docs.python.org/3/library/venv.html) or
+[conda](https://docs.conda.io/en/latest/) virtual environment.
 
-`pip install 'im2deep[er]'`
+### For development
+
+Clone this repository and use [uv](https://docs.astral.sh/uv/) to install:
+
+```bash
+git clone https://github.com/CompOmics/IM2Deep.git
+cd IM2Deep
+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>
+```
+
+**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
 ```
-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
+
+**Output options:**
+```bash
+im2deep <path/to/peptide_file.csv> --output-file predictions.csv
+```
+
+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
 
-For example:
+IM2Deep can also be used programmatically:
+
+```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,8 +116,13 @@ 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:
+If you use IM2Deep within the context of [(TI)MS²Rescore](https://github.com/compomics/ms2rescore), please cite the following:
 > **TIMS²Rescore: A DDA-PASEF optimized data-driven rescoring pipeline based on MS²Rescore.**
 > Arthur Declercq*, Robbe Devreese*, Jonas Scheid, Caroline Jachmann, Tim Van Den Bossche, Annica Preikschat, David Gomez-Zepeda, Jeewan Babu Rijal, Aurélie Hirschler, Jonathan R Krieger, Tharan Srikumar, George Rosenberger, Dennis Trede, Christine Carapito, Stefan Tenzer, Juliane S Walz, Sven Degroeve, Robbin Bouwmeester, Lennart Martens, and Ralf Gabriels.
 > _Journal of Proteome Research_ (2025) [doi:10.1021/acs.jproteome.4c00609](https://doi.org/10.1021/acs.jproteome.4c00609) <span class="__dimensions_badge_embed__" data-doi="10.1021/acs.jproteome.4c00609" data-hide-zero-citations="true" data-style="small_rectangle"></span>
@@ -66,4 +133,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)
 
 
-