jabs-behavior-classifier 0.44.2__tar.gz → 0.46.0__tar.gz

jabs_behavior_classifier-0.46.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 The Jackson Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{jabs_behavior_classifier-0.44.2 → jabs_behavior_classifier-0.46.0}/PKG-INFO

@@ -1,12 +1,13 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: jabs-behavior-classifier
-Version: 0.44.2
+Version: 0.46.0
 Summary: 
 Author: Glen Beane, Brian Geuther, Keith Sheppard, Alexander Berger-Liedtka
-License: Proprietary
-Requires-Dist: jabs-behavior==0.44.2
-Requires-Dist: jabs-core==0.44.2
-Requires-Dist: jabs-io==0.44.2
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: jabs-behavior==0.46.0
+Requires-Dist: jabs-core==0.46.0
+Requires-Dist: jabs-io==0.46.0
 Requires-Dist: h5py>=3.10.0,<4.0.0
 Requires-Dist: markdown2>=2.5.1,<3.0.0
 Requires-Dist: numpy>=2.0.0,<3.0.0
@@ -29,11 +30,13 @@ Requires-Dist: click>=8.2.1
 Requires-Dist: argparse-formatter>=1.4
 Requires-Dist: distinctipy>=1.3.4
 Requires-Dist: catboost>=1.2.8
+Requires-Dist: mlflow>=3.8.1 ; extra == 'mlflow'
 Requires-Dist: jabs-io[nwb] ; extra == 'nwb'
 Requires-Dist: pyyaml>=6.0.0 ; extra == 'yaml'
 Requires-Python: >=3.10, <3.15
 Project-URL: Issues, https://github.com/KumarLabJax/JABS-behavior-classifier/issues
 Project-URL: Repository, https://github.com/KumarLabJax/JABS-behavior-classifier
+Provides-Extra: mlflow
 Provides-Extra: nwb
 Provides-Extra: yaml
 Description-Content-Type: text/markdown
@@ -42,18 +45,20 @@ Description-Content-Type: text/markdown
 
 # JAX Animal Behavior System (JABS)
 
