mlquantify 0.1.8__py3-none-any.whl → 0.1.10__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,168 @@
+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 models the class-conditional densities of posterior probabilities using Kernel Density Estimation (KDE)
+    on the probability simplex. Given posterior outputs from a probabilistic classifier, each class distribution
+    is approximated as a smooth KDE. Test set class prevalences correspond to mixture weights that best explain 
+    the overall test posterior distribution.
+
+    Mathematically, the test posterior distribution is approximated as:
+
+    .. math::
+
+        p_{\mathrm{test}}(x) \approx \sum_{k=1}^K \alpha_k p_k(x),
+
+    where \(p_k(x)\) is the KDE of class \(k\) posteriors from training data, and \(\alpha_k\) are the unknown class 
+    prevalences subject to:
+
+    .. math::
+
+        \alpha_k \geq 0, \quad \sum_{k=1}^K \alpha_k = 1.
+
+    The quantification minimizes an objective \(\mathcal{L}\) over \(\boldsymbol{\alpha} = (\alpha_1, \dots, \alpha_K)\) in the simplex:
+
+    .. math::
+
+        \min_{\boldsymbol{\alpha} \in \Delta^{K-1}} \mathcal{L} \left( \sum_{k=1}^K \alpha_k p_k(x), \hat{p}(x) \right),
+
+    where \(\hat{p}(x)\) is the test posterior distribution (empirical KDE or direct predictions).
+
+    This problem is typically solved using numerical constrained optimization methods.
+
+    Attributes
+    ----------
+    learner : estimator
+        Probabilistic classifier generating posterior predictions.
+    bandwidth : float
+        KDE bandwidth (smoothing parameter).
+    kernel : str
+        KDE kernel type (e.g., 'gaussian').
+    _precomputed : bool
+        Indicates if KDE models have been fitted.
+    best_distance : float or None
+        Best objective value found during estimation.
+
+    Examples
+    --------
+    Subclasses should implement `_solve_prevalences` method returning estimated prevalences and objective value:
+
+    >>> class KDEyExample(BaseKDE):
+    ...     def _solve_prevalences(self, predictions):
+    ...         n_classes = len(self._class_kdes)
+    ...         alpha = np.ones(n_classes) / n_classes
+    ...         obj_val = 0.0  # Placeholder, replace with actual objective
+    ...         return alpha, obj_val
+
+    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

mlquantify/neighbors/_classes.py

@@ -0,0 +1,150 @@
+import numpy as np
+from mlquantify.utils._constraints import Interval, Options
+from mlquantify.neighbors._classification import PWKCLF
+from mlquantify.base_aggregative import AggregationMixin, CrispLearnerQMixin
+from mlquantify.base import BaseQuantifier
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.adjust_counting import CC
+from mlquantify.utils import validate_y, validate_data
+from mlquantify.utils._validation import validate_prevalences
+
+
+class PWK(BaseQuantifier):
+    r"""
+    Probabilistic Weighted k-Nearest Neighbor (PWK) Quantifier.
+
+    This quantifier leverages the PWKCLF classifier to perform quantification by estimating 
+    class prevalences through a probabilistically weighted k-nearest neighbor approach.
+
+    The method internally uses a weighted k-NN classifier where neighbors' contributions 
+    are adjusted by class-specific weights designed to correct for class imbalance,
+    controlled by the hyperparameter alpha.
+
+    Parameters
+    ----------
+    alpha : float, default=1
+        Imbalance correction exponent for class weights. Higher values increase 
+        the influence of minority classes.
+    n_neighbors : int, default=10
+        Number of nearest neighbors considered.
+    algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, default='auto'
+        Algorithm used to compute nearest neighbors.
+    metric : str, default='euclidean'
+        Distance metric for nearest neighbor search.
+    leaf_size : int, default=30
+        Leaf size for tree-based neighbors algorithms.
+    p : int, default=2
+        Power parameter for the Minkowski metric (when metric='minkowski').
+    metric_params : dict or None, default=None
+        Additional parameters for the metric function.
+    n_jobs : int or None, default=None
+        Number of parallel jobs for neighbors search.
+
+    Attributes
+    ----------
+    cc : object
+        Internally used Classify & Count quantifier wrapping PWKCLF.
+    learner : PWKCLF
+        Underlying probabilistic weighted k-NN classifier.
+
+
+    Examples
+    --------
+    >>> q = PWK(alpha=1.5, n_neighbors=5)
+    >>> q.fit(X_train, y_train)
+    >>> prevalences = q.predict(X_test)
+    """
+    
+    _parameter_constraints = {
+        "alpha": [Interval(1, None, inclusive_right=False)],
+        "n_neighbors": [Interval(1, None, inclusive_right=False)],
+        "algorithm": [Options(["auto", "ball_tree", "kd_tree", "brute"])],
+        "metric": [str],
+        "leaf_size": [Interval(1, None, inclusive_right=False)],
+        "p": [Interval(1, None, inclusive_right=False)],
+        "metric_params": [dict, type(None)],
+        "n_jobs": [Interval(1, None, inclusive_right=False), type(None)],
+    }
+    
+    def __init__(self,
+                 alpha=1,
+                 n_neighbors=10,
+                 algorithm="auto",
+                 metric="euclidean",
+                 leaf_size=30,
+                 p=2,
+                 metric_params=None,
+                 n_jobs=None):
+        learner = PWKCLF(alpha=alpha,
+                         n_neighbors=n_neighbors,
+                         algorithm=algorithm,
+                         metric=metric,
+                         leaf_size=leaf_size,
+                         p=p,
+                         metric_params=metric_params,
+                         n_jobs=n_jobs)
+        self.algorithm = algorithm
+        self.alpha = alpha
+        self.n_neighbors = n_neighbors
+        self.metric = metric
+        self.leaf_size = leaf_size
+        self.p = p
+        self.metric_params = metric_params
+        self.n_jobs = n_jobs
+        self.learner = learner
+        
+    @_fit_context(prefer_skip_nested_validation=True)
+    def fit(self, X, y):
+        """Fit the PWK quantifier to the training data.
+        
+        Parameters
+        ----------
+        X_train : array-like of shape (n_samples, n_features)
+            Training features.
+        
+        y_train : array-like of shape (n_samples,)
+            Training labels.
+        
+        Returns
+        -------
+        self : object
+            The fitted instance.
+        """
+        X, y = validate_data(self, X, y, ensure_2d=True, ensure_min_samples=2)
+        validate_y(self, y)
+        self.classes_ = np.unique(y)
+        self.cc = CC(self.learner)
+        return self.cc.fit(X, y)
+    
+    def predict(self, X):
+        """Predict prevalences for the given data.
+        
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Features for which to predict prevalences.
+        
+        Returns
+        -------
+        prevalences : array of shape (n_classes,)
+            Predicted class prevalences.
+        """
+        prevalences = self.cc.predict(X)
+        prevalences = validate_prevalences(self, prevalences, self.classes_)
+        return prevalences
+    
+    def classify(self, X):
+        """Classify samples using the underlying learner.
+        
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Features to classify.
+        
+        Returns
+        -------
+        labels : array of shape (n_samples,)
+            Predicted class labels.
+        """
+        return self.learner.predict(X)
+