add architectures + training

CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `core.train()` and `core.finetune()`, replacing the `NotImplementedError` stub that
+  pointed at the separate `im2deeptrainer` package. Both featurise through
+  `DeepLCDataset`, the same path `predict()` uses, so a trained checkpoint is directly
+  usable for prediction
+- `im2deep train` and `im2deep finetune` CLI commands
+- New `_data` module with `CCSDataset` (flattens DeepLC's nested feature tuple for
+  training), `build_training_dataset` (accepts a PSMList, DataFrame or delimited file,
+  and reads the target from `CCS` or `ccs`) and `grouped_split` (train/validation split
+  grouped by stripped sequence, so a peptide cannot appear in both halves)
+- `DEFAULT_TRAINING_CONFIG` with the training-loop and featurisation keys, leaving
+  `DEFAULT_CONFIG` untouched
+- `Global_features` configuration key, making the architectures' global branch width
+  configurable so featurisations other than the default 60 can be trained. Defaults to
+  60, so existing checkpoints and configurations are unaffected
+- `BackboneFreeze` callback, freezing a transfer model's pretrained feature branches for
+  a warmup before unfreezing at a reduced learning rate
+- Trained checkpoints now record their own configuration, so a model is read back with
+  the architecture and featurisation it was trained on
+- Weights & Biases logging, off by default. Runs are named after `model_name` (or an
+  explicit `wandb.name`) and carry the full training config, so a set of runs differing
+  only in training data or featurisation is comparable. `--wandb`, `--wandb-project` and
+  `--wandb-name` on both CLI commands; `entity` and `tags` are settable from a config
+  file
+
+### Changed
+- Widened the `deeplc` dependency to `>=4.1.0,<5`. From 4.1.0 the 4.0.1 feature-encoding
+  change sits behind `legacy_positional_deltas`, which defaults to `True`, so the
+  encoding matches what the bundled checkpoints were trained with. Verified
+  bit-identical to 4.0.0 across 4,000 peptidoforms, 3,000 of them modified
+- `predict()` now selects the architecture and featurisation from the checkpoint rather
+  than assuming the package defaults, so fine-tuned models and models trained with
+  other featurisations load correctly
+- `wandb` is now an optional extra (`pip install im2deep[wandb]`) rather than an
+  undeclared import
+
+### Fixed
+- `IM2DeepTransfer`'s training, validation and test steps did not squeeze the model
+  output in the `add_X_mol` branch, so the loss broadcast to a `(batch, batch)` matrix
+  instead of comparing element-wise
+
 ## [2.0.2] - 2026-07-16
 
 ### Added

docs/source/index.rst

@@ -11,6 +11,15 @@
    Changelog <changelog>
 
 
+.. toctree::
+   :caption: Guides
+   :hidden:
+   :includehidden:
+   :maxdepth: 2
+
+   Training <training>
+
+
 .. toctree::
    :caption: Command line interface
    :hidden:

docs/source/training.rst

