mlquantify 0.1.8__py3-none-any.whl → 0.1.9__py3-none-any.whl

mlquantify/multiclass.py

@@ -0,0 +1,350 @@
+from copy import deepcopy
+import numpy as np
+from abc import abstractmethod
+from mlquantify.base import BaseQuantifier
+from mlquantify.base_aggregative import get_aggregation_requirements
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.base import BaseQuantifier, MetaquantifierMixin
+from mlquantify.utils._validation import validate_prevalences, check_has_method
+
+
+from copy import deepcopy
+from itertools import combinations
+import numpy as np
+from abc import abstractmethod
+from mlquantify.base import BaseQuantifier, MetaquantifierMixin
+from mlquantify.base_aggregative import get_aggregation_requirements
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.utils._validation import validate_prevalences, check_has_method
+
+
+# ============================================================
+# Decorator for enabling binary quantification behavior
+# ============================================================
+def define_binary(cls):
+    """Decorator to enable binary quantification extensions (One-vs-Rest or One-vs-One).
+
+    This decorator dynamically extends a quantifier class to handle multiclass
+    quantification tasks by decomposing them into multiple binary subproblems,
+    following either the One-vs-Rest (OvR) or One-vs-One (OvO) strategy.
+
+    It automatically replaces the class methods `fit`, `predict`, and `aggregate`
+    with binary-aware versions from `BinaryQuantifier`, while preserving access
+    to the original implementations via `_original_fit`, `_original_predict`, 
+    and `_original_aggregate`.
+
+    Parameters
+    ----------
+    cls : class
+        A subclass of `BaseQuantifier` implementing standard binary quantification
+        methods (`fit`, `predict`, and `aggregate`).
+
+    Returns
+    -------
+    class
+        The same class with binary quantification capabilities added.
+
+    Examples
+    --------
+    >>> from mlquantify.base import BaseQuantifier
+    >>> from mlquantify.binary import define_binary
+
+    >>> @define_binary
+    ... class MyQuantifier(BaseQuantifier):
+    ...     def fit(self, X, y):
+    ...         # Custom binary training logic
+    ...         self.classes_ = np.unique(y)
+    ...         return self
+    ...
+    ...     def predict(self, X):
+    ...         # Return dummy prevalences
+    ...         return np.array([0.4, 0.6])
+    ...
+    ...     def aggregate(self, preds, y_train):
+    ...         # Example aggregation method
+    ...         return np.mean(preds, axis=0)
+
+    >>> qtf = MyQuantifier()
+    >>> qtf.strategy = 'ovr'  # or 'ovo'
+    >>> X = np.random.randn(10, 5)
+    >>> y = np.random.randint(0, 3, 10)
+    >>> qtf.fit(X, y)
+    MyQuantifier(...)
+    >>> qtf.predict(X)
+    array([...])
+    """
+    if check_has_method(cls, "fit"):
+        cls._original_fit = cls.fit
+    if check_has_method(cls, "predict"):
+        cls._original_predict = cls.predict
+    if check_has_method(cls, "aggregate"):
+        cls._original_aggregate = cls.aggregate
+
+    cls.fit = BinaryQuantifier.fit
+    cls.predict = BinaryQuantifier.predict
+    cls.aggregate = BinaryQuantifier.aggregate
+
+    return cls
+
+
+# ============================================================
+# Fitting strategies
+# ============================================================
+def _fit_ovr(quantifier, X, y):
+    """Fit using One-vs-Rest (OvR) strategy.
+
+    Creates a binary quantifier for each class, trained to distinguish that class
+    versus all others.
+
+    Parameters
+    ----------
+    quantifier : BaseQuantifier
+        The quantifier instance being trained.
+    X : array-like of shape (n_samples, n_features)
+        Training feature matrix.
+    y : array-like of shape (n_samples,)
+        Class labels.
+
+    Returns
+    -------
+    dict
+        A mapping from class label to fitted binary quantifier.
+    """
+    quantifiers = {}
+    for cls in np.unique(y):
+        qtf = deepcopy(quantifier)
+        y_bin = (y == cls).astype(int)
+        qtf._original_fit(X, y_bin)
+        quantifiers[cls] = qtf
+    return quantifiers
+
+
+def _fit_ovo(quantifier, X, y):
+    """Fit using One-vs-One (OvO) strategy.
+
+    Creates a binary quantifier for every pair of classes, trained to distinguish
+    one class from another.
+
+    Parameters
+    ----------
+    quantifier : BaseQuantifier
+        The quantifier instance being trained.
+    X : array-like of shape (n_samples, n_features)
+        Training feature matrix.
+    y : array-like of shape (n_samples,)
+        Class labels.
+
+    Returns
+    -------
+    dict
+        A mapping from (class1, class2) tuples to fitted binary quantifiers.
+    """
+    quantifiers = {}
+    for cls1, cls2 in combinations(np.unique(y), 2):
+        qtf = deepcopy(quantifier)
+        mask = (y == cls1) | (y == cls2)
+        y_bin = (y[mask] == cls1).astype(int)
+        qtf._original_fit(X[mask], y_bin)
+        quantifiers[(cls1, cls2)] = qtf
+    return quantifiers
+
+
+# ============================================================
+# Prediction strategies
+# ============================================================
+def _predict_ovr(quantifier, X):
+    """Predict using One-vs-Rest (OvR) strategy.
+
+    Each binary quantifier produces a prevalence estimate for its corresponding class.
+
+    Parameters
+    ----------
+    quantifier : BinaryQuantifier
+        Fitted quantifier containing binary models.
+    X : array-like of shape (n_samples, n_features)
+        Test feature matrix.
+
+    Returns
+    -------
+    np.ndarray
+        Predicted prevalences for each class.
+    """
+    preds = np.zeros(len(quantifier.qtfs_))
+    for i, qtf in enumerate(quantifier.qtfs_.values()):
+        preds[i] = qtf._original_predict(X)[1]
+    return preds
+
+
+def _predict_ovo(quantifier, X):
+    """Predict using One-vs-One (OvO) strategy.
+
+    Each binary quantifier outputs a prevalence estimate for the pair of classes it was trained on.
+
+    Parameters
+    ----------
+    quantifier : BinaryQuantifier
+        Fitted quantifier containing binary models.
+    X : array-like of shape (n_samples, n_features)
+        Test feature matrix.
+
+    Returns
+    -------
+    np.ndarray
+        Pairwise prevalence predictions.
+    """
+    preds = np.zeros(len(quantifier.qtfs_))
+    for i, (cls1, cls2) in enumerate(combinations(quantifier.qtfs_.keys(), 2)):
+        qtf = quantifier.qtfs_[(cls1, cls2)]
+        preds[i] = qtf._original_predict(X)[1]
+    return preds
+
+
+# ============================================================
+# Aggregation strategies
+# ============================================================
+def _aggregate_ovr(quantifier, preds, y_train, train_preds=None):
+    """Aggregate binary predictions using One-vs-Rest (OvR).
+
+    Parameters
+    ----------
+    quantifier : BinaryQuantifier
+        Quantifier performing the aggregation.
+    preds : ndarray of shape (n_samples, n_classes)
+        Model predictions.
+    y_train : ndarray of shape (n_samples,)
+        Training labels.
+    train_preds : ndarray of shape (n_samples, n_classes), optional
+        Predictions on the training set.
+
+    Returns
+    -------
+    dict
+        Class-wise prevalence estimates.
+    """
+    prevalences = {}
+    for i, cls in enumerate(np.unique(y_train)):
+        bin_preds = np.column_stack([1 - preds[:, i], preds[:, i]])
+        y_bin = (y_train == cls).astype(int)
+        args = [bin_preds]
+
+        if train_preds is not None:
+            bin_train_preds = np.column_stack([1 - train_preds[:, i], train_preds[:, i]])
+            args.append(bin_train_preds)
+
+        args.append(y_bin)
+        prevalences[cls] = quantifier._original_aggregate(*args)[1]
+    return prevalences
+
+
+def _aggregate_ovo(quantifier, preds, y_train, train_preds=None):
+    """Aggregate binary predictions using One-vs-One (OvO).
+
+    Parameters
+    ----------
+    quantifier : BinaryQuantifier
+        Quantifier performing the aggregation.
+    preds : ndarray
+        Model predictions.
+    y_train : ndarray
+        Training labels.
+    train_preds : ndarray, optional
+        Predictions on the training set.
+
+    Returns
+    -------
+    dict
+        Pairwise prevalence estimates.
+    """
+    prevalences = {}
+    for cls1, cls2 in combinations(np.unique(y_train), 2):
+        bin_preds = np.column_stack([1 - preds[:, (cls1, cls2)], preds[:, (cls1, cls2)]])
+        mask = (y_train == cls1) | (y_train == cls2)
+        y_bin = (y_train[mask] == cls1).astype(int)
+
+        args = [bin_preds]
+        if train_preds is not None:
+            bin_train_preds = np.column_stack([1 - train_preds[:, (cls1, cls2)], train_preds[:, (cls1, cls2)]])
+            args.append(bin_train_preds)
+
+        args.append(y_bin)
+        prevalences[(cls1, cls2)] = quantifier._original_aggregate(*args)[1]
+    return prevalences
+
+
+# ============================================================
+# Main Class
+# ============================================================
+class BinaryQuantifier(MetaquantifierMixin, BaseQuantifier):
+    """Meta-quantifier enabling One-vs-Rest and One-vs-One strategies.
+
+    This class extends a base quantifier to handle multiclass problems by 
+    decomposing them into binary subproblems. It automatically delegates fitting, 
+    prediction, and aggregation operations to the appropriate binary quantifiers.
+
+    Attributes
+    ----------
+    qtfs_ : dict
+        Dictionary mapping class labels or label pairs to fitted binary quantifiers.
+    strategy : {'ovr', 'ovo'}
+        Defines how multiclass quantification is decomposed.
+    """
+
+    @_fit_context(prefer_skip_nested_validation=False)
+    def fit(qtf, X, y):
+        """Fit the quantifier under a binary decomposition strategy."""
+        if len(np.unique(y)) <= 2:
+            qtf.binary = True
+            return qtf._original_fit(X, y)
+
+        qtf.strategy = getattr(qtf, "strategy", "ovr")
+
+        if qtf.strategy == "ovr":
+            qtf.qtfs_ = _fit_ovr(qtf, X, y)
+        elif qtf.strategy == "ovo":
+            qtf.qtfs_ = _fit_ovo(qtf, X, y)
+        else:
+            raise ValueError("Strategy must be 'ovr' or 'ovo'")
+
+        return qtf
+
+    def predict(qtf, X):
+        """Predict class prevalences using the trained binary quantifiers."""
+        if hasattr(qtf, "binary") and qtf.binary:
+            return qtf._original_predict(X)
+        else:
+            if qtf.strategy == "ovr":
+                preds = _predict_ovr(qtf, X)
+            elif qtf.strategy == "ovo":
+                preds = _predict_ovo(qtf, X)
+            else:
+                raise ValueError("Strategy must be 'ovr' or 'ovo'")
+
+        return validate_prevalences(qtf, preds, qtf.qtfs_.keys())
+
+    def aggregate(qtf, *args):
+        """Aggregate binary predictions to obtain multiclass prevalence estimates."""
+        requirements = get_aggregation_requirements(qtf)
+
+        if requirements.requires_train_proba and requirements.requires_train_labels:
+            preds, train_preds, y_train = args
+            args_dict = dict(preds=preds, train_preds=train_preds, y_train=y_train)
+        elif requirements.requires_train_labels:
+            preds, y_train = args
+            args_dict = dict(preds=preds, y_train=y_train)
+        else:
+            raise ValueError("Binary aggregation requires at least train labels")
+
+        classes = np.unique(args_dict["y_train"])
+        qtf.strategy = getattr(qtf, "strategy", "ovr")
+
+        if hasattr(qtf, "binary") and qtf.binary:
+            return qtf._original_aggregate(*args_dict.values())
+
+        if qtf.strategy == "ovr":
+            prevalences = _aggregate_ovr(qtf, **args_dict)
+        elif qtf.strategy == "ovo":
+            prevalences = _aggregate_ovo(qtf, **args_dict)
+        else:
+            raise ValueError("Strategy must be 'ovr' or 'ovo'")
+
+        return validate_prevalences(qtf, prevalences, classes)

