preorder4mlc 1.0.0__py3-none-any.whl

preorder4mlc/__init__.py

@@ -0,0 +1,4 @@
+"""Pre-order based multi-label classification (preorder4MLC).
+
+Library package. CLI entry points live under ``scripts/``.
+"""

preorder4mlc/base_classifiers.py

@@ -0,0 +1,242 @@
+"""Pairwise- and calibrated-classifier factories.
+
+:class:`BaseClassifiers` builds the per-pair training datasets that
+:class:`inference_models.PredictBOPOs` consumes: pairwise classifiers for
+PRE_ORDER and PARTIAL_ORDER variants, and one calibrated classifier per
+label for CLR. Estimator construction is delegated to
+:class:`estimator.Estimator`, with fitting parallelised via joblib.
+"""
+
+from logging import INFO, log
+
+import numpy as np
+from joblib import Parallel, delayed
+from numpy.typing import NDArray
+from sklearn.base import BaseEstimator
+
+from preorder4mlc.estimator import Estimator, train_classifier
+
+
+class BaseClassifiers:
+    """Base classifiers for multi-label classification with different order types.
+
+    Attributes:
+        base_learner (Estimator): The base learning algorithm
+        logger (logging.Logger): Logger instance
+    """
+
+    def __init__(self, name: str):
+        log(
+            INFO,
+            f"BaseClassifiers: Initializing base learner: {name}",
+        )
+        self.name = name
+
+    def get_classifier(self) -> BaseEstimator:
+        return Estimator(self.name).get_classifier()  # type: ignore
+
+    def pairwise_calibrated_classifier(self, X: NDArray[np.float64], Y: NDArray[np.int32]):
+        """Train pairwise calibrated classifiers.
+
+        Args:
+            X: Input features of shape (n_samples, n_features)
+            Y: Binary label matrix of shape (n_samples, n_labels)
+
+            X_train = [[1, 2, 3, 0], [3, 2, 4, 1], [4, 5, 3, 3], [7, 6, 3, 1]]
+            Y_train = [[1, 1, 0], [0, 1, 0], [1, 0, 0], [0, 0, 1]]
+            n_labels = 3
+
+        Returns:
+            Tuple containing:
+                - Dictionary of pairwise classifiers
+                - List of calibrated classifiers
+        """
+        n_instances, n_labels = Y.shape
+
+        # calibrated_classifiers is in fact is a (inverse) BR classifier
+        calibrated_classifiers = []
+        clr_dataset_classifier = {}
+        for k in range(n_labels):
+            # MCC = score for class 0; invert the label column so the trained
+            # classifier produces P(y_k = 0) directly (CLR convention).
+            # Example: Y[:, k] = [1, 0, 1, 0] -> MCC_y = [0, 1, 0, 1].
+            MCC_y = np.logical_not(Y[:, k]).astype(int)
+            clr_dataset_classifier[str(k)] = {  # type: ignore
+                "X": X,
+                "Y": MCC_y,
+            }
+
+        log(
+            INFO,
+            f"\t - Training for {len(clr_dataset_classifier.keys())} calibrated_classifiers with {self.name}",
+        )
+        # run fit in parallel for each pair of labels
+        classifiers = Parallel(n_jobs=-1)(
+            delayed(train_classifier)(
+                clr_dataset_classifier[str(k)]["X"],
+                clr_dataset_classifier[str(k)]["Y"],
+                self.name,
+            )  # type: ignore
+            for k in range(n_labels)
+        )
+        log(INFO, f"\t - Trained {n_labels} classifiers")
+
+        calibrated_classifiers = list(classifiers)
+
+        pairwise_classifiers = {}
+        single_label_pair = {}
+        dataset_classifier = {}
+        for i in range(n_labels - 1):
+            for j in range(i + 1, n_labels):
+                key = f"{i}_{j}"
+                MCC_X = []
+                MCC_y = []
+
+                for n in range(n_instances):
+                    if Y[n, i] == 1 and Y[n, j] == 0:
+                        MCC_X.append(X[n])
+                        MCC_y.append(0)
+                    elif Y[n, i] == 0 and Y[n, j] == 1:
+                        MCC_X.append(X[n])
+                        MCC_y.append(1)
+
+                dataset_classifier[key] = {  # type: ignore
+                    "X": MCC_X,
+                    "Y": MCC_y,
+                }
+
+        log(
+            INFO,
+            f"\t - Training for {len(dataset_classifier.keys())} pairs with {self.name}",
+        )
+
+        # Skip degenerate pairs (empty, single-sample, or single-class). LGBM
+        # rejects single-sample fits and any single-class fit; RF tolerates
+        # single-sample but not single-class. downstream predict_CLR guards
+        # against missing keys.
+        trainable_keys = [
+            k for k in dataset_classifier.keys()
+            if len(dataset_classifier[k]["Y"]) >= 2
+            and len(set(dataset_classifier[k]["Y"])) >= 2
+        ]
+        skipped = len(dataset_classifier) - len(trainable_keys)
+        if skipped:
+            log(INFO, f"\t - Skipping {skipped} empty pairs (degenerate fold)")
+
+        classifiers = Parallel(n_jobs=-1)(
+            delayed(train_classifier)(
+                dataset_classifier[key]["X"],
+                dataset_classifier[key]["Y"],
+                self.name,
+            )  # type: ignore
+            for key in trainable_keys
+        )
+
+        log(INFO, f"\t - Trained {len(trainable_keys)} classifiers")
+
+        pairwise_classifiers = dict(zip(trainable_keys, classifiers))  # type: ignore
+
+        for i in range(n_labels - 1):
+            for j in range(i + 1, n_labels):
+                key = f"{i}_{j}"
+                MCC_y = dataset_classifier[key]["Y"]
+                single_label_pair[key] = (
+                    1
+                    if len(np.unique(MCC_y)) == 1 and np.unique(MCC_y)[0] == 1
+                    else (0 if len(np.unique(MCC_y)) == 1 and np.unique(MCC_y)[0] == 0 else None)
+                )
+
+        return pairwise_classifiers, calibrated_classifiers, single_label_pair
+
+    def pairwise_partial_order_classifier_fit(self, X, Y):
+        # This BaseClassifier provides pairwise_probability_information for learning partial orders
+        n_labels = len(Y[0])
+        n_instances, _ = Y.shape
+        dataset_classifier = {}
+        pairwise_classifiers = {}
+
+        for i in range(n_labels - 1):
+            for j in range(i + 1, n_labels):
+                key = f"{i}_{j}"
+                MCC_y = []
+                for n in range(n_instances):
+                    if Y[n, i] == Y[n, j]:
+                        MCC_y.append(2)
+                    elif Y[n, i] == 1 and Y[n, j] == 0:
+                        MCC_y.append(0)
+                    elif Y[n, i] == 0 and Y[n, j] == 1:
+                        MCC_y.append(1)
+                # X is read-only input for sklearn/LightGBM fit; share the
+                # reference across pairs instead of copying. For K=101 (mediamill)
+                # that's 5050 copies of a 42 MB array (~212 GB) avoided.
+                dataset_classifier[key] = {  # type: ignore
+                    "X": X,
+                    "Y": MCC_y,
+                }
+        log(
+            INFO,
+            f"\t - Training for {len(dataset_classifier.keys())} pairs with {self.name}",
+        )
+        # run fit in parallel for each pair of labels
+        classifiers = Parallel(n_jobs=-1)(
+            delayed(train_classifier)(
+                dataset_classifier[key]["X"],
+                dataset_classifier[key]["Y"],
+                self.name,
+            )  # type: ignore
+            for key in dataset_classifier.keys()
+        )
+        log(INFO, f"\t - Trained {len(dataset_classifier.keys())} classifiers")
+
+        pairwise_classifiers = dict(zip(dataset_classifier.keys(), classifiers))  # type: ignore
+
+        return pairwise_classifiers  # type: ignore
+
+    def pairwise_pre_order_classifier_fit(self, X, Y) -> dict[str, Estimator]:
+        """
+        This BaseClassifier provides pairwise_probability_information for learning preorders
+        For each pair of labels, we will train a classifier to predict the probability of the label
+        """
+        n_instances, n_labels = Y.shape
+        log(INFO, f"\t - {n_labels} labels with {self.name}")
+        dataset_classifier = {}
+        for i in range(n_labels - 1):
+            for j in range(i + 1, n_labels):
+                key = f"{i}_{j}"
+                MCC_y = []
+                for n in range(n_instances):
+                    if Y[n, i] == 0 and Y[n, j] == 0:
+                        MCC_y.append(2)
+                    elif Y[n, i] == 1 and Y[n, j] == 1:
+                        MCC_y.append(3)
+                    elif Y[n, i] == 1 and Y[n, j] == 0:
+                        MCC_y.append(0)
+                    elif Y[n, i] == 0 and Y[n, j] == 1:
+                        MCC_y.append(1)
+
+                # X is read-only input for sklearn/LightGBM fit; share the
+                # reference across pairs instead of copying.
+                dataset_classifier[key] = {  # type: ignore
+                    "X": X,
+                    "Y": MCC_y,
+                }
+        log(
+            INFO,
+            f"\t - Training {len(dataset_classifier.keys())} pairs with {self.name}",
+        )
+        # run fit in parallel for each pair of labels
+        classifiers = Parallel(n_jobs=-1)(
+            delayed(train_classifier)(
+                dataset_classifier[key]["X"],
+                dataset_classifier[key]["Y"],
+                self.name,
+            )  # type: ignore
+            for key in dataset_classifier.keys()
+        )
+        log(INFO, f"\t - Trained {len(dataset_classifier.keys())} classifiers")
+
+        pairwise_classifiers = dict(zip(dataset_classifier.keys(), classifiers))  # type: ignore
+
+        # This is a dictionary of pairwise classifiers. [key] is a string of the form "i_j"
+        # where i and j are the indices of the labels in the label matrix Y
+        return pairwise_classifiers  # type: ignore