@@ -0,0 +1,139 @@
+Training
+========
+
+IM2Deep can train a new CCS prediction model from scratch, or fine-tune an
+existing one on your own runs. Both go through the same DeepLC featuriser that
+:func:`im2deep.core.predict` uses, so a model that comes out of training is
+directly usable for prediction.
+
+Training data
+-------------
+
+Training data is a delimited file, a :class:`pandas.DataFrame`, or a
+:class:`~psm_utils.psm_list.PSMList`.
+
+Tabular input needs a target CCS column, named either ``CCS`` or ``ccs``, plus
+either a ``peptidoform`` column of ProForma strings or the three columns
+``seq``, ``modifications`` and ``charge``:
+
+.. code-block:: text
+
+    seq,modifications,charge,ccs
+    AAAAAAAAAAAAAAAAASAGGK,,2,445.04
+    AAAAAAAAAAAAAAAAAGATCLER,21|U:4,3,634.92
+
+A :class:`~psm_utils.psm_list.PSMList` needs a target on every PSM, as either
+``psm.ion_mobility`` or ``psm.metadata["CCS"]``. Ion mobility is converted to
+CCS automatically.
+
+Peptides longer than the 60-residue featurisation window are dropped rather than
+silently truncated, as are rows with a missing or non-finite CCS. Both are
+reported in the log.
+
+Training a new model
+--------------------
+
+From the command line:
+
+.. code-block:: bash
+
+    im2deep train train.csv -o my_model.ckpt --epochs 100 --num-workers 16
+
+Or from Python:
+
+.. code-block:: python
+
+    from im2deep import train
+
+    model = train("train.csv", "my_model.ckpt", training_kwargs={"epochs": 100})
+
+A validation set is split off the training data, grouped by stripped sequence so
+that the same peptide cannot appear in both halves at different charge states or
+modification states. Pass ``--validation-data`` (or ``validation_psm_list=``) to
+supply one explicitly instead.
+
+``--num-workers`` matters on large datasets: featurisation happens on the fly in
+the dataloader and is CPU-bound, so it is usually the bottleneck rather than the
+GPU.
+
+Fine-tuning an existing model
+-----------------------------
+
+Fine-tuning adapts a trained model to new data, which is useful when your runs
+sit on a systematically different CCS scale than the training data:
+
+.. code-block:: bash
+
+    im2deep finetune my_runs.csv -o finetuned.ckpt --freeze-epochs 5
+
+The pretrained feature branches are held frozen for the first ``--freeze-epochs``
+epochs while the head adapts, then unfrozen and training continues at a reduced
+learning rate. By default the bundled IM2Deep model is the backbone; pass
+``--backbone`` to use another checkpoint.
+
+Configuration
+-------------
+
+Every model and training parameter can be set through a JSON configuration file:
+
+.. code-block:: bash
+
+    im2deep train train.csv -o my_model.ckpt --config config.json
+
+.. code-block:: json
+
+    {
+      "model_params": {
+        "epochs": 100,
+        "batch_size": 512,
+        "learning_rate": 0.001,
+        "patience": 10,
+        "wandb": {"enabled": true, "project_name": "IM2Deep"}
+      }
+    }
+
+The ``model_params`` block is optional; a flat object works too. Values are
+merged over :data:`im2deep.constants.DEFAULT_TRAINING_CONFIG`, and explicit
+command-line flags or ``training_kwargs`` win over the file.
+
+Weights & Biases logging needs the optional extra:
+
+.. code-block:: bash
+
+    pip install im2deep[wandb]
+
+Featurisation variants
+----------------------
+
+Three configuration keys change how peptides are encoded. They alter the number
+of global features, so ``Global_features`` must be set to match; training refuses
+to start otherwise rather than failing later with a shape error.
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``add_ccs_features``
+     - ``add_terminal_composition``
+     - ``Global_features``
+   * - ``false``
+     - ``false``
+     - 55
+   * - ``true`` (default)
+     - ``false`` (default)
+     - 60
+   * - ``false``
+     - ``true``
+     - 67
+   * - ``true``
+     - ``true``
+     - 72
+
+``legacy_positional_deltas`` controls positional modification indexing. It
+defaults to ``true``, reproducing the encoding the bundled models were trained
+with. Setting it to ``false`` uses DeepLC's corrected indexing, which changes the
+encoding of modified peptides only.
+
+Each trained checkpoint records the configuration it was trained with, so
+:func:`im2deep.core.predict` reads a model back with the right architecture and
+featurisation automatically. There is no need to repeat these settings at
+prediction time.

im2deep/__init__.py

@@ -24,7 +24,7 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
-from im2deep.core import predict, predict_and_calibrate
+from im2deep.core import finetune, predict, predict_and_calibrate, train
 from im2deep.utils import ccs2im, im2ccs
 
 try:
@@ -34,6 +34,8 @@
 __all__ = [
     "predict",
     "predict_and_calibrate",
+    "train",
+    "finetune",
     "ccs2im",
     "im2ccs",
 ]