mlquantify/neighbors/__init__.py

@@ -0,0 +1,9 @@
+from ._kde import (
+    KDEyCS,
+    KDEyHD,
+    KDEyML,
+)
+
+from ._classes import (
+    PWK,
+)

mlquantify/neighbors/_base.py

@@ -0,0 +1,198 @@
+import numpy as np
+from abc import abstractmethod
+from sklearn.neighbors import KernelDensity
+
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.base import BaseQuantifier
+from mlquantify.utils import validate_y, validate_predictions, validate_data, check_classes_attribute
+from mlquantify.base_aggregative import AggregationMixin, SoftLearnerQMixin, _get_learner_function
+from mlquantify.utils._constraints import Interval, Options
+from mlquantify.utils._get_scores import apply_cross_validation
+from mlquantify.utils._validation import validate_prevalences
+
+EPS = 1e-12
+
+class BaseKDE(SoftLearnerQMixin, AggregationMixin, BaseQuantifier):
+    r"""
+    Base class for KDEy quantification methods.
+    
+    KDEy methods model the class-conditional densities of posterior probabilities
+    using Kernel Density Estimation (KDE) in the probability simplex space.
+    Given a probabilistic classifier's posterior outputs, each class distribution
+    is approximated as a smooth density function via KDE. Class prevalences in
+    the test set are estimated as the mixture weights of these densities that best 
+    explain the test posterior distribution.
+    
+    Formally, KDEy approximates the test posterior distribution as:
+
+    \[
+    p_{test}(x) \approx \sum_{k=1}^K \alpha_k p_k(x),
+    \]
+
+    where \( p_k(x) \) is the KDE of the posterior scores of class \( k \) on training data,
+    and \( \alpha_k \) are the unknown class prevalences to be estimated under:
+
+    \[
+    \alpha_k \geq 0, \quad \sum_{k=1}^K \alpha_k = 1.
+    \]
+    
+    The quantification task is then to find the vector \( \boldsymbol{\alpha} = (\alpha_1,\dots,\alpha_K) \)
+    minimizing an objective function defined on the mixture density and the test posteriors,
+    subject to the simplex constraints on \( \boldsymbol{\alpha} \).
+
+    Attributes
+    ----------
+    learner : estimator
+        The underlying probabilistic classifier yielding posterior predictions.
+    bandwidth : float
+        Bandwidth (smoothing parameter) for the KDE models.
+    kernel : str
+        Kernel type used in KDE (e.g., 'gaussian').
+    _precomputed : bool
+        Indicates whether KDE models have been fitted on training data.
+    best_distance : float or None
+        Stores the best value of the objective (distance or loss) achieved.
+
+    Methods
+    -------
+    fit(X, y, learner_fitted=False)
+        Fits KDE models for each class using posterior predictions of the learner.
+    predict(X)
+        Aggregates learner’s posterior predictions on X to estimate class prevalences.
+    aggregate(predictions, train_predictions, train_y_values)
+        Core estimation method that validates inputs, ensures KDE precomputation,
+        and calls `_solve_prevalences` implemented by subclasses.
+    _fit_kde_models(train_predictions, train_y_values)
+        Fits KDE model per class on training data posteriors.
+    _solve_prevalences(predictions)
+        Abstract method to estimate prevalence vector \( \boldsymbol{\alpha} \) for given posteriors.
+        Must be implemented by subclasses.
+
+    Examples
+    --------
+    To implement a new KDEy quantifier, subclass BaseKDE and implement the method
+    `_solve_prevalences`, which receives posterior predictions and returns a tuple
+
+    (estimated prevalences \(\boldsymbol{\alpha}\), objective value).
+
+    >>> class KDEyExample(BaseKDE):
+    ...     def _solve_prevalences(self, predictions):
+    ...         # Example: simple uniform prevalences, replace with actual optimization
+    ...         n_classes = len(self._class_kdes)
+    ...         alpha = np.ones(n_classes) / n_classes
+    ...         obj_val = 0.0  # Replace with actual objective computation
+    ...         return alpha, obj_val
+
+    Mathematical formulation for prevalence estimation typically involves optimizing:
+
+    \[
+    \min_{\boldsymbol{\alpha} \in \Delta^{K-1}} \mathcal{L} \bigg( \sum_{k=1}^K \alpha_k p_k(x), \hat{p}(x) \bigg),
+    \]
+
+    where \(\hat{p}(x)\) is the test posterior distribution (empirical KDE or direct predictions),
+    \(\Delta^{K-1}\) is the probability simplex defined by the constraints on \(\boldsymbol{\alpha}\),
+    and \(\mathcal{L}\) is an appropriate divergence or loss function, e.g., negative log-likelihood,
+    Hellinger distance, or Cauchy–Schwarz divergence.
+
+    This optimization is typically solved numerically with constrained methods such as
+    sequential quadratic programming or projected gradient descent.
+
+    References
+    ----------
+    [1] Moreo, A., et al. (2023). Kernel Density Quantification methods and applications.
+        In *Learning to Quantify*, Springer.
+    """
+
+    _parameter_constraints = {
+        "bandwidth": [Interval(0, None, inclusive_right=False)],
+        "kernel": [Options(["gaussian", "tophat", "epanechnikov", "exponential", "linear", "cosine"])],
+    }
+
+    def __init__(self, learner=None, bandwidth: float = 0.1, kernel: str = "gaussian"):
+        self.learner = learner
+        self.bandwidth = bandwidth
+        self.kernel = kernel
+        self._precomputed = False
+        self.best_distance = None
+
+    @_fit_context(prefer_skip_nested_validation=True)
+    def fit(self, X, y, learner_fitted=False):
+        X, y = validate_data(self, X, y, ensure_2d=True, ensure_min_samples=2)
+        validate_y(self, y)
+        
+        self.classes_ = np.unique(y)
+        
+        learner_function = _get_learner_function(self)
+
+        if learner_fitted:
+            train_predictions = getattr(self.learner, learner_function)(X)
+            train_y_values = y
+        else:
+            train_predictions, train_y_values = apply_cross_validation(
+                self.learner, X, y,
+                function=learner_function, cv=5,
+                stratified=True, shuffle=True
+            )
+
+        self.train_predictions = train_predictions
+        self.train_y_values = train_y_values
+        self._precompute_training(train_predictions, train_y_values)
+        return self
+
+    def _fit_kde_models(self, train_predictions, train_y_values):
+        P = np.atleast_2d(train_predictions)
+        y = np.asarray(train_y_values)
+        self._class_kdes = []
+
+        for c in self.classes_:
+            Xi = P[y == c]
+            if Xi.shape[0] == 0:
+                Xi = np.ones((1, P.shape[1])) / P.shape[1]  # fallback
+            kde = KernelDensity(bandwidth=self.bandwidth, kernel=self.kernel)
+            kde.fit(Xi)
+            self._class_kdes.append(kde)
+            
+        self._precomputed = True
+
+    def predict(self, X):
+        predictions = getattr(self.learner, _get_learner_function(self))(X)
+        return self.aggregate(predictions, self.train_predictions, self.train_y_values)
+    
+    def aggregate(self, predictions, train_predictions, train_y_values):
+        predictions = validate_predictions(self, predictions)
+        
+        if hasattr(self, "classes_") and len(np.unique(train_y_values)) != len(self.classes_):
+            self._precomputed = False
+        
+        self.classes_ = check_classes_attribute(self, np.unique(train_y_values))
+        
+        if not self._precomputed:
+            self._precompute_training(train_predictions, train_y_values)
+            self._precomputed = True
+            
+        prevalence, _ = self._solve_prevalences(predictions)
+        prevalence = np.clip(prevalence, EPS, None)
+        prevalence = validate_prevalences(self, prevalence, self.classes_)
+        return prevalence
+
+    def best_distance(self, predictions, train_predictions, train_y_values):
+        """Retorna a melhor distância encontrada durante o ajuste."""
+        if self.best_distance is not None:
+            return self.best_distance
+        
+        self.classes_ = check_classes_attribute(self, np.unique(train_y_values))
+        
+        if not self._precomputed:
+            self._precompute_training(train_predictions, train_y_values)
+            self._precomputed = True    
+    
+        _, best_distance = self._solve_prevalences(predictions)
+        return best_distance
+
+    @abstractmethod
+    def _precompute_training(self, train_predictions, train_y_values):
+        raise NotImplementedError
+
+    @abstractmethod
+    def _solve_prevalences(self, predictions):
+        raise NotImplementedError