MaldiDeepKit 0.1.0__py3-none-any.whl

maldideepkit/base/data.py

@@ -0,0 +1,322 @@
+"""Dataset and DataLoader helpers for MALDI-TOF spectra."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+import torch
+from sklearn.model_selection import train_test_split
+from torch.utils.data import DataLoader, Dataset
+
+_STD_FLOOR = 1e-7
+
+
+def _to_numpy(X: Any) -> np.ndarray:
+    """Return ``X`` as a float32 2-D ndarray.
+
+    Accepts NumPy arrays, pandas DataFrames/Series, and any object
+    exposing a DataFrame-like ``.X`` attribute (e.g. :class:`maldiamrkit.MaldiSet`).
+    """
+    if hasattr(X, "X") and not isinstance(X, np.ndarray):
+        X = X.X
+    if hasattr(X, "to_numpy"):
+        X = X.to_numpy()
+    X = np.asarray(X, dtype=np.float32)
+    if X.ndim == 1:
+        X = X.reshape(1, -1)
+    if X.ndim != 2:
+        raise ValueError(f"Expected 2-D feature matrix, got shape {X.shape} instead.")
+    return X
+
+
+class SpectralDataset(Dataset):
+    """PyTorch ``Dataset`` wrapping a binned MALDI-TOF feature matrix.
+
+    The dataset stores its spectra as a single float32 tensor in memory
+    and optionally standardizes each feature on the fly using
+    statistics computed once at construction time.
+
+    Parameters
+    ----------
+    X : array-like or MaldiSet
+        Feature matrix of shape ``(n_samples, n_bins)``. A NumPy array,
+        a pandas DataFrame, or any object with a DataFrame-like ``.X``
+        attribute is accepted.
+    y : array-like, optional
+        Integer class labels of shape ``(n_samples,)``. When ``None``
+        (inference usage) the dataset yields only features.
+    standardize : bool, default=False
+        If ``True``, subtract the per-column mean and divide by the
+        per-column standard deviation computed from ``X``. Columns with
+        zero variance are left untouched.
+    mean : array-like, optional
+        Pre-computed per-feature means. Used together with ``std`` to
+        apply an external standardization (e.g. one fitted on a training
+        fold). Ignored when ``standardize=False``.
+    std : array-like, optional
+        Pre-computed per-feature standard deviations. Ignored when
+        ``standardize=False``.
+
+    Attributes
+    ----------
+    X : torch.Tensor
+        Stored features as a float32 tensor.
+    y : torch.Tensor or None
+        Stored labels as a long tensor, or ``None`` for inference.
+    mean : torch.Tensor or None
+        Feature-wise mean used for standardization.
+    std : torch.Tensor or None
+        Feature-wise standard deviation used for standardization.
+    """
+
+    def __init__(
+        self,
+        X: Any,
+        y: Any | None = None,
+        *,
+        standardize: bool = False,
+        mean: np.ndarray | None = None,
+        std: np.ndarray | None = None,
+    ) -> None:
+        X_np = _to_numpy(X)
+
+        if standardize:
+            if mean is None or std is None:
+                mean = X_np.mean(axis=0)
+                std = X_np.std(axis=0)
+            std = np.asarray(std, dtype=np.float32)
+            mean = np.asarray(mean, dtype=np.float32)
+            safe_std = np.maximum(std, _STD_FLOOR).astype(np.float32)
+            X_np = (X_np - mean) / safe_std
+            self.mean: torch.Tensor | None = torch.from_numpy(
+                np.asarray(mean, dtype=np.float32)
+            )
+            self.std: torch.Tensor | None = torch.from_numpy(safe_std)
+        else:
+            self.mean = None
+            self.std = None
+
+        self.X = torch.from_numpy(X_np)
+
+        if y is not None:
+            if hasattr(y, "to_numpy"):
+                y = y.to_numpy()
+            y_np = np.asarray(y).ravel()
+            self.y: torch.Tensor | None = torch.from_numpy(y_np.astype(np.int64))
+        else:
+            self.y = None
+
+    def __len__(self) -> int:
+        return int(self.X.shape[0])
+
+    def __getitem__(self, idx: int) -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]:
+        if self.y is None:
+            return self.X[idx]
+        return self.X[idx], self.y[idx]
+
+
+INPUT_TRANSFORMS = ("standardize", "log1p", "robust", "log1p+standardize", "none")
+
+
+def fit_input_transform(X_tr: np.ndarray, mode: str) -> dict[str, Any]:
+    """Compute per-bin statistics for the requested input-transform mode.
+
+    Fitted on the training split only to keep the pipeline leak-safe.
+    Returns a state dict that :func:`apply_input_transform` consumes
+    at training and inference time.
+
+    Supported modes:
+
+    - ``"none"``: identity; empty state.
+    - ``"standardize"``: per-bin ``(X - mean) / std`` from the train split.
+    - ``"log1p"``: element-wise ``log1p(clip(X, 0, None))``; stateless.
+    - ``"robust"``: per-bin ``(X - median) / IQR`` from the train split.
+      A zero IQR bin is treated as unit scale.
+    - ``"log1p+standardize"``: ``log1p`` first, then standardize.
+    """
+    if mode not in INPUT_TRANSFORMS:
+        raise ValueError(
+            f"Unknown input_transform={mode!r}; expected one of {INPUT_TRANSFORMS}."
+        )
+    state: dict[str, Any] = {"mode": mode}
+    if mode == "log1p+standardize":
+        X_fit = np.log1p(np.clip(X_tr, 0, None))
+    else:
+        X_fit = X_tr
+
+    if mode in {"standardize", "log1p+standardize"}:
+        state["mean"] = X_fit.mean(axis=0).astype(np.float32)
+        state["std"] = X_fit.std(axis=0).astype(np.float32)
+    elif mode == "robust":
+        state["median"] = np.median(X_fit, axis=0).astype(np.float32)
+        q75, q25 = np.percentile(X_fit, [75, 25], axis=0)
+        iqr = (q75 - q25).astype(np.float32)
+        state["iqr"] = np.maximum(iqr, _STD_FLOOR).astype(np.float32)
+    return state
+
+
+def apply_input_transform(X: np.ndarray, state: dict[str, Any]) -> np.ndarray:
+    """Apply a fitted :func:`fit_input_transform` state to ``X``."""
+    mode = state.get("mode", "none")
+    if mode == "none":
+        return X.astype(np.float32, copy=False)
+    if mode == "log1p":
+        return np.log1p(np.clip(X, 0, None)).astype(np.float32, copy=False)
+    if mode == "standardize":
+        mean = np.asarray(state["mean"], dtype=np.float32)
+        std = np.asarray(state["std"], dtype=np.float32)
+        safe_std = np.maximum(std, _STD_FLOOR).astype(np.float32)
+        return ((X - mean) / safe_std).astype(np.float32, copy=False)
+    if mode == "log1p+standardize":
+        logged = np.log1p(np.clip(X, 0, None))
+        mean = np.asarray(state["mean"], dtype=np.float32)
+        std = np.asarray(state["std"], dtype=np.float32)
+        safe_std = np.maximum(std, _STD_FLOOR).astype(np.float32)
+        return ((logged - mean) / safe_std).astype(np.float32, copy=False)
+    if mode == "robust":
+        median = np.asarray(state["median"], dtype=np.float32)
+        iqr = np.asarray(state["iqr"], dtype=np.float32)
+        return ((X - median) / iqr).astype(np.float32, copy=False)
+    raise ValueError(f"Unknown input_transform state mode={mode!r}.")
+
+
+def _warp_numpy(warper: Any, X_np: np.ndarray) -> np.ndarray:
+    """Apply a fitted warper to a numpy matrix, returning a numpy matrix."""
+    df = pd.DataFrame(X_np)
+    out = warper.transform(df)
+    if hasattr(out, "to_numpy"):
+        out = out.to_numpy()
+    return np.asarray(out, dtype=np.float32)
+
+
+def make_loaders(
+    X: Any,
+    y: Any,
+    *,
+    batch_size: int = 32,
+    val_size: float = 0.1,
+    random_state: int | None = 0,
+    standardize: bool = False,
+    input_transform: str | None = None,
+    stratify: bool = True,
+    num_workers: int = 0,
+    warper: Any | None = None,
+) -> tuple[DataLoader, DataLoader, dict[str, Any]]:
+    """Build stratified train / validation :class:`DataLoader` pairs.
+
+    Pipeline order, applied **after** the train/val split so nothing
+    from the validation split leaks into training statistics:
+
+    1. Spectral warping / alignment (if ``warper`` is given): fit on
+       the training split, then transform both splits.
+    2. Per-feature standardization (if ``standardize=True``): fit
+       mean/std on the (warped) training split, then apply to both
+       splits.
+
+    Parameters
+    ----------
+    X : array-like or MaldiSet
+        Feature matrix of shape ``(n_samples, n_bins)``.
+    y : array-like
+        Integer class labels of shape ``(n_samples,)``.
+    batch_size : int, default=32
+        Mini-batch size for the training loader.
+    val_size : float, default=0.1
+        Fraction of the input held out for validation.
+    random_state : int or None, default=0
+        Seed for the split.
+    standardize : bool, default=False
+        Shorthand for ``input_transform="standardize"`` (when True) or
+        ``input_transform="none"`` (when False). Kept for backwards
+        compatibility; the modern interface is ``input_transform``.
+        Ignored whenever ``input_transform`` is given explicitly.
+    input_transform : str, optional
+        One of ``{"none", "standardize", "log1p", "robust",
+        "log1p+standardize"}``. Fitted on the (warped) training split
+        only and applied to both splits. Overrides ``standardize``
+        when both are given.
+    stratify : bool, default=True
+        If ``True`` and all classes have at least two samples, stratify
+        the split on ``y``. Falls back to random split otherwise.
+    num_workers : int, default=0
+        ``DataLoader`` worker count.
+    warper : sklearn-style transformer, optional
+        Unfitted spectral-alignment transformer with ``fit(X) ->
+        self`` + ``transform(X) -> X``. Fitted on the training split
+        only and used to transform both splits. The fitted object is
+        returned in ``stats["warper"]``.
+
+    Returns
+    -------
+    train_loader : DataLoader
+        Shuffling training loader. Drops the last batch when it would
+        contain a single sample (avoids ``BatchNorm`` issues).
+    val_loader : DataLoader
+        Non-shuffling validation loader.
+    stats : dict
+        ``{"mean": array or None, "std": array or None, "warper":
+        fitted warper or None, "input_transform_state": dict}``.
+    """
+    X_np = _to_numpy(X)
+    if hasattr(y, "to_numpy"):
+        y = y.to_numpy()
+    y_np = np.asarray(y).ravel()
+
+    _, counts = np.unique(y_np, return_counts=True)
+    can_stratify = stratify and counts.min() >= 2
+
+    X_tr, X_val, y_tr, y_val = train_test_split(
+        X_np,
+        y_np,
+        test_size=val_size,
+        random_state=random_state,
+        stratify=y_np if can_stratify else None,
+    )
+
+    fitted_warper = None
+    if warper is not None:
+        fitted_warper = warper.fit(pd.DataFrame(X_tr))
+        X_tr = _warp_numpy(fitted_warper, X_tr)
+        X_val = _warp_numpy(fitted_warper, X_val)
+
+    if input_transform is None:
+        transform_mode = "standardize" if standardize else "none"
+    else:
+        transform_mode = input_transform
+    transform_state = fit_input_transform(X_tr, transform_mode)
+    X_tr = apply_input_transform(X_tr, transform_state)
+    X_val = apply_input_transform(X_val, transform_state)
+
+    mean = transform_state.get("mean")
+    std = transform_state.get("std")
+
+    train_ds = SpectralDataset(X_tr, y_tr, standardize=False)
+    val_ds = SpectralDataset(X_val, y_val, standardize=False)
+
+    drop_last = batch_size > 1 and (len(train_ds) % batch_size) == 1
+    train_loader = DataLoader(
+        train_ds,
+        batch_size=batch_size,
+        shuffle=True,
+        drop_last=drop_last,
+        num_workers=num_workers,
+    )
+    val_loader = DataLoader(
+        val_ds,
+        batch_size=batch_size,
+        shuffle=False,
+        drop_last=False,
+        num_workers=num_workers,
+    )
+    return (
+        train_loader,
+        val_loader,
+        {
+            "mean": mean,
+            "std": std,
+            "warper": fitted_warper,
+            "input_transform_state": transform_state,
+        },
+    )

maldideepkit/blocks.py

@@ -0,0 +1,39 @@
+"""One-stop import path for every MaldiDeepKit ``nn.Module`` primitive.
+
+Re-exports the full backbones and composable primitives under a single
+namespace so users embedding components into their own networks don't
+have to know the per-family layout.
+
+Examples
+--------
+>>> import torch
+>>> from maldideepkit.blocks import SpectralTransformer1D, TransformerBlock
+>>> backbone = SpectralTransformer1D(input_dim=6000, depth=6)
+>>> block = TransformerBlock(dim=128, num_heads=4)
+>>> tokens = torch.randn(2, 1500, 128)
+>>> out = block(tokens)           # (2, 1500, 128)
+"""
+
+from __future__ import annotations
+
+from ._blocks import DropPath, PatchEmbed1D
+from .attention.mlp import SpectralAttentionMLP
+from .cnn.cnn import SpectralCNN1D
+from .resnet.resnet import BasicBlock1D, SpectralResNet1D
+from .transformer.transformer import (
+    MultiHeadSelfAttention,
+    SpectralTransformer1D,
+    TransformerBlock,
+)
+
+__all__ = [
+    "SpectralAttentionMLP",
+    "SpectralCNN1D",
+    "SpectralResNet1D",
+    "BasicBlock1D",
+    "SpectralTransformer1D",
+    "TransformerBlock",
+    "MultiHeadSelfAttention",
+    "PatchEmbed1D",
+    "DropPath",
+]

maldideepkit/cnn/__init__.py

@@ -0,0 +1,5 @@
+"""1-D convolutional classifier for MALDI-TOF spectra."""
+
+from .cnn import MaldiCNNClassifier, SpectralCNN1D
+
+__all__ = ["MaldiCNNClassifier", "SpectralCNN1D"]

maldideepkit/cnn/cnn.py

@@ -0,0 +1,316 @@
+"""1-D convolutional classifier for binned MALDI-TOF spectra.
+
+A stack of ``Conv1d -> BatchNorm -> ReLU -> MaxPool`` blocks followed
+by a flatten + dense classification head.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Sequence
+
+import numpy as np
+import torch
+from torch import nn
+
+from .._bin_scaling import scale_odd_kernel
+from ..base.classifier import BaseSpectralClassifier
+
+
+def _broadcast(value: int | Sequence[int], n: int, name: str) -> tuple[int, ...]:
+    """Return a length-``n`` tuple: scalars are broadcast, sequences validated."""
+    if isinstance(value, int):
+        if value <= 0:
+            raise ValueError(f"{name} must be a positive integer; got {value}.")
+        return (value,) * n
+    out = tuple(int(v) for v in value)
+    if len(out) != n:
+        raise ValueError(
+            f"{name} has length {len(out)} but must have length {n} to match channels."
+        )
+    if any(v <= 0 for v in out):
+        raise ValueError(f"{name} must contain only positive integers; got {out}.")
+    return out
+
+
+class _ConvBlock(nn.Module):
+    """One Conv1D + BN + ReLU + MaxPool + Dropout block."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        kernel_size: int,
+        pool_size: int,
+        dropout: float,
+    ) -> None:
+        super().__init__()
+        padding = kernel_size // 2
+        self.block = nn.Sequential(
+            nn.Conv1d(in_channels, out_channels, kernel_size, padding=padding),
+            nn.BatchNorm1d(out_channels),
+            nn.ReLU(inplace=True),
+            nn.MaxPool1d(pool_size),
+            nn.Dropout(dropout),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.block(x)
+
+
+class SpectralCNN1D(nn.Module):
+    """Stack of Conv1D blocks with a dense classification head.
+
+    Parameters
+    ----------
+    input_dim : int
+        Number of input bins.
+    n_classes : int, default=2
+        Number of output logits.
+    channels : sequence of int, default=(32, 64, 128, 128)
+        Output channels of each convolutional block.
+    kernel_size : int or sequence of int, default=7
+        Kernel size per block. A scalar is broadcast to every block;
+        a sequence must have the same length as ``channels``.
+    pool_size : int or sequence of int, default=2
+        Pool factor per block. A scalar is broadcast to every block;
+        a sequence must have the same length as ``channels``.
+    head_dim : int, default=128
+        Width of the single hidden dense layer.
+    dropout : float, default=0.3
+        Dropout applied inside every block and before the output layer.
+
+    Notes
+    -----
+    Input tensors have shape ``(batch, input_dim)`` and are unsqueezed to
+    ``(batch, 1, input_dim)`` internally.
+    """
+
+    def __init__(
+        self,
+        input_dim: int,
+        n_classes: int = 2,
+        channels: tuple[int, ...] = (32, 64, 128, 128),
+        kernel_size: int | Sequence[int] = 7,
+        pool_size: int | Sequence[int] = 2,
+        head_dim: int = 128,
+        dropout: float = 0.3,
+    ) -> None:
+        super().__init__()
+        n_blocks = len(channels)
+        kernels = _broadcast(kernel_size, n_blocks, "kernel_size")
+        pools = _broadcast(pool_size, n_blocks, "pool_size")
+
+        blocks: list[nn.Module] = []
+        prev = 1
+        length = input_dim
+        for out_ch, k, p in zip(channels, kernels, pools, strict=True):
+            blocks.append(_ConvBlock(prev, out_ch, k, p, dropout))
+            prev = out_ch
+            length //= p
+            if length <= 0:
+                raise ValueError(
+                    f"input_dim={input_dim} is too small for the given pool "
+                    f"schedule {pools} (block {len(blocks)} would have 0 length)."
+                )
+        self.backbone = nn.Sequential(*blocks)
+        self.flat_dim = prev * length
+        self.head = nn.Sequential(
+            nn.Linear(self.flat_dim, head_dim),
+            nn.LayerNorm(head_dim),
+            nn.ReLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(head_dim, n_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Map ``(batch, input_dim)`` to ``(batch, n_classes)`` logits."""
+        x = x.unsqueeze(1)
+        feat = self.backbone(x)
+        return self.head(feat.flatten(1))
+
+
+class MaldiCNNClassifier(BaseSpectralClassifier):
+    """sklearn-compatible 1-D CNN classifier for MALDI-TOF spectra.
+
+    Parameters
+    ----------
+    channels : sequence of int, default=(32, 64, 128, 128)
+        Output channels of each convolutional block. The effective spatial
+        resolution is divided by the corresponding ``pool_size`` after
+        every block.
+    kernel_size : int or sequence of int, default=7
+        Kernel size per block. A scalar is broadcast; a sequence must
+        match the length of ``channels``. The default is calibrated for
+        ``bin_width=3``; :meth:`from_spectrum` scales it for other bin
+        widths.
+    pool_size : int or sequence of int, default=2
+        Pool factor per block. Accepts scalar or per-block sequence.
+    head_dim : int, default=128
+        Width of the hidden dense layer.
+    dropout : float, default=0.3
+        Dropout applied inside every block and before the output layer.
+    **kwargs
+        Forwarded to :class:`~maldideepkit.base.classifier.BaseSpectralClassifier`.
+
+    Notes
+    -----
+    The flat dense head scales linearly with ``input_dim``; prefer
+    :class:`~maldideepkit.MaldiResNetClassifier` or
+    :class:`~maldideepkit.MaldiTransformerClassifier` if you want
+    a head width that's independent of the input resolution.
+
+    See :func:`from_spectrum` for a factory that auto-scales
+    ``kernel_size`` for a given ``(bin_width, input_dim)`` layout.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from maldideepkit import MaldiCNNClassifier
+    >>> rng = np.random.default_rng(0)
+    >>> X = rng.standard_normal((32, 256)).astype("float32")
+    >>> y = rng.integers(0, 2, size=32)
+    >>> clf = MaldiCNNClassifier(epochs=2, batch_size=8, random_state=0).fit(X, y)
+    >>> clf.predict(X).shape
+    (32,)
+
+    Per-block kernel progression:
+
+    >>> clf = MaldiCNNClassifier(
+    ...     channels=(32, 64, 128, 128),
+    ...     kernel_size=(11, 7, 5, 3),
+    ... )
+    """
+
+    def __init__(
+        self,
+        input_dim: int | None = None,
+        n_classes: int = 2,
+        channels: tuple[int, ...] = (32, 64, 128, 128),
+        kernel_size: int | Sequence[int] = 7,
+        pool_size: int | Sequence[int] = 2,
+        head_dim: int = 128,
+        dropout: float = 0.3,
+        learning_rate: float = 1e-3,
+        weight_decay: float = 0.0,
+        grad_clip_norm: float | None = None,
+        label_smoothing: float = 0.0,
+        loss: str = "cross_entropy",
+        focal_gamma: float = 2.0,
+        use_amp: bool = False,
+        swa_start_epoch: int | None = None,
+        tune_threshold: bool = False,
+        threshold_metric: str = "balanced_accuracy",
+        calibrate_temperature: bool = False,
+        min_val_auroc_for_threshold_tune: float = 0.6,
+        use_sam: bool = False,
+        sam_rho: float = 0.05,
+        batch_size: int = 32,
+        epochs: int = 100,
+        early_stopping_patience: int = 10,
+        val_fraction: float = 0.1,
+        warmup_epochs: int = 0,
+        standardize: bool = False,
+        input_transform: str | None = None,
+        warping: Any | None = None,
+        metrics_log_path: str | Path | None = None,
+        track_train_metrics: bool = False,
+        augment: Any | None = None,
+        mixup_alpha: float = 0.0,
+        cutmix_alpha: float = 0.0,
+        ema_decay: float | None = None,
+        retry_on_val_auroc_below: float | None = None,
+        max_retries: int = 2,
+        class_weight: str | np.ndarray | list | None = None,
+        device: str | torch.device = "auto",
+        random_state: int = 0,
+        verbose: bool = False,
+    ) -> None:
+        super().__init__(
+            input_dim=input_dim,
+            n_classes=n_classes,
+            learning_rate=learning_rate,
+            weight_decay=weight_decay,
+            grad_clip_norm=grad_clip_norm,
+            label_smoothing=label_smoothing,
+            loss=loss,
+            focal_gamma=focal_gamma,
+            use_amp=use_amp,
+            swa_start_epoch=swa_start_epoch,
+            tune_threshold=tune_threshold,
+            threshold_metric=threshold_metric,
+            calibrate_temperature=calibrate_temperature,
+            min_val_auroc_for_threshold_tune=min_val_auroc_for_threshold_tune,
+            use_sam=use_sam,
+            sam_rho=sam_rho,
+            batch_size=batch_size,
+            epochs=epochs,
+            early_stopping_patience=early_stopping_patience,
+            val_fraction=val_fraction,
+            warmup_epochs=warmup_epochs,
+            standardize=standardize,
+            input_transform=input_transform,
+            warping=warping,
+            metrics_log_path=metrics_log_path,
+            track_train_metrics=track_train_metrics,
+            augment=augment,
+            mixup_alpha=mixup_alpha,
+            cutmix_alpha=cutmix_alpha,
+            ema_decay=ema_decay,
+            retry_on_val_auroc_below=retry_on_val_auroc_below,
+            max_retries=max_retries,
+            class_weight=class_weight,
+            device=device,
+            random_state=random_state,
+            verbose=verbose,
+        )
+        self.channels = channels
+        self.kernel_size = kernel_size
+        self.pool_size = pool_size
+        self.head_dim = head_dim
+        self.dropout = dropout
+
+    def _build_model(self) -> nn.Module:
+        return SpectralCNN1D(
+            input_dim=self.input_dim_,
+            n_classes=self.n_classes_,
+            channels=tuple(self.channels),
+            kernel_size=self.kernel_size,
+            pool_size=self.pool_size,
+            head_dim=int(self.head_dim),
+            dropout=float(self.dropout),
+        )
+
+    @classmethod
+    def from_spectrum(
+        cls, bin_width: int, input_dim: int, **overrides
+    ) -> "MaldiCNNClassifier":
+        """Construct a classifier with ``kernel_size`` scaled for ``bin_width``.
+
+        Scales ``kernel_size`` inversely with ``bin_width`` relative to
+        the package reference (``bin_width=3``, ``kernel_size=7``).
+        Any keyword in ``**overrides`` wins over the auto-scaled value.
+
+        Parameters
+        ----------
+        bin_width : int
+            Bin width in Daltons (e.g. 3 for the MaldiAMRKit default,
+            6 for coarser binning).
+        input_dim : int
+            Number of bins in the input. Stored on the classifier for
+            shape validation.
+        **overrides
+            Any additional keyword arguments override the scaled defaults.
+
+        Returns
+        -------
+        MaldiCNNClassifier
+            An unfitted estimator with ``kernel_size`` scaled for the
+            given ``bin_width``.
+        """
+        kwargs: dict[str, Any] = {
+            "input_dim": input_dim,
+            "kernel_size": scale_odd_kernel(bin_width),
+        }
+        kwargs.update(overrides)
+        return cls(**kwargs)

maldideepkit/resnet/__init__.py

@@ -0,0 +1,5 @@
+"""1-D ResNet classifier for MALDI-TOF spectra."""
+
+from .resnet import MaldiResNetClassifier, SpectralResNet1D
+
+__all__ = ["MaldiResNetClassifier", "SpectralResNet1D"]