MaldiBatchKit 0.2.0__tar.gz → 0.2.1__tar.gz

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1/MaldiBatchKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiBatchKit
-Version: 0.2.0
+Version: 0.2.1
 Summary: Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -27,7 +27,7 @@ Requires-Dist: pandas>=1.3.0
 Requires-Dist: scipy>=1.13.0
 Requires-Dist: scikit-learn>=1.6.0
 Requires-Dist: matplotlib>=3.4.0
-Requires-Dist: combatlearn>=2.0.0
+Requires-Dist: combatlearn>=2.4.0
 Requires-Dist: harmonypy<2,>=0.2.0
 Requires-Dist: maldiamrkit>=0.15.0
 Requires-Dist: typer>=0.9.0
@@ -69,6 +69,10 @@ Dynamic: license-file
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="docs/batch_correction.svg" alt="Animated scatter plot: before correction MALDI-TOF samples cluster by acquisition site; after MaldiBatchKit the site effect is removed and samples cluster by species" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
@@ -212,7 +216,7 @@ maldibatchkit correct combat-fortin \
     -o corrected.npz
 ```
 
-Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` / `combat-chen` refuse to run without covariates (they would silently reduce to Johnson ComBat); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
+Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` refuses to run without covariates (it would silently reduce to Johnson ComBat); `combat-chen` without covariates is plain CovBat (Johnson ComBat plus the covariance correction); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
 
 ## Algorithms
 
@@ -220,7 +224,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | ComBat (Johnson, Fortin, Chen) | `ComBat`                  | Fortin / Chen        | yes              |
 | Limma                          | `Limma`                   | via `design=`        | yes              |
-| Harmony                        | `Harmony`                 | via `covariates=`    | yes              |
+| Harmony                        | `Harmony`                 | no (removes them)    | yes              |
 | Median centering               | `MedianCentering`         | no                   | yes              |
 | Z-score per batch              | `ZScorePerBatch`          | no                   | yes              |
 | Reference scaling              | `ReferenceScaling`        | no                   | yes              |

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/MaldiBatchKit.egg-info/requires.txt

@@ -3,7 +3,7 @@ pandas>=1.3.0
 scipy>=1.13.0
 scikit-learn>=1.6.0
 matplotlib>=3.4.0
-combatlearn>=2.0.0
+combatlearn>=2.4.0
 harmonypy<2,>=0.2.0
 maldiamrkit>=0.15.0
 typer>=0.9.0

{maldibatchkit-0.2.0/MaldiBatchKit.egg-info → maldibatchkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiBatchKit
-Version: 0.2.0
+Version: 0.2.1
 Summary: Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -27,7 +27,7 @@ Requires-Dist: pandas>=1.3.0
 Requires-Dist: scipy>=1.13.0
 Requires-Dist: scikit-learn>=1.6.0
 Requires-Dist: matplotlib>=3.4.0
-Requires-Dist: combatlearn>=2.0.0
+Requires-Dist: combatlearn>=2.4.0
 Requires-Dist: harmonypy<2,>=0.2.0
 Requires-Dist: maldiamrkit>=0.15.0
 Requires-Dist: typer>=0.9.0
@@ -69,6 +69,10 @@ Dynamic: license-file
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="docs/batch_correction.svg" alt="Animated scatter plot: before correction MALDI-TOF samples cluster by acquisition site; after MaldiBatchKit the site effect is removed and samples cluster by species" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
@@ -212,7 +216,7 @@ maldibatchkit correct combat-fortin \
     -o corrected.npz
 ```
 
-Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` / `combat-chen` refuse to run without covariates (they would silently reduce to Johnson ComBat); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
+Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` refuses to run without covariates (it would silently reduce to Johnson ComBat); `combat-chen` without covariates is plain CovBat (Johnson ComBat plus the covariance correction); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
 
 ## Algorithms
 
@@ -220,7 +224,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | ComBat (Johnson, Fortin, Chen) | `ComBat`                  | Fortin / Chen        | yes              |
 | Limma                          | `Limma`                   | via `design=`        | yes              |