preorder4mlc/config.py

@@ -0,0 +1,115 @@
+"""Run configuration for the BOPOs training pipeline.
+
+Defines the typed config dataclasses (:class:`DatasetConfig`,
+:class:`TrainingConfig`) and the per-run :class:`ConfigManager` factory
+that maps a dataset key from the command line to its ARFF location, the
+target label count, and the fixed list of noisy rates / base learners /
+fold and repeat counts used throughout the paper.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from preorder4mlc.constants import BaseLearnerName
+
+
+class AlgorithmType(Enum):
+    BOPOS = "bopos"
+    CLR = "clr"
+    BR = "br"
+    CC = "cc"
+    ECC = "ecc"
+
+
+@dataclass
+class DatasetConfig:
+    name: str
+    file: str
+    n_labels: int
+
+
+@dataclass
+class TrainingConfig:
+    data_path: str
+    results_dir: str
+    noisy_rates: list[float]
+    base_learners: list[BaseLearnerName]
+    total_repeat_times: int
+    number_folds: int
+    algorithms: list[AlgorithmType]  # Which algorithms to run
+    # When set, orchestrator skips repeats/folds whose index does not match.
+    # Result pickle filename is suffixed with _r<repeat>_f<fold> to keep
+    # split partials distinct; merge_split_results.py recombines them.
+    repeat_idx_filter: int | None = None
+    fold_idx_filter: int | None = None
+
+
+class ConfigManager:
+    DATASET_CONFIGS = {
+        "chd_49": DatasetConfig("CHD_49", "CHD_49.arff", 6),
+        "emotions": DatasetConfig("emotions", "emotions.arff", 6),
+        "scene": DatasetConfig("scene", "scene.arff", 6),
+        "yeast": DatasetConfig("Yeast", "Yeast.arff", 14),
+        "water_quality": DatasetConfig("Water-quality", "Water-quality.arff", 14),
+        "humanpseaac": DatasetConfig("HumanPseAAC", "HumanPseAAC.arff", 14),
+        "gpositivepseaac": DatasetConfig("GpositivePseAAC", "GpositivePseAAC.arff", 4),
+        "plantpseaac": DatasetConfig("PlantPseAAC", "PlantPseAAC.arff", 12),
+        "viruspseaac": DatasetConfig("VirusPseAAC", "VirusPseAAC.arff", 6),
+        # enron (K=53). ARFF is NOT bundled — download from COMETA / MULAN
+        # and place at ./data/enron.arff. See REPRODUCE.md.
+        "enron": DatasetConfig("enron", "enron.arff", 53),
+    }
+
+    @staticmethod
+    def get_dataset_config(dataset_name: str) -> DatasetConfig:
+        dataset_name = dataset_name.lower()
+        if dataset_name not in ConfigManager.DATASET_CONFIGS:
+            raise ValueError(f"Dataset {dataset_name} not found")
+        return ConfigManager.DATASET_CONFIGS[dataset_name]
+
+    @staticmethod
+    def get_training_config(args) -> TrainingConfig:
+        results_dir = args.results_dir if args.results_dir else "./results"
+        Path(results_dir).mkdir(parents=True, exist_ok=True)
+
+        # NOISY_RATES = [0.0, 0.1, 0.2, 0.3]
+        # If --noise_rate is passed on the CLI, restrict to that single level
+        # so the run can be split across slurm jobs by noise.
+        single_noise = getattr(args, "noise_rate", None)
+        if single_noise is not None:
+            NOISY_RATES = [float(single_noise)]
+        else:
+            NOISY_RATES = [
+                0.0,
+                0.1,
+                0.2,
+                0.3,
+            ]
+        # Default is RF (paper-equivalent). Pass --base_learner LightGBM on
+        # the CLI to switch to LightGBM (paper also reports LGBM results).
+        BASE_LEARNERS = [BaseLearnerName.RF]
+        bl_override = getattr(args, "base_learner", None)
+        if bl_override:
+            BASE_LEARNERS = [BaseLearnerName(bl_override)]
+        ALGORITHMS = [
+            AlgorithmType.BOPOS,
+            AlgorithmType.CLR,
+            AlgorithmType.BR,
+            AlgorithmType.CC,
+        ]
+        algo_override = getattr(args, "algorithm", None)
+        if algo_override:
+            ALGORITHMS = [AlgorithmType(algo_override)]
+
+        return TrainingConfig(
+            data_path="./data/",
+            results_dir=results_dir,
+            noisy_rates=NOISY_RATES,
+            base_learners=BASE_LEARNERS,
+            total_repeat_times=5,
+            number_folds=5,
+            algorithms=ALGORITHMS,
+            repeat_idx_filter=getattr(args, "repeat_idx", None),
+            fold_idx_filter=getattr(args, "fold_idx", None),
+        )

preorder4mlc/constants.py

@@ -0,0 +1,30 @@
+"""Shared constants and enum types.
+
+Centralises the base learner names and target metric enums used across
+:mod:`training_orchestrator`, :mod:`inference_models`, and
+:mod:`searching_algorithms`, along with the canonical random seed that
+controls every reproducible split and noise draw in the paper.
+"""
+
+from enum import Enum
+
+
+class BaseLearnerName(Enum):
+    """Identifier for the supported base learners."""
+
+    RF = "RF"
+    ETC = "ETC"
+    XGBoost = "XGBoost"
+    LightGBM = "LightGBM"
+
+
+# Used by every split, fold, and Bernoulli noise draw. Do not change
+# casually -- result directories in `results/` are tied to this seed.
+RANDOM_STATE = 6
+
+
+class TargetMetric(Enum):
+    """Loss the ILP search optimises for in :mod:`searching_algorithms`."""
+
+    Hamming = "Hamming"
+    Subset = "Subset"

preorder4mlc/datasets4experiments.py

@@ -0,0 +1,176 @@
+"""Dataset loading, splitting, and noise injection.
+
+:class:`Datasets4Experiments` reads multi-label ARFF files, separates X
+from Y based on whether labels are at the beginning or end of the file
+(controlled by :data:`TARGET_IN_END_FILE_DATASETS`), and yields k-fold
+splits with optional symmetric label-flip noise (Bernoulli with rate
+``noisy_rate``) for the training fold of each split.
+"""
+
+from logging import INFO, log
+
+import numpy as np
+import pandas as pd
+from scipy.io import arff
+from scipy.stats import bernoulli
+from sklearn.model_selection import KFold
+
+try:
+    import arff as liac_arff  # liac-arff package — handles sparse ARFF
+except ImportError:  # pragma: no cover
+    liac_arff = None
+
+TARGET_IN_END_FILE_DATASETS = [
+    "emotions.arff",
+    "scene.arff",
+    "flags.arff",
+    "VirusGO.arff",
+    "VirusPseAAC.arff",
+    "Yelp.arff",
+    "birds.arff",
+    "HumanPseAAC.arff",
+    "PlantGO.arff",
+    "GpositivePseAAC.arff",
+    "PlantPseAAC.arff",
+    # Medium-K additions (COMETA convention: labels at end of attribute list).
+    "enron.arff",
+    "medical.arff",
+    # Large-K additions (COMETA convention: labels at end of attribute list).
+    "CAL500.arff",
+    "mediamill.arff",
+    "bibtex.arff",
+]
+
+
+def _load_sparse_arff_to_dataframe(path: str) -> pd.DataFrame:
+    """Parse sparse-format ARFF via liac-arff and densify to a DataFrame.
+
+    Sparse rows look like ``{2 1, 5 1, ...}`` — every non-listed index is 0.
+    liac-arff returns a (n_samples, n_attributes) list-of-lists with zeros
+    filled in, which we wrap in a DataFrame keyed by the attribute names.
+    """
+    with open(path) as f:
+        obj = liac_arff.load(f, return_type=liac_arff.DENSE_GEN)
+        attr_names = [a[0] for a in obj["attributes"]]
+        rows = list(obj["data"])
+    return pd.DataFrame(rows, columns=attr_names)
+
+
+class Datasets4Experiments:
+
+    def __init__(self, data_path: str, data_files: list[dict]):
+        self.data_path = data_path
+
+        self.data_files = []
+        self.n_labels_set = []
+        for item in data_files:
+            self.data_files.append(item["dataset_name"])
+            self.n_labels_set.append(item["n_labels_set"])
+
+        self.datasets: list[tuple[np.ndarray, np.ndarray, str]] = []
+
+    def load_datasets(self):
+        for file_name, n_labels in zip(self.data_files, self.n_labels_set):
+            full_path = f"{self.data_path}{file_name}"
+            log(INFO, f"Loading dataset from {full_path}")
+            # NPY path: dataset_name ends with "_features.npy"; sibling labels
+            # file lives at the same path with "_features" replaced by "_labels".
+            if file_name.endswith("_features.npy"):
+                X = np.load(full_path).astype(np.float32)
+                labels_path = full_path.replace("_features.npy", "_labels.npy")
+                Y = np.load(labels_path).astype(int)
+                if Y.shape[1] != n_labels:
+                    raise ValueError(
+                        f"{file_name}: labels file has {Y.shape[1]} columns, "
+                        f"expected n_labels_set={n_labels}"
+                    )
+                Y = np.where(Y < 0, 0, Y)
+                df_name = file_name.removesuffix("_features.npy")
+                self.datasets.append((X, Y, df_name))
+                continue
+            try:
+                data, _meta = arff.loadarff(full_path)
+                df = pd.DataFrame(data)
+            except (ValueError, NotImplementedError) as e:
+                # scipy.io.arff cannot parse sparse ARFF format
+                # ({idx val, idx val, ...}). Fall back to liac-arff which
+                # supports it, then densify.
+                if liac_arff is None:
+                    raise RuntimeError(
+                        f"scipy.io.arff failed on {file_name} ({e}). "
+                        "Install liac-arff (`pip install liac-arff`) to handle "
+                        "sparse ARFF datasets like bibtex."
+                    ) from e
+                log(INFO, f"  scipy failed ({e!s}); retrying with liac-arff…")
+                df = _load_sparse_arff_to_dataframe(full_path)
+
+            is_target_in_end = any(
+                f.lower() == file_name.lower() for f in TARGET_IN_END_FILE_DATASETS
+            )
+
+            X, Y = self.preprocess_data(df, n_labels, is_target_in_end)
+            df_name = file_name.split(".")[0]
+            self.datasets.append((X, Y, df_name))
+
+    def preprocess_data(self, df, n_labels, is_target_in_end=False):
+        if is_target_in_end:
+            X = df.iloc[:, :-n_labels].to_numpy()
+            Y = df.iloc[:, -n_labels:].to_numpy().astype(int)
+        else:
+            X = df.iloc[:, n_labels:].to_numpy()
+            Y = df.iloc[:, :n_labels].to_numpy().astype(int)
+
+        # liac-arff returns object dtype when attributes are stored as strings
+        # in a sparse ARFF. Coerce to float for sklearn/LightGBM compatibility.
+        if X.dtype == object:
+            X = X.astype(float)
+
+        # Map sklearn-style -1 (negative) labels to 0 so downstream pairwise
+        # encoders see a clean {0,1} matrix.
+        Y = np.where(Y < 0, 0, Y)
+
+        return X, Y
+
+    def add_noise_to_labels(self, Y, noisy_rate):
+        """
+        Adds noise to the dataset labels based on the specified noisy rate.
+
+        :param Y: The label matrix for a dataset.
+        :param noisy_rate: The rate at which noise should be added to the labels.
+        :return: The label matrix with added noise.
+        """
+        n_instances, n_labels = Y.shape
+        for i in range(n_instances):
+            for j in range(n_labels):
+                if bernoulli.rvs(p=noisy_rate):
+                    Y[i, j] = 1 - Y[i, j]  # Flip the label to add noise
+        return Y
+
+    def kfold_split_with_noise(
+        self, dataset_index, n_splits=5, noisy_rate=0.0, random_state=None, shuffle=True
+    ):
+        """
+        Generates K-fold splits for a specific dataset and adds noise to the training labels.
+
+        :param dataset_index: Index of the dataset to split.
+        :param n_splits: Number of folds.
+        :param noisy_rate: Noise rate to be applied to the training set labels.
+        :param random_state: Random state for reproducibility.
+        :param shuffle: Whether to shuffle the data before splitting.
+        :return: Generator of K-fold splits (train_index, test_index) with noisy training labels.
+        """
+        X, Y, _ = self.datasets[dataset_index]
+        kf = KFold(n_splits=n_splits, random_state=random_state, shuffle=shuffle)
+        for train_index, test_index in kf.split(X):
+            Y_train_noisy = self.add_noise_to_labels(Y[train_index].copy(), noisy_rate)
+            # I want to return x_train, y_train_noisy, x_test, y_test
+            yield X[train_index], Y_train_noisy, X[test_index], Y[test_index]
+
+    def get_datasets(self) -> list:
+        return self.datasets
+
+    def get_length(self) -> int:
+        return len(self.datasets)
+
+    def get_dataset_name(self, dataset_index) -> str:
+        return self.datasets[dataset_index][2]

preorder4mlc/estimator.py

@@ -0,0 +1,123 @@
+"""Uniform estimator interface over scikit-learn and LightGBM backends.
+
+:class:`Estimator` is the single adapter every other module talks to;
+its constructor accepts a :class:`constants.BaseLearnerName` and hides
+the differences between :class:`sklearn.ensemble.RandomForestClassifier`,
+:class:`sklearn.ensemble.ExtraTreesClassifier`,
+:class:`sklearn.ensemble.GradientBoostingClassifier` (XGBoost in our
+nomenclature), and :class:`lightgbm.LGBMClassifier`.
+"""
+
+import os
+from logging import INFO, basicConfig
+
+from lightgbm import LGBMClassifier
+from numpy.typing import NDArray
+from sklearn.base import BaseEstimator
+from sklearn.calibration import CalibratedClassifierCV
+from sklearn.ensemble import (
+    ExtraTreesClassifier,
+    GradientBoostingClassifier,
+    RandomForestClassifier,
+)
+
+from preorder4mlc.constants import RANDOM_STATE, BaseLearnerName
+
+basicConfig(level=INFO)  # type: ignore
+
+number_of_cores: int = os.cpu_count() if os.cpu_count() is not None else 1  # type: ignore
+# log(INFO, f"Number of cores: {number_of_cores}")
+
+# Whether to wrap the base learner in CalibratedClassifierCV (isotonic).
+# Opt-in: default OFF so existing pipelines / paper-equivalent runs are
+# unchanged. Enable per-run via env (PREORDER_CALIBRATE=1) or constructor
+# (Estimator(name, calibrate=True)). The A/B/C/D ablation in
+# scripts/ablations/ablation_base_learner.py decides whether to flip the default.
+CALIBRATE_PROBAS = os.environ.get("PREORDER_CALIBRATE", "0") not in ("0", "false", "False")
+CALIBRATION_METHOD = os.environ.get("PREORDER_CALIBRATION_METHOD", "isotonic")
+CALIBRATION_CV = int(os.environ.get("PREORDER_CALIBRATION_CV", "3"))
+
+
+class Estimator:
+    def __init__(self, name: str, calibrate: bool | None = None):
+        self.name = name
+        self.calibrate = CALIBRATE_PROBAS if calibrate is None else calibrate
+        base = self.get_classifier()
+        if self.calibrate:
+            self.clf = CalibratedClassifierCV(
+                base, method=CALIBRATION_METHOD, cv=CALIBRATION_CV
+            )
+        else:
+            self.clf = base
+
+    def get_classifier(self) -> BaseEstimator | LGBMClassifier:
+        """Get the classifier based on name with proper error handling."""
+        if self.name == BaseLearnerName.RF.value:
+            return RandomForestClassifier(random_state=RANDOM_STATE)
+        elif self.name == BaseLearnerName.ETC.value:
+            return ExtraTreesClassifier(random_state=RANDOM_STATE)
+        elif self.name == BaseLearnerName.XGBoost.value:
+            return GradientBoostingClassifier(random_state=RANDOM_STATE)
+        elif self.name == BaseLearnerName.LightGBM.value:
+            return LGBMClassifier(
+                random_state=RANDOM_STATE,
+                # n_jobs=1 because LGBM is always called inside a
+                # joblib.Parallel(n_jobs=-1) loop in base_classifiers.py and the
+                # ECC/LP path. Using n_jobs=cores caused thread oversubscription
+                # (~5x slower on yeast); see scripts/ablations/NOTES.md.
+                n_jobs=1,
+                verbose=-1,
+                num_leaves=20,  # Moderate complexity
+                max_depth=6,
+                bagging_fraction=0.9,
+                feature_fraction=0.8,
+                learning_rate=0.1,
+                n_estimators=100,
+                min_child_samples=5,  # Relaxed for small datasets
+                min_child_weight=0.0001,  # Allow splits with low Hessian
+                min_split_gain=0.01,  # Allow minimal gain splits
+                is_unbalance=True,  # Handle label imbalance
+                device="cpu",
+            )
+        else:
+            raise ValueError(f"Unknown base learner: {self.name}")
+
+    def fit(self, X: NDArray, Y: NDArray):
+        """Fit the classifier with proper error handling.
+
+        When calibration is enabled but the data is degenerate (single class
+        or too few samples per class to support cv folds), fall back to the
+        uncalibrated base estimator so the pairwise pipeline still runs.
+        """
+        try:
+            self.clf.fit(X, Y)  # type: ignore
+        except Exception as e:
+            if self.calibrate:
+                fallback = self.get_classifier()
+                try:
+                    fallback.fit(X, Y)  # type: ignore
+                    self.clf = fallback
+                    return
+                except Exception as e2:
+                    raise ValueError(
+                        f"Error training {self.name} (calibrated and uncalibrated both failed): {e2}"
+                    ) from e2
+            raise ValueError(f"Error training {self.name}: {e}") from e
+
+    def predict_proba(self, X: NDArray) -> NDArray:
+        """Predict the probability of each class for each instance."""
+        prob = self.clf.predict_proba(X)  # type: ignore
+
+        return prob  # type: ignore
+
+    def classes_(self) -> list[int]:
+        return self.clf.classes_  # type: ignore
+
+    def predict(self, X: NDArray) -> NDArray:
+        return self.clf.predict(X)  # type: ignore
+
+
+def train_classifier(X, Y, estimator_name):
+    classifier = Estimator(estimator_name)  # Add n_jobs or other params here
+    classifier.fit(X, Y)
+    return classifier