sklearn-morpho 0.2.3__py3-none-any.whl

sklearn_morpho/__init__.py

@@ -0,0 +1,5 @@
+from .classifiers import (
+    LDEP as LDEP,
+    RDEP as RDEP,
+    MorphoPerceptron as MorphoPerceptron,
+)

sklearn_morpho/classifiers/__init__.py

@@ -0,0 +1,3 @@
+from .ldep import LDEP as LDEP
+from .rdep import RDEP as RDEP
+from .simple_perceptron import MorphoPerceptron as MorphoPerceptron

sklearn_morpho/classifiers/ldep.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import numpy as np
+from typing import Literal, cast
+
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.preprocessing import StandardScaler
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import validate_data, check_is_fitted
+from sklearn.utils.multiclass import unique_labels
+
+from ..training.dccp_ldep import LDEPDccpTrainer
+from ..stopping import (
+    StoppingMethod,
+    CostStoppingMethod,
+    EarlyStoppingMethod,
+    EpochStoppingMethod,
+    TrainStopStoppingMethod,
+)
+from ..weighting import SampleWeighting, NoneSampleWeighting
+
+
+class LDEP(ClassifierMixin, BaseEstimator):
+    """
+    Scikit-learn estimator wrapper around a l-DEP (linear Dilation-Erosion
+    morphological Perceptron) for binary data classification.
+
+    The l-DEP's activation function is defined as:
+
+    \\[ y = f(\\lambda \\tau_(R_1(x)) + (1 - \\lambda) \\tau'_(R_2(x))) \\]
+
+    Where $\\tau$ refers to the activation of a (max, +) morphological
+    perceptron and $\\tau'$ to a (min, +) one.
+    $R_1, R_2$ are linear transformations to apply to the training data.
+    They convert it into a latent space with possibly different dimensions,
+    also allowing classification of arbitrarily distributed data.
+    A higher dimension for the latent space will result in slower training
+    times, but will allow the decision boundary to be more complex.
+    """
+
+    def __init__(
+        self,
+        latent_dims: tuple[int, int] = (10, 10),
+        margin=1.0,
+        penalty=0.0,
+        validation_ratio=0.3,
+        weighting_method: SampleWeighting | None = None,
+        stopping_methods: list[StoppingMethod] | None = None,
+        use_dccp_library: bool = False,
+        verbose: Literal[0, 1, 2] = 0,
+        random_state: np.random.RandomState | None = None,
+    ) -> None:
+        """
+        Initialize the classifier, see class help for more.
+
+        param latent_dims:      The dimensions of the latent spaces used for the
+                                linear transformations output
+        param margin:           Enforce a margin between the decision boundary
+                                and the data. May help with linearly separable
+                                datasets, but generally lower is more accurate.
+        param penalty:          A penalty to add to the weights squared and
+                                avoid them exploding.
+                                Must be a small positive number like 1e-6, or
+                                zero to disable penalty calculation altogether.
+        param validation_radio: How much of the training set to dedicate to use
+                                as validation during fitting.
+                                Must be between 0 and 1 (inclusive, exclusive),
+                                if set to exactly 0 then incompatible stopping
+                                methods cannot be used (e.g. early stopping).
+                                Ignored when using the dccp library solver.
+        param weighting_method: The weighting method to use: apply weights to
+                                the cost contribution of each data point to help
+                                avoid outliers.
+                                If left to None, will use NoneWeightingMethod().
+        param stopping_methods: A list of stopping methods, must not be empty.
+                                At each epoch, these methods will be
+                                sequentially asked whether the training should
+                                stop. In this case, epoch ends by rolling back
+                                to the epoch with the best validation cost.
+                                If left to None, will use:
+                                [
+                                    CostStoppingMethod(),
+                                    EarlyStoppingMethod(),
+                                    EpochStoppingMethod(),
+                                    TrainStopStoppingMethod(),
+                                ]
+                                Ignored when using the dccp library solver.
+        param use_dccp_library: Whether to use the dccp library as a solver or
+                                a manual constraints linearization in fit.
+        param verbose:          Whether to log extra information. 0: no logging,
+                                1: basic logging / timing, 2: cvxpy solve() set
+                                to verbose mode.
+        param random_state:     A RandomState object or None to allow for seeded
+                                randomness.
+        """
+
+        self.latent_dims = latent_dims
+        self.margin = margin
+        self.penalty = penalty
+        self.validation_ratio = validation_ratio
+        self.weighting_method = weighting_method
+        self.stopping_methods = stopping_methods
+        self.use_dccp_library = use_dccp_library
+        self.verbose: Literal[0, 1, 2] = verbose
+        self.random_state = random_state
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> LDEP:
+        """
+        Fit the classifier, create attributes:
+        - self.max_perceptron_
+        - self.min_perceptron_
+        - self.lambda_
+        - self.max_matrix_
+        - self.min_matrix_
+        - self.classes_:        Unique labels generated from y
+
+        X and y must represent binary classifiable data.
+        """
+
+        # input data validation
+        random_state = check_random_state(self.random_state)
+        X, y = validate_data(self, X, y)  # type: ignore
+        self.scaler_ = StandardScaler()
+        X_scaled = self.scaler_.fit_transform(X)
+
+        # set unset parameters to their default values
+        if self.weighting_method is None:
+            weighting_method = NoneSampleWeighting()
+        else:
+            weighting_method = self.weighting_method
+        if self.stopping_methods is None:
+            stopping_methods = [
+                CostStoppingMethod(),
+                EarlyStoppingMethod(),
+                EpochStoppingMethod(),
+                TrainStopStoppingMethod(),
+            ]
+        else:
+            stopping_methods = self.stopping_methods
+
+        # create classes and convert them to distinct integers for fitting
+        # the classes are persisted inside the object for use in predict
+        self.classes_ = unique_labels(y)
+        classes_list = list(self.classes_)
+        y_integers = np.array(
+            [classes_list.index(c) for c in y], dtype=np.int32
+        )
+
+        if len(classes_list) != 2:
+            raise ValueError(
+                'Only binary classification is supported but '
+                f'got {len(classes_list)} class(es).'
+            )
+
+        # create and train perceptrons
+        trainer = LDEPDccpTrainer(
+            self.latent_dims,
+            self.margin,
+            self.penalty,
+            self.validation_ratio,
+            weighting_method,
+            stopping_methods,
+            self.use_dccp_library,
+            self.verbose,
+            random_state,
+        )
+
+        trainer.train(X_scaled, y_integers)
+        self.max_perceptron_ = trainer.max_perceptron
+        self.min_perceptron_ = trainer.min_perceptron
+        self.lambda_ = trainer.lambda_
+        self.max_matrix_ = trainer.max_matrix
+        self.min_matrix_ = trainer.min_matrix
+
+        return self
+
+    def decision_function(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        X = validate_data(self, X, reset=False)  # type: ignore
+        X_scaled = cast(np.ndarray, self.scaler_.transform(X))
+
+        expr_max = np.max(
+            self.max_perceptron_ + X_scaled @ self.max_matrix_.T, axis=1
+        )
+        expr_min = np.min(
+            self.min_perceptron_ + X_scaled @ self.min_matrix_.T, axis=1
+        )
+        return expr_max * self.lambda_ + expr_min * (1 - self.lambda_)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        return self.classes_[(self.decision_function(X) >= 0).astype(int)]
+
+    def __sklearn_tags__(self):
+        """
+        Overriden method to allow check_estimator to not run accuracy tests.
+        These are designed for perceptrons with a linear decision boundary,
+        which is not the case for a morphological perceptron.
+        """
+
+        tags = super().__sklearn_tags__()
+        tags.classifier_tags.multi_class = False
+        return tags

sklearn_morpho/classifiers/rdep.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import numpy as np
+from typing import Literal, cast
+
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.preprocessing import StandardScaler
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import validate_data, check_is_fitted
+from sklearn.utils.multiclass import unique_labels
+
+from ..training.dccp_rdep import RDEPDccpTrainer
+from ..stopping import (
+    StoppingMethod,
+    CostStoppingMethod,
+    EarlyStoppingMethod,
+    EpochStoppingMethod,
+    TrainStopStoppingMethod,
+)
+from ..weighting import SampleWeighting, NoneSampleWeighting
+
+
+class RDEP(ClassifierMixin, BaseEstimator):
+    """
+    Scikit-learn estimator wrapper around a r-DEP (reduced Dilation-Erosion
+    morphological Perceptron) for binary data classification.
+
+    The r-DEP's activation function is defined as:
+
+    \\[ y = f(\\lambda \\tau_(x) + (1 - \\lambda) \\tau'_(x)) \\]
+
+    Where $\\tau$ refers to the activation of a (max, +) morphological
+    perceptron and $\\tau'$ to a (min, +) one.
+    $\\lambda$ is a real number between 0 and 1 to guarantee correct convexity,
+    but in practice a smaller interval can be enforced to avoid imprecisions.
+    """
+
+    def __init__(
+        self,
+        lambda_bounds=(1e-3, 1 - 1e-3),
+        margin=0.0,
+        penalty=0.0,
+        validation_ratio=0.3,
+        weighting_method: SampleWeighting | None = None,
+        stopping_methods: list[StoppingMethod] | None = None,
+        use_dccp_library: bool = False,
+        verbose: Literal[0, 1, 2] = 0,
+        random_state: np.random.RandomState | None = None,
+    ) -> None:
+        """
+        Initialize the classifier, see class help for more.
+
+        param lambda_bounds:    A pair of min and max values for lambda, to
+                                avoid solvers (especially dccp) from failing to
+                                optimize.
+                                To keep the constraints at the right convexity,
+                                the bounds must be inside [0, 1].
+        param margin:           Enforce a margin between the decision boundary
+                                and the data. May help with linearly separable
+                                datasets, but generally lower is more accurate.
+        param penalty:          A penalty to add to the weights squared and
+                                avoid them exploding.
+                                Must be a small positive number like 1e-6, or
+                                zero to disable penalty calculation altogether.
+        param validation_radio: How much of the training set to dedicate to use
+                                as validation during fitting.
+                                Must be between 0 and 1 (inclusive, exclusive),
+                                if set to exactly 0 then incompatible stopping
+                                methods cannot be used (e.g. early stopping).
+                                Ignored when using the dccp library solver.
+        param weighting_method: The weighting method to use: apply weights to
+                                the cost contribution of each data point to help
+                                avoid outliers.
+                                If left to None, will use NoneWeightingMethod().
+        param stopping_methods: A list of stopping methods, must not be empty.
+                                At each epoch, these methods will be
+                                sequentially asked whether the training should
+                                stop. In this case, epoch ends by rolling back
+                                to the epoch with the best validation cost.
+                                If left to None, will use:
+                                [
+                                    CostStoppingMethod(),
+                                    EarlyStoppingMethod(),
+                                    EpochStoppingMethod(),
+                                    TrainStopStoppingMethod(),
+                                ]
+                                Ignored when using the dccp library solver.
+        param use_dccp_library: Whether to use the dccp library as a solver or
+                                a manual constraints linearization in fit.
+        param verbose:          Whether to log extra information. 0: no logging,
+                                1: basic logging / timing, 2: cvxpy solve() set
+                                to verbose mode.
+        param random_state:     A RandomState object or None to allow for seeded
+                                randomness.
+        """
+
+        self.lambda_bounds = lambda_bounds
+        self.margin = margin
+        self.penalty = penalty
+        self.validation_ratio = validation_ratio
+        self.weighting_method = weighting_method
+        self.stopping_methods = stopping_methods
+        self.use_dccp_library = use_dccp_library
+        self.verbose: Literal[0, 1, 2] = verbose
+        self.random_state = random_state
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> RDEP:
+        """
+        Fit the classifier, create attributes:
+        - self.max_perceptron_
+        - self.min_perceptron_
+        - self.classes_:        Unique labels generated from y
+
+        X and y must represent binary classifiable data.
+        """
+
+        # input data validation
+        random_state = check_random_state(self.random_state)
+        X, y = validate_data(self, X, y)  # type: ignore
+        self.scaler_ = StandardScaler()
+        X_scaled = self.scaler_.fit_transform(X)
+
+        # set unset parameters to their default values
+        if self.weighting_method is None:
+            weighting_method = NoneSampleWeighting()
+        else:
+            weighting_method = self.weighting_method
+        if self.stopping_methods is None:
+            stopping_methods = [
+                CostStoppingMethod(),
+                EarlyStoppingMethod(),
+                EpochStoppingMethod(),
+                TrainStopStoppingMethod(),
+            ]
+        else:
+            stopping_methods = self.stopping_methods
+
+        # create classes and convert them to distinct integers for fitting
+        # the classes are persisted inside the object for use in predict
+        self.classes_ = unique_labels(y)
+        classes_list = list(self.classes_)
+        y_integers = np.array(
+            [classes_list.index(c) for c in y], dtype=np.int32
+        )
+
+        if len(classes_list) != 2:
+            raise ValueError(
+                'Only binary classification is supported but '
+                f'got {len(classes_list)} class(es).'
+            )
+
+        # create and train perceptrons
+        trainer = RDEPDccpTrainer(
+            self.lambda_bounds,
+            self.margin,
+            self.penalty,
+            self.validation_ratio,
+            weighting_method,
+            stopping_methods,
+            self.use_dccp_library,
+            self.verbose,
+            random_state,
+        )
+
+        trainer.train(X_scaled, y_integers)
+        self.max_perceptron_ = trainer.max_perceptron
+        self.min_perceptron_ = trainer.min_perceptron
+        self.lambda_ = trainer.lambda_
+        self.invert_res_ = trainer.invert_res
+
+        return self
+
+    def decision_function(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        X = validate_data(self, X, reset=False)  # type: ignore
+        X_scaled = cast(np.ndarray, self.scaler_.transform(X))
+
+        expr_max = np.max(self.max_perceptron_ + X_scaled, axis=1)
+        expr_min = np.min(self.min_perceptron_ + X_scaled, axis=1)
+        activation = expr_max * self.lambda_ + expr_min * (1 - self.lambda_)
+
+        return activation * (1 - 2 * self.invert_res_)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        return self.classes_[(self.decision_function(X) >= 0).astype(int)]
+
+    def __sklearn_tags__(self):
+        """
+        Overriden method to allow check_estimator to not run accuracy tests.
+        These are designed for perceptrons with a linear decision boundary,
+        which is not the case for a morphological perceptron.
+        """
+
+        tags = super().__sklearn_tags__()
+        tags.classifier_tags.multi_class = False
+        return tags

sklearn_morpho/classifiers/simple_perceptron.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import numpy as np
+from typing import Literal, cast
+
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.preprocessing import StandardScaler
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import validate_data, check_is_fitted
+from sklearn.utils.multiclass import unique_labels
+
+from ..training.dccp_simple_perceptron import SimplePerceptronDccpTrainer
+from ..stopping import (
+    StoppingMethod,
+    CostStoppingMethod,
+    EarlyStoppingMethod,
+    EpochStoppingMethod,
+    TrainStopStoppingMethod,
+)
+from ..weighting import SampleWeighting, NoneSampleWeighting
+
+
+class MorphoPerceptron(ClassifierMixin, BaseEstimator):
+    """
+    Scikit-learn estimator wrapper around a simple morphological perceptron.
+
+    The morphological perceptron's activation function is defined as:
+
+    \\[ y = \\tau(w + x) \\]
+
+    Where $\\tau$ refers to max (resp. min), for a dilation (resp. erosion)
+    perceptron and $w$ the perceptron's weights.
+    """
+
+    def __init__(
+        self,
+        kind: Literal['max', 'min'],
+        margin=0.0,
+        penalty=0.0,
+        validation_ratio=0.3,
+        weighting_method: SampleWeighting | None = None,
+        stopping_methods: list[StoppingMethod] | None = None,
+        use_dccp_library: bool = False,
+        verbose: Literal[0, 1, 2] = 0,
+        random_state: np.random.RandomState | None = None,
+    ) -> None:
+        """
+        Initialize the classifier, see class help for more.
+
+        param kind:             Whether the perceptron is dilation or erosion.
+        param margin:           Enforce a margin between the decision boundary
+                                and the data. May help with linearly separable
+                                datasets, but generally lower is more accurate.
+        param penalty:          A penalty to add to the weights squared and
+                                avoid them exploding.
+                                Must be a small positive number like 1e-6, or
+                                zero to disable penalty calculation altogether.
+        param validation_radio: How much of the training set to dedicate to use
+                                as validation during fitting.
+                                Must be between 0 and 1 (inclusive, exclusive),
+                                if set to exactly 0 then incompatible stopping
+                                methods cannot be used (e.g. early stopping).
+                                Ignored when using the dccp library solver.
+        param weighting_method: The weighting method to use: apply weights to
+                                the cost contribution of each data point to help
+                                avoid outliers.
+                                If left to None, will use NoneWeightingMethod().
+        param stopping_methods: A list of stopping methods, must not be empty.
+                                At each epoch, these methods will be
+                                sequentially asked whether the training should
+                                stop. In this case, epoch ends by rolling back
+                                to the epoch with the best validation cost.
+                                If left to None, will use:
+                                [
+                                    CostStoppingMethod(),
+                                    EarlyStoppingMethod(),
+                                    EpochStoppingMethod(),
+                                    TrainStopStoppingMethod(),
+                                ]
+                                Ignored when using the dccp library solver.
+        param use_dccp_library: Whether to use the dccp library as a solver or
+                                a manual constraints linearization in fit.
+        param verbose:          Whether to log extra information. 0: no logging,
+                                1: basic logging / timing, 2: cvxpy solve() set
+                                to verbose mode.
+        param random_state:     A RandomState object or None to allow for seeded
+                                randomness.
+        """
+
+        self.kind: Literal['max', 'min'] = kind
+        self.margin = margin
+        self.penalty = penalty
+        self.validation_ratio = validation_ratio
+        self.weighting_method = weighting_method
+        self.stopping_methods = stopping_methods
+        self.use_dccp_library = use_dccp_library
+        self.verbose: Literal[0, 1, 2] = verbose
+        self.random_state = random_state
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> MorphoPerceptron:
+        """
+        Fit the classifier, create attributes:
+        - self.weights
+        - self.classes_:        Unique labels generated from y
+
+        X and y must represent binary classifiable data.
+        """
+
+        # input data validation
+        random_state = check_random_state(self.random_state)
+        X, y = validate_data(self, X, y)  # type: ignore
+        self.scaler_ = StandardScaler()
+        X_scaled = self.scaler_.fit_transform(X)
+
+        # set unset parameters to their default values
+        if self.weighting_method is None:
+            weighting_method = NoneSampleWeighting()
+        else:
+            weighting_method = self.weighting_method
+        if self.stopping_methods is None:
+            stopping_methods = [
+                CostStoppingMethod(),
+                EarlyStoppingMethod(),
+                EpochStoppingMethod(),
+                TrainStopStoppingMethod(),
+            ]
+        else:
+            stopping_methods = self.stopping_methods
+
+        # create classes and convert them to distinct integers for fitting
+        # the classes are persisted inside the object for use in predict
+        self.classes_ = unique_labels(y)
+        classes_list = list(self.classes_)
+        y_integers = np.array(
+            [classes_list.index(c) for c in y], dtype=np.int32
+        )
+
+        if len(classes_list) != 2:
+            raise ValueError(
+                'Only binary classification is supported but '
+                f'got {len(classes_list)} class(es).'
+            )
+
+        # create and train perceptrons
+        trainer = SimplePerceptronDccpTrainer(
+            self.kind,
+            self.margin,
+            self.penalty,
+            self.validation_ratio,
+            weighting_method,
+            stopping_methods,
+            self.use_dccp_library,
+            self.verbose,
+            random_state,
+        )
+
+        trainer.train(X_scaled, y_integers)
+        self.weights_ = trainer.weights
+
+        return self
+
+    def decision_function(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        X = validate_data(self, X, reset=False)  # type: ignore
+        X_scaled = cast(np.ndarray, self.scaler_.transform(X))
+
+        expr = self.weights_ + X_scaled
+
+        if self.kind == 'max':
+            return expr.max(axis=1)
+        return expr.min(axis=1)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        check_is_fitted(self)
+        return self.classes_[(self.decision_function(X) >= 0).astype(int)]
+
+    def __sklearn_tags__(self):
+        """
+        Overriden method to allow check_estimator to not run accuracy tests.
+        These are designed for perceptrons with a linear decision boundary,
+        which is not the case for a morphological perceptron.
+        """
+
+        tags = super().__sklearn_tags__()
+        tags.classifier_tags.multi_class = False
+        tags.classifier_tags.poor_score = True
+        return tags

sklearn_morpho/stopping/__init__.py

@@ -0,0 +1,7 @@
+from .stopping_base import StoppingMethod as StoppingMethod
+from .stopping_cost import CostStoppingMethod as CostStoppingMethod
+from .stopping_early import EarlyStoppingMethod as EarlyStoppingMethod
+from .stopping_epoch import EpochStoppingMethod as EpochStoppingMethod
+from .stopping_train_stop import (
+    TrainStopStoppingMethod as TrainStopStoppingMethod,
+)

sklearn_morpho/stopping/stopping_base.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+
+
+class StoppingMethod(ABC):
+    """
+    Abstract class for a fitting stopping method.
+    """
+
+    @abstractmethod
+    def requires_validation(self) -> bool:
+        """
+        Whether the stopping method requires the training to be split in
+        train/validation sets.
+
+        Can still be False even if using validation_cost.
+        In fact, the should_stop method should use the validation cost as the
+        main and most reliable cost, in case of no validation it will just be
+        the same as the training cost.
+        """
+
+    @abstractmethod
+    def should_stop(
+        self, n_epochs: int, train_cost: float, validation_cost: float
+    ) -> bool:
+        """
+        Given some information, return whether the fitting process should stop.
+        """

sklearn_morpho/stopping/stopping_cost.py

@@ -0,0 +1,24 @@
+from . import StoppingMethod
+
+
+class CostStoppingMethod(StoppingMethod):
+    """
+    Stopping method that triggers whenever the cost gets lower or equal to the
+    parameter.
+    """
+
+    def __init__(self, cost_threshold=1e-6):
+        if cost_threshold <= 0:
+            raise ValueError(
+                f'invalid done_threshold, expected > 0 but got {cost_threshold}'
+            )
+
+        self.cost_threshold = cost_threshold
+
+    def requires_validation(self) -> bool:
+        return False
+
+    def should_stop(
+        self, n_epochs: int, train_cost: float, validation_cost: float
+    ) -> bool:
+        return validation_cost <= self.cost_threshold