-| Harmony                        | `Harmony`                 | via `covariates=`    | yes              |
+| Harmony                        | `Harmony`                 | no (removes them)    | yes              |
 | Median centering               | `MedianCentering`         | no                   | yes              |
 | Z-score per batch              | `ZScorePerBatch`          | no                   | yes              |
 | Reference scaling              | `ReferenceScaling`        | no                   | yes              |

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/README.md

@@ -16,6 +16,10 @@
   <strong>Batch-effect correction methods for MALDI-TOF spectra in clinical AMR prediction workflows</strong>
 </p>
 
+<p align="center">
+  <img src="docs/batch_correction.svg" alt="Animated scatter plot: before correction MALDI-TOF samples cluster by acquisition site; after MaldiBatchKit the site effect is removed and samples cluster by species" width="720"/>
+</p>
+
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#features">Features</a> •
@@ -159,7 +163,7 @@ maldibatchkit correct combat-fortin \
     -o corrected.npz
 ```
 
-Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` / `combat-chen` refuse to run without covariates (they would silently reduce to Johnson ComBat); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
+Run `maldibatchkit correct <method> --help` for the full flag list of any corrector. `combat-fortin` refuses to run without covariates (it would silently reduce to Johnson ComBat); `combat-chen` without covariates is plain CovBat (Johnson ComBat plus the covariance correction); `species-combat` / `quality-combat` require their dedicated `--species-csv` / `--quality-csv` inputs.
 
 ## Algorithms
 
@@ -167,7 +171,7 @@ Run `maldibatchkit correct <method> --help` for the full flag list of any correc
 |--------------------------------|---------------------------|----------------------|------------------|
 | ComBat (Johnson, Fortin, Chen) | `ComBat`                  | Fortin / Chen        | yes              |
 | Limma                          | `Limma`                   | via `design=`        | yes              |
-| Harmony                        | `Harmony`                 | via `covariates=`    | yes              |
+| Harmony                        | `Harmony`                 | no (removes them)    | yes              |
 | Median centering               | `MedianCentering`         | no                   | yes              |
 | Z-score per batch              | `ZScorePerBatch`          | no                   | yes              |
 | Reference scaling              | `ReferenceScaling`        | no                   | yes              |

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/maldibatchkit/__init__.py