+## JABS Behavior Classifier
+
 **An open-source platform for standardized mouse behavioral phenotyping.**
 
 [![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/jabs-behavior-classifier.svg)](https://pypi.org/project/jabs-behavior-classifier/)
-[![License: Non-Commercial](https://img.shields.io/badge/license-non--commercial-orange.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/LICENSE)
 [![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.107259.2-green.svg)](https://doi.org/10.7554/eLife.107259.2)
 
-[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
+[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
 
 ---
 
-![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.44.2/docs/assets/images/jabs_screenshot.png)
+![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.0/docs/assets/images/jabs_screenshot.png)
 
 </div>
 
@@ -183,7 +188,7 @@ JABS requires pose files generated from the Kumar Lab's mouse pose estimation ne
 
 We provide Singularity/Apptainer definition files and SLURM batch scripts for running
 JABS on Linux compute clusters. See
-[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/vm/README.md)
+[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/vm/README.md)
 for build instructions and usage details.
 
 ## Project Portability
@@ -219,14 +224,14 @@ JABS uses four version numbers to track compatibility:
 ## Documentation
 
 - **[ReadTheDocs Tutorial](https://jabs-tutorial.readthedocs.io/)** — Complete user guide and tutorials
-- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/user-guide/overview.md)** — Markdown documentation
+- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/user-guide/overview.md)** — Markdown documentation
 - **[Sample Data](https://doi.org/10.5281/zenodo.16697331)** — Test datasets for demonstration
 
 ## Contributing
 
 Interested in contributing? Check out our:
-- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/CONTRIBUTING.md)
-- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/development/development.md)
+- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/CONTRIBUTING.md)
+- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/development/development.md)
 
 ## Citation
 
@@ -236,11 +241,9 @@ If you use JABS in your research, please cite:
 
 ## License
 
-Copyright 2023 The Jackson Laboratory — All rights reserved.
-
-JABS is licensed under a **non-commercial use license**. See [LICENSE](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/LICENSE) for details.
+Copyright (c) 2023-2026 The Jackson Laboratory.
 
-For commercial licensing inquiries, [contact us](mailto:jabs@jax.org).
+The JABS Behavior Classifier is released under the [MIT License](LICENSE).
 
 ## Acknowledgements
 

{jabs_behavior_classifier-0.44.2 → jabs_behavior_classifier-0.46.0}/README.md

@@ -2,18 +2,20 @@
 
 # JAX Animal Behavior System (JABS)
 
+## JABS Behavior Classifier
+
 **An open-source platform for standardized mouse behavioral phenotyping.**
 
 [![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://img.shields.io/pypi/v/jabs-behavior-classifier.svg)](https://pypi.org/project/jabs-behavior-classifier/)
-[![License: Non-Commercial](https://img.shields.io/badge/license-non--commercial-orange.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/LICENSE)
 [![DOI](https://img.shields.io/badge/DOI-10.7554%2FeLife.107259.2-green.svg)](https://doi.org/10.7554/eLife.107259.2)
 
-[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
+[Documentation](https://jabs-tutorial.readthedocs.io/) · [User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/user-guide/overview.md) · [Sample Data](https://doi.org/10.5281/zenodo.16697331) · [Contact Us](mailto:jabs@jax.org)
 
 ---
 
-![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.44.2/docs/assets/images/jabs_screenshot.png)
+![JABS Screenshot](https://raw.githubusercontent.com/KumarLabJax/JABS-behavior-classifier/v0.46.0/docs/assets/images/jabs_screenshot.png)
 
 </div>
 
@@ -143,7 +145,7 @@ JABS requires pose files generated from the Kumar Lab's mouse pose estimation ne
 
 We provide Singularity/Apptainer definition files and SLURM batch scripts for running
 JABS on Linux compute clusters. See
-[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/vm/README.md)
+[vm/README.md](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/vm/README.md)
 for build instructions and usage details.
 
 ## Project Portability
@@ -179,14 +181,14 @@ JABS uses four version numbers to track compatibility:
 ## Documentation
 
 - **[ReadTheDocs Tutorial](https://jabs-tutorial.readthedocs.io/)** — Complete user guide and tutorials
-- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/user-guide/overview.md)** — Markdown documentation
+- **[User Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/user-guide/overview.md)** — Markdown documentation
 - **[Sample Data](https://doi.org/10.5281/zenodo.16697331)** — Test datasets for demonstration
 
 ## Contributing
 
 Interested in contributing? Check out our:
-- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/CONTRIBUTING.md)
-- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/docs/development/development.md)
+- [Contributing Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/CONTRIBUTING.md)
+- [Development Guide](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.46.0/docs/development/development.md)
 
 ## Citation
 
@@ -196,11 +198,9 @@ If you use JABS in your research, please cite:
 
 ## License
 
-Copyright 2023 The Jackson Laboratory — All rights reserved.
-
-JABS is licensed under a **non-commercial use license**. See [LICENSE](https://github.com/KumarLabJax/JABS-behavior-classifier/blob/v0.44.2/LICENSE) for details.
+Copyright (c) 2023-2026 The Jackson Laboratory.
 
-For commercial licensing inquiries, [contact us](mailto:jabs@jax.org).
+The JABS Behavior Classifier is released under the [MIT License](LICENSE).
 
 ## Acknowledgements
 

{jabs_behavior_classifier-0.44.2 → jabs_behavior_classifier-0.46.0}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "jabs-behavior-classifier"
-version = "0.44.2"
+version = "0.46.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
-license = { text = "Proprietary" }
+license = "MIT"
+license-files = ["LICENSE"]
 
 authors = [
   { name = "Glen Beane" },
@@ -14,9 +15,9 @@ authors = [
 ]
 
 dependencies = [
-  "jabs-behavior==0.44.2",
-  "jabs-core==0.44.2",
-  "jabs-io==0.44.2",
+  "jabs-behavior==0.46.0",
+  "jabs-core==0.46.0",
+  "jabs-io==0.46.0",
   "h5py>=3.10.0,<4.0.0",
   "markdown2>=2.5.1,<3.0.0",
   "numpy>=2.0.0,<3.0.0",
@@ -44,6 +45,7 @@ dependencies = [
 [project.optional-dependencies]
 nwb = ["jabs-io[nwb]"]
 yaml = ["pyyaml>=6.0.0"]
+mlflow = ["mlflow>=3.8.1"]
 
 [tool.uv.sources]
 jabs-behavior = { workspace = true }
@@ -91,3 +93,11 @@ build-backend = "uv_build"
 [tool.uv.build-backend]
 namespace = true
 module-name = "jabs"
+
+[tool.pytest.ini_options]
+# Default to the application test suite under tests/. The reusable library packages
+# under packages/* have their own test suites and are run separately (e.g.
+# `pytest packages/jabs-core/tests`); collecting them together from the repo root
+# fails on cross-package test-module name collisions, which is why CI runs each
+# suite separately. Explicit path arguments override this default.
+testpaths = ["tests"]

{jabs_behavior_classifier-0.44.2 → jabs_behavior_classifier-0.46.0}/src/jabs/classifier/__init__.py

@@ -7,20 +7,36 @@ Gradient Boosting, and XGBoost), utilities for feature management, data splittin
 
 from .classifier import Classifier
 from .cross_validation import run_leave_one_group_out_cv
+from .mlflow_logging import (
+    MlflowLoggingError,
+    log_cross_validation_to_mlflow,
+    mlflow_available,
+    parse_kv_tags,
+)
+from .multi_class_classifier import MultiClassClassifier
 from .protocols import ClassifierProtocol
 from .training_report import (
+    BinaryCVResult,
     CrossValidationResult,
+    MultiClassCVResult,
     TrainingReportData,
     generate_markdown_report,
     save_training_report,
 )
 
 __all__ = [
+    "BinaryCVResult",
     "Classifier",
     "ClassifierProtocol",
     "CrossValidationResult",
+    "MlflowLoggingError",
+    "MultiClassCVResult",
+    "MultiClassClassifier",
     "TrainingReportData",
     "generate_markdown_report",
+    "log_cross_validation_to_mlflow",
+    "mlflow_available",
+    "parse_kv_tags",
     "run_leave_one_group_out_cv",
     "save_training_report",
 ]

jabs_behavior_classifier-0.46.0/src/jabs/classifier/base.py

@@ -0,0 +1,342 @@
+"""Shared infrastructure for behavior classifiers.
+
+``BaseClassifier`` consolidates persistence, identity properties, factory
+dispatch, feature cleaning, and feature-importance reporting that are common
+to both binary and multi-class classifiers. Subclasses provide the train and
+predict implementations that determine the actual learning behavior.
+
+The class is concrete (not abstract): subclasses are not required to
+override anything to instantiate. Public surface for classifier *consumers*
+is governed by :class:`jabs.classifier.ClassifierProtocol`, which both
+subclasses satisfy structurally.
+"""
+
+from __future__ import annotations
+
+import typing
+import warnings
+from pathlib import Path
+from typing import ClassVar
+
+import joblib
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+from sklearn.exceptions import InconsistentVersionWarning
+
+from jabs.core.enums import ClassifierType
+from jabs.core.utils import hash_file
+
+from . import classifier_utils, factories
+
+
+class BaseClassifier:
+    """Shared persistence and identity machinery for JABS classifiers.
+
+    Class attributes that subclasses must set:
+        ``_VERSION``: pickled-format version integer for this subclass.
+        ``_MULTICLASS``: True if this subclass operates in multi-class mode.
+        ``_PERSISTED_REQUIRED``: tuple of instance attribute names that ``load``
+            must restore from the pickled instance.
+        ``_PERSISTED_OPTIONAL``: tuple of instance attribute names that
+            ``load`` should restore if present on the pickled instance (default
+            to ``None`` otherwise). Used to support older pickles that may not
+            have all attributes the live class now declares.
+    """
+
+    _VERSION: ClassVar[int] = 0
+    _MULTICLASS: ClassVar[bool] = False
+    _PERSISTED_REQUIRED: ClassVar[tuple[str, ...]] = ()
+    _PERSISTED_OPTIONAL: ClassVar[tuple[str, ...]] = ()
+
+    def __init__(self, classifier_type: ClassifierType, n_jobs: int = 1) -> None:
+        self._classifier_type = classifier_type
+        self._classifier: typing.Any = None
+        self._project_settings: dict | None = None
+        self._feature_names: list[str] | None = None
+        self._n_jobs = n_jobs
+        self._version = self._VERSION
+
+        self._classifier_file: str | None = None
+        self._classifier_hash: str | None = None
+        self._classifier_source: str | None = None
+
+        self._supported_classifiers = self._supported_classifier_choices()
+        if classifier_type not in self._supported_classifiers:
+            raise ValueError("Invalid classifier type")
+
+    @property
+    def classifier_name(self) -> str:
+        """Return the name of the underlying algorithm."""
+        return self._classifier_type.value
+
+    @property
+    def classifier_type(self) -> ClassifierType:
+        """Return the underlying classifier algorithm enum value."""
+        return self._classifier_type
+
+    @property
+    def classifier_file(self) -> str | None:
+        """Return the filename of the saved classifier, if any."""
+        return self._classifier_file
+
+    @property
+    def classifier_hash(self) -> str | None:
+        """Return the content hash of the saved classifier, if any."""
+        return self._classifier_hash
+
+    @property
+    def project_settings(self) -> dict:
+        """Return a copy of the classifier's training settings."""
+        if self._project_settings is not None:
+            return dict(self._project_settings)
+        return {}
+
+    @property
+    def version(self) -> int:
+        """Return the serialized classifier format version."""
+        return self._version
+
+    @property
+    def feature_names(self) -> list[str] | None:
+        """Return the list of feature names used to train this classifier."""
+        return self._feature_names
+
+    @classmethod
+    def _supported_classifier_choices(cls) -> set[ClassifierType]:
+        """Return classifier types available in the current environment.
+
+        Resolved per-call so that test code can patch
+        :func:`jabs.classifier.factories.supported_classifier_types` or this
+        method on the subclass without freezing state at import time.
+        """
+        return factories.supported_classifier_types(multiclass=cls._MULTICLASS)
+
+    def set_classifier(self, classifier: ClassifierType) -> None:
+        """Switch the underlying classifier algorithm.
+
+        Args:
+            classifier: The classifier type to switch to.
+
+        Raises:
+            ValueError: If the classifier type is not supported.
+        """
+        if classifier not in self._supported_classifier_choices():
+            raise ValueError("Invalid Classifier Type")
+        self._classifier_type = classifier
+
+    def set_dict_settings(self, settings: dict) -> None:
+        """Assign classifier settings from a dictionary.
+
+        Args:
+            settings: dict of settings (same structure as
+                ``project.settings_manager.get_behavior``).
+        """
+        self._project_settings = dict(settings)
+
+    def classifier_choices(self) -> dict[ClassifierType, str]:
+        """Return the available classifier types as a sorted display map.
+
+        Returns:
+            dict mapping ``ClassifierType`` enum values to their string names.
+        """
+        return {t: t.value for t in sorted(self._supported_classifiers, key=lambda t: t.value)}
+
+    def _create_classifier(self, random_seed: int | None = None) -> typing.Any:
+        """Instantiate the underlying sklearn/xgboost/catboost classifier."""
+        factory = factories.get_factory(self._classifier_type, multiclass=self._MULTICLASS)
+        return factory(self._n_jobs, random_seed)
+
+    def _clean_features(self, features: pd.DataFrame) -> pd.DataFrame:
+        """Replace ±inf/NaN in feature matrix per classifier type."""
+        return classifier_utils.clean_features(features, self._classifier_type)
+
+    def _get_features_to_classify(self, features: pd.DataFrame) -> pd.DataFrame:
+        """Reorder/select feature columns to match the trained model.
+
+        Args:
+            features: DataFrame of feature data to filter.
+
+        Returns:
+            DataFrame containing only the columns the trained model expects,
+            in the order the model expects them.
+
+        Raises:
+            RuntimeError: If feature names cannot be obtained from the model.
+        """
+        if self._classifier_type == ClassifierType.XGBOOST:
+            classifier_columns = self._classifier.get_booster().feature_names
+        elif hasattr(self._classifier, "feature_names_in_"):
+            classifier_columns = list(self._classifier.feature_names_in_)
+        elif hasattr(self._classifier, "feature_names_"):
+            classifier_columns = list(self._classifier.feature_names_)
+        else:
+            raise RuntimeError("Error obtaining feature names from classifier.")
+        return features[classifier_columns]
+
+    @staticmethod
+    def combine_data(per_frame: pd.DataFrame, window: pd.DataFrame) -> pd.DataFrame:
+        """Combine per-frame and window feature DataFrames into one."""
+        return classifier_utils.combine_data(per_frame, window)
+
+    @staticmethod
+    def derive_predictions(
+        probabilities: npt.NDArray[np.floating],
+    ) -> tuple[npt.NDArray[np.int8], npt.NDArray[np.floating]]:
+        """Derive class predictions and confidence from class probabilities.
+
+        Args:
+            probabilities: Array of shape ``(n_frames, n_classes)`` of predicted
+                class probabilities.
+
+        Returns:
+            Tuple ``(predictions, confidence)`` where ``predictions`` is the
+            argmax class index per frame (``-1`` if confidence is zero,
+            indicating no pose) and ``confidence`` is the probability of the
+            chosen class.
+        """
+        predictions = np.argmax(probabilities, axis=1).astype(np.int8)
+        confidence = probabilities[np.arange(len(probabilities)), predictions]
+        predictions[confidence == 0] = -1
+        return predictions, confidence
+
+    def get_feature_importance(self, limit: int = 20) -> list[tuple[str, float]]:
+        """Return ranked feature importances, highest first.
+
+        Args:
+            limit: Maximum number of features to return.
+
+        Returns:
+            List of ``(feature_name, importance)`` tuples sorted by importance
+            descending. Returns an empty list if the classifier is untrained or
+            does not expose feature importances.
+        """
+        if self._classifier is None or self._feature_names is None:
+            return []
+        if not hasattr(self._classifier, "feature_importances_"):
+            return []
+        importances = list(np.asarray(self._classifier.feature_importances_).reshape(-1))
+        feature_importance = [
+            (feature, round(importance, 2))
+            for feature, importance in zip(self._feature_names, importances, strict=True)
+        ]
+        feature_importance.sort(key=lambda x: x[1], reverse=True)
+        return feature_importance[:limit]
+
+    def reset_persistence_identity(self) -> None:
+        """Clear the recorded file identity (path, hash, source).
+
+        ``save()`` only (re)computes ``_classifier_hash`` when
+        ``_classifier_file`` is ``None``, so an already-persisted classifier
+        keeps its previous hash even if its contents change. Call this after
+        mutating persisted state (e.g. renaming a class) so the next ``save()``
+        records a hash matching the rewritten file. ``train()`` performs the
+        same null-out after refitting.
+        """
+        self._classifier_file = None
+        self._classifier_hash = None
+        self._classifier_source = None
+
+    def save(self, path: Path) -> None:
+        """Serialize the classifier to disk using joblib.
+
+        Args:
+            path: Destination file path.
+        """
+        joblib.dump(self, path)
+        if self._classifier_file is None:
+            self._classifier_file = Path(path).name
+            self._classifier_hash = hash_file(Path(path))
+            self._classifier_source = "serialized"
+
+    @classmethod
+    def from_pickle(cls, path: Path) -> BaseClassifier:
+        """Load a classifier from a pickle file with full validation and metadata backfill.
+
+        Applies the same version, classifier-type, and metadata checks as
+        :meth:`load`, but as a classmethod factory so no dummy instance is
+        required. The class of the returned object is determined by the
+        calling class - ``Classifier.from_pickle(...)`` rejects pickled
+        ``MultiClassClassifier`` instances and vice versa.
+
+        Args:
+            path: Path to the saved classifier pickle file.
+
+        Returns:
+            Loaded and validated classifier instance of type ``cls``.
+
+        Raises:
+            ValueError: If the file is not an instance of ``cls``, was trained
+                with an incompatible sklearn or JABS version, or uses an
+                unsupported classifier type.
+        """
+        with warnings.catch_warnings(record=True) as caught_warnings:
+            warnings.simplefilter("always", InconsistentVersionWarning)
+            c = joblib.load(path)
+            for warning in caught_warnings:
+                if issubclass(warning.category, InconsistentVersionWarning):
+                    raise ValueError("Classifier trained with different version of sklearn.")
+                warnings.warn(warning.message, warning.category, stacklevel=2)
+
+        if not isinstance(c, cls):
+            raise ValueError(f"{path} is not an instance of {cls.__name__}")
+
+        if c._version != cls._VERSION:
+            raise ValueError(
+                f"Unable to deserialize pickled classifier. "
+                f"File version {c._version}, expected {cls._VERSION}."
+            )
+
+        if c._classifier_type not in cls._supported_classifier_choices():
+            raise ValueError("Invalid classifier type")
+
+        if c._classifier_file is None:
+            c._classifier_file = Path(path).name
+            c._classifier_hash = hash_file(Path(path))
+            c._classifier_source = "pickle"
+
+        return c
+
+    def load(self, path: Path) -> None:
+        """Deserialize a classifier from disk, updating this instance in place.
+
+        Args:
+            path: Source file path.
+
+        Raises:
+            ValueError: If the file is not an instance of this class, was saved
+                with a different version, or uses an unsupported classifier type.
+        """
+        with warnings.catch_warnings(record=True) as caught_warnings:
+            warnings.simplefilter("always", InconsistentVersionWarning)
+            c = joblib.load(path)
+            for warning in caught_warnings:
+                if issubclass(warning.category, InconsistentVersionWarning):
+                    raise ValueError("Classifier trained with different version of sklearn.")
+                warnings.warn(warning.message, warning.category, stacklevel=2)
+
+        if not isinstance(c, type(self)):
+            raise ValueError(f"{path} is not an instance of {type(self).__name__}")
+
+        if c._version != self._VERSION:
+            raise ValueError(
+                f"Unable to deserialize pickled classifier. "
+                f"File version {c._version}, expected {self._VERSION}."
+            )
+
+        if c._classifier_type not in self._supported_classifiers:
+            raise ValueError("Invalid classifier type")
+
+        for attr in self._PERSISTED_REQUIRED:
+            setattr(self, attr, getattr(c, attr))
+        for attr in self._PERSISTED_OPTIONAL:
+            setattr(self, attr, getattr(c, attr, None))
+
+        if c._classifier_file is not None:
+            self._classifier_file = c._classifier_file
+            self._classifier_hash = c._classifier_hash
+            self._classifier_source = c._classifier_source
+        else:
+            self._classifier_file = Path(path).name
+            self._classifier_hash = hash_file(Path(path))
+            self._classifier_source = "pickle"