@@ -58,7 +58,7 @@ from .metrics import (
     make_batch_scorer,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 __author__ = "Ettore Rocchi"
 
 __all__ = [

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/maldibatchkit/_base.py

@@ -27,7 +27,14 @@ import pandas as pd
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_array, check_is_fitted
 
-from ._utils import ArrayLike, _ensure_index, _subset
+from ._utils import (
+    ArrayLike,
+    _check_label_values,
+    _check_positional_alignment,
+    _check_unique_ids,
+    _ensure_index,
+    _subset,
+)
 
 
 def _check_array_finite(X: Any) -> None:
@@ -65,6 +72,8 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
     :meth:`get_params` / :meth:`set_params` work.
     """
 
+    _sample_aligned_params: tuple[str, ...] = ("batch",)
+
     def __init__(self, batch: ArrayLike) -> None:
         self.batch = batch
 
@@ -72,6 +81,13 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
         """Validate the feature matrix."""
         _check_array_finite(X)
 
+    def _check_sample_alignment(self, X: ArrayLike) -> None:
+        """Reject pandas per-sample inputs that an ndarray ``X`` cannot match."""
+        if isinstance(X, pd.DataFrame | pd.Series):
+            return
+        for name in self._sample_aligned_params:
+            _check_positional_alignment(getattr(self, name, None), len(X), name)
+
     def _prepare_fit(
         self, X: ArrayLike
     ) -> tuple[pd.DataFrame, npt.NDArray[Any], pd.Index]:
@@ -87,7 +103,10 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
             The shared index used by ``X`` and ``batch``.
         """
         self._validate_X(X)
+        self._check_sample_alignment(X)
         idx = _ensure_index(X)
+        _check_unique_ids(idx, "X")
+        self._fitted_on_frame_ = isinstance(X, pd.DataFrame)
         if isinstance(X, pd.DataFrame):
             self.feature_names_in_ = np.asarray(X.columns, dtype=object)
             X_df = X
@@ -104,11 +123,7 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
                 raise ValueError(f"`batch` must be 1-D; got shape {batch_vec.shape}.")
             batch_vec = batch_vec.iloc[:, 0]
         batch_ser = pd.Series(batch_vec, index=idx)
-        if batch_ser.isna().any():
-            raise ValueError(
-                f"batch contains {int(batch_ser.isna().sum())} NaN value(s); "
-                f"all batch labels must be non-null."
-            )
+        _check_label_values(batch_ser, "batch")
         return X_df, batch_ser.to_numpy(), idx
 
     def _prepare_transform(
@@ -117,13 +132,32 @@ class BaseBatchCorrector(BaseEstimator, TransformerMixin):  # type: ignore[misc]
         """Run common ``transform``-time bookkeeping."""
         check_is_fitted(self)
         self._validate_X(X)
+        self._check_sample_alignment(X)
         idx = _ensure_index(X)
+        _check_unique_ids(idx, "X")
         was_df = isinstance(X, pd.DataFrame)
         X_df = X if was_df else pd.DataFrame(np.asarray(X), index=idx)
+        if X_df.shape[1] != self.n_features_in_:
+            raise ValueError(
+                f"X has {X_df.shape[1]} features, but {type(self).__name__} "
+                f"is expecting {self.n_features_in_} features as input."
+            )
+        if (
+            was_df
+            and getattr(self, "_fitted_on_frame_", False)
+            and not np.array_equal(
+                np.asarray(X.columns, dtype=object), self.feature_names_in_
+            )
+        ):
+            raise ValueError(
+                "The feature names should match those that were passed during "
+                "fit, in the same order."
+            )
         batch_vec = _subset(self.batch, idx)
         if isinstance(batch_vec, pd.DataFrame):
             batch_vec = batch_vec.iloc[:, 0]
         batch_ser = pd.Series(batch_vec, index=idx)
+        _check_label_values(batch_ser, "batch")
         return X_df, batch_ser.to_numpy(), idx, was_df
 
     def _fit_impl(

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/maldibatchkit/_cli_io.py

@@ -13,20 +13,25 @@ Supported input / output containers
   ``columns``, ``index``, ``batch``, and arbitrary extra arrays kept as
   passthrough metadata.  This is the MaldiSet-friendly format.
 
-All auxiliary loaders align the loaded object to ``X.index`` via
-``.reindex`` when an index is available in the CSV, or positionally
-otherwise.
+All auxiliary loaders align the loaded object to ``X.index`` by sample
+ID and fail, listing the missing IDs, when the sidecar does not cover
+``X.index``. Sample IDs and labels are read as strings (``"001"`` stays
+``"001"`` and ``"NA"`` is a label, not a missing value).
 """
 
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 
 import numpy as np
 import pandas as pd
 import typer
 
+from ._utils import _check_unique_ids
+
 __all__ = [
+    "load_features",
     "load_matrix",
     "load_dataframe_csv",
     "load_labels_csv",
@@ -35,9 +40,41 @@ __all__ = [
 ]
 
 
-def _read_csv_indexed(path: Path) -> pd.DataFrame:
-    """Read a CSV assuming the first column is the sample index."""
-    return pd.read_csv(path, index_col=0)
+def _read_csv_indexed(path: Path, **kwargs: Any) -> pd.DataFrame:
+    """Read a CSV whose first column holds the sample IDs, kept as strings."""
+    df = pd.read_csv(path, index_col=0, **kwargs)
+    ids = pd.read_csv(path, usecols=[0], dtype=str, keep_default_na=False)
+    df.index = pd.Index(ids.iloc[:, 0].to_numpy(), name=df.index.name)
+    return df
+
+
+def _load_npz(path: Path) -> tuple[pd.DataFrame, pd.Series | None, dict]:
+    """Return ``X``, the bundled batch (or None) and the extra arrays of an NPZ."""
+    with np.load(path, allow_pickle=True) as npz:
+        if "X" not in npz.files:
+            raise typer.BadParameter(
+                f"{path} is missing the 'X' array. Expected "
+                f"np.savez(..., X=, [columns=, index=, batch=])."
+            )
+        X_arr = np.asarray(npz["X"])
+        columns = list(npz["columns"]) if "columns" in npz.files else None
+        index = list(npz["index"]) if "index" in npz.files else None
+        npz_batch = (
+            pd.Series(np.asarray(npz["batch"])) if "batch" in npz.files else None
+        )
+        extras = {
+            k: np.asarray(npz[k])
+            for k in npz.files
+            if k not in {"X", "columns", "index", "batch"}
+        }
+    return pd.DataFrame(X_arr, index=index, columns=columns), npz_batch, extras
+
+
+def load_features(path: Path) -> pd.DataFrame:
+    """Load only the feature matrix of a CSV or NPZ file."""
+    if path.suffix.lower() == ".npz":
+        return _load_npz(path)[0]
+    return _read_csv_indexed(path)
 
 
 def load_matrix(
@@ -65,24 +102,7 @@ def load_matrix(
         columns / batch).  Empty for CSV inputs.
     """
     if path.suffix.lower() == ".npz":
-        with np.load(path, allow_pickle=True) as npz:
-            if "X" not in npz.files:
-                raise typer.BadParameter(
-                    f"{path} is missing the 'X' array. Expected "
-                    f"np.savez(..., X=, [columns=, index=, batch=])."
-                )
-            X_arr = np.asarray(npz["X"])
-            columns = list(npz["columns"]) if "columns" in npz.files else None
-            index = list(npz["index"]) if "index" in npz.files else None
-            npz_batch = (
-                pd.Series(np.asarray(npz["batch"])) if "batch" in npz.files else None
-            )
-            extras = {
-                k: np.asarray(npz[k])
-                for k in npz.files
-                if k not in {"X", "columns", "index", "batch"}
-            }
-        X = pd.DataFrame(X_arr, index=index, columns=columns)
+        X, npz_batch, extras = _load_npz(path)
         if npz_batch is not None:
             if len(npz_batch) != len(X):
                 raise typer.BadParameter(
@@ -98,7 +118,6 @@ def load_matrix(
             batch = load_labels_csv(batch_csv, X.index)
         return X, batch, extras
 
-    # CSV path
     X = _read_csv_indexed(path)
     if batch_csv is None:
         raise typer.BadParameter(
@@ -112,15 +131,11 @@ def load_matrix(
 def load_labels_csv(path: Path, index: pd.Index) -> pd.Series:
     """Load a single-column sidecar CSV as a Series aligned to ``index``.
 
-    The CSV's first column is interpreted as the sample index; the
-    second column is the label value. If the CSV has no explicit sample
-    index (i.e. a single data column read with the default
-    ``RangeIndex``), the labels are assumed to already be in ``X`` order
-    and are aligned positionally.
+    The CSV's first column is the sample ID and the second the label, both
+    read as strings.
     """
-    df = pd.read_csv(path, index_col=0)
+    df = _read_csv_indexed(path, dtype=str, keep_default_na=False)
     if df.shape[1] == 0:
-        # Only an index column was present -> data is the index itself
         raise typer.BadParameter(
             f"{path} has no data columns. Expected <sample_id>,<label>."
         )
@@ -134,9 +149,26 @@ def load_labels_csv(path: Path, index: pd.Index) -> pd.Series:
     return _align_series(series, index, source=path)
 
 
-def load_dataframe_csv(path: Path, index: pd.Index) -> pd.DataFrame:
-    """Load a multi-column sidecar CSV and align it to ``index``."""
-    df = pd.read_csv(path, index_col=0)
+def load_dataframe_csv(
+    path: Path, index: pd.Index, *, categorical: bool = False
+) -> pd.DataFrame:
+    """Load a multi-column sidecar CSV and align it to ``index``.
+
+    Parameters
+    ----------
+    path : Path
+        CSV whose first column holds the sample IDs.
+    index : pd.Index
+        ``X.index`` to align to.
+    categorical : bool, default=False
+        Read the values as strings (labels such as ``"NA"`` or ``"001"``
+        are kept as written); otherwise they are parsed as numbers.
+    """
+    df = (
+        _read_csv_indexed(path, dtype=str, keep_default_na=False)
+        if categorical
+        else _read_csv_indexed(path)
+    )
     if df.shape[1] == 0:
         raise typer.BadParameter(f"{path} has no data columns.")
     return _align_frame(df, index, source=path)
@@ -180,32 +212,33 @@ def save_matrix(
         X.to_csv(path)
 
 
+def _align_by_id(obj, index: pd.Index, *, source: Path):
+    """Reindex ``obj`` onto ``index`` by sample ID (compared as strings)."""
+    if obj.index.equals(index):
+        return obj
+    keys = pd.Index(index).astype(str)
+    if obj.index.name is not None and str(obj.index.name) in keys:
+        raise typer.BadParameter(
+            f"{source} has no header row: its first line starts with sample ID "
+            f"{obj.index.name!r}. Add a header such as 'id,label'."
+        )
+    try:
+        _check_unique_ids(obj.index, str(source))
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    by_id = obj.set_axis(obj.index.astype(str), axis=0)
+    missing = keys[~keys.isin(by_id.index)]
+    if len(missing):
+        raise typer.BadParameter(
+            f"{source}: cannot align to X.index; {len(missing)} sample ID(s) "
+            f"of X are missing (first 5: {list(missing[:5])})."
+        )
+    return by_id.reindex(keys).set_axis(index, axis=0)
+
+
 def _align_series(series: pd.Series, index: pd.Index, *, source: Path) -> pd.Series:
-    if series.index.equals(index):
-        return series
-    if set(index).issubset(set(series.index)):
-        return series.reindex(index)
-    if len(series) == len(index):
-        # Positional fallback: the CSV did not carry the X sample IDs.
-        aligned = series.copy()
-        aligned.index = index
-        return aligned
-    raise typer.BadParameter(
-        f"{source}: cannot align labels to X.index. "
-        f"Labels have {len(series)} rows, X has {len(index)} rows, "
-        f"and label indices do not cover X.index."
-    )
+    return _align_by_id(series, index, source=source)
 
 
 def _align_frame(df: pd.DataFrame, index: pd.Index, *, source: Path) -> pd.DataFrame:
-    if df.index.equals(index):
-        return df
-    if set(index).issubset(set(df.index)):
-        return df.reindex(index)
-    if len(df) == len(index):
-        aligned = df.copy()
-        aligned.index = index
-        return aligned
-    raise typer.BadParameter(
-        f"{source}: cannot align to X.index. Got {len(df)} rows, X has {len(index)}."
-    )
+    return _align_by_id(df, index, source=source)

{maldibatchkit-0.2.0 → maldibatchkit-0.2.1}/maldibatchkit/_utils.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from typing import Any
 
 import numpy as np
@@ -45,6 +46,7 @@ def _subset(obj: ArrayLike | None, idx: pd.Index) -> pd.Series | pd.DataFrame |
     if obj is None:
         return None
     if isinstance(obj, pd.Series | pd.DataFrame):
+        _check_unique_ids(obj.index, "batch/covariate index")
         try:
             return obj.loc[idx]
         except KeyError as exc:
@@ -62,6 +64,79 @@ def _subset(obj: ArrayLike | None, idx: pd.Index) -> pd.Series | pd.DataFrame |
     return pd.DataFrame(arr, index=idx)
 
 
+def _check_positional_alignment(obj: ArrayLike | None, n_rows: int, name: str) -> None:
+    """Raise if pandas ``obj`` is not indexed by ``RangeIndex(n_rows)``."""
+    if isinstance(obj, pd.Series | pd.DataFrame) and not obj.index.equals(
+        pd.RangeIndex(n_rows)
+    ):
+        raise ValueError(
+            f"`{name}` is a pandas object but X is an ndarray with no index, "
+            f"and `{name}`'s index is not RangeIndex({n_rows}), so its rows "
+            f"cannot be matched to X. Pass X as a DataFrame (in a Pipeline, "
+            f'call `set_output(transform="pandas")` on the previous steps) or '
+            f"pass `{name}` as a numpy array in the same row order as X."
+        )
+
+
+def _warn_unscaled(n_pairs: int, eps: float) -> None:
+    """Warn that ``n_pairs`` (batch, feature) scales <= ``eps`` are left unscaled."""
+    if n_pairs:
+        warnings.warn(
+            f"{n_pairs} (batch, feature) pair(s) have a training scale <= "
+            f"eps={eps:g} (e.g. a bin that is all zero in a batch); they are "
+            f"left unscaled.",
+            stacklevel=4,
+        )
+
+
+def _check_labels(labels: ArrayLike, n_rows: int, name: str) -> npt.NDArray[Any]:
+    """Return ``labels`` as a 1-D array of ``n_rows`` non-missing values or raise."""
+    arr = np.asarray(labels)
+    if arr.ndim != 1 or arr.shape[0] != n_rows:
+        raise ValueError(
+            f"`{name}` must hold one label per row of X ({n_rows}); got shape "
+            f"{arr.shape}."
+        )
+    _check_label_values(arr, name)
+    return arr
+
+
+def _check_label_values(values: ArrayLike, name: str) -> None:
+    """Raise on missing labels or labels mixing strings and non-strings."""
+    arr = np.asarray(values, dtype=object)
+    n_missing = int(pd.isna(arr).sum())
+    if n_missing:
+        raise ValueError(f"`{name}` contains {n_missing} missing (NaN) label(s).")
+    is_str = np.array([isinstance(v, str) for v in arr])
+    if is_str.any() and not is_str.all():
+        raise ValueError(
+            f"`{name}` mixes string and non-string labels (e.g. 1 and '1'); "
+            f"use one type for all labels."
+        )
+
+
+def _check_unique_ids(index: pd.Index, what: str) -> None:
+    """Raise if ``index`` holds duplicated sample IDs."""
+    if index.has_duplicates:
+        dup = index[index.duplicated()].unique().tolist()
+        raise ValueError(
+            f"{what} has duplicated sample ID(s) (first 3: {dup[:3]}); sample "
+            f"IDs must be unique."
+        )
+
+
+def _check_min_batch_size(batch: ArrayLike) -> None:
+    """Raise if any batch has fewer than 2 samples."""
+    counts = pd.Series(np.asarray(batch)).value_counts()
+    small = counts[counts < 2]
+    if len(small):
+        raise ValueError(
+            f"Batch {small.index[0]!r} has only {int(small.iloc[0])} sample(s). "
+            f"ComBat requires >= 2 samples per batch. Consider merging small "
+            f"batches or removing them."
+        )
+
+
 def _ensure_index(X: ArrayLike) -> pd.Index:
     """Return ``X.index`` if ``X`` is a pandas object, else a default RangeIndex."""
     if isinstance(X, pd.DataFrame | pd.Series):
@@ -99,13 +174,15 @@ def _resolve_mz_axis(
     n_features = df.shape[1]
     if mz_values is not None:
         mz = np.asarray(mz_values, dtype=float)
+        if mz.ndim != 1:
+            raise ValueError(f"mz_values must be 1-D; got shape {mz.shape}.")
+        if not np.isfinite(mz).all():
+            raise ValueError("mz_values must be finite (no NaN or inf).")
         if mz.shape[0] != n_features:
             raise ValueError(
                 f"mz_values has length {mz.shape[0]} but X has {n_features} columns."
             )
         return mz, True
-    # pandas.DataFrame(ndarray) yields a default RangeIndex(0, n) -
-    # that is positional, not an m/z axis. Treat it as bin indices.
     if isinstance(df.columns, pd.RangeIndex):
         return np.arange(n_features, dtype=float), False
     try:
@@ -114,9 +191,6 @@ def _resolve_mz_axis(
         return np.arange(n_features, dtype=float), False
     if np.any(np.isnan(mz)):
         return np.arange(n_features, dtype=float), False
-    # If the coerced axis is exactly ``[0, 1, ..., n-1]`` it is an
-    # integer-labelled DataFrame that happens to parse as floats;
-    # the caller almost certainly did not mean those as m/z.
     if np.array_equal(mz, np.arange(n_features, dtype=float)):
         return mz, False
     return mz, True