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

mlquantify/adjust_counting/_base.py

@@ -0,0 +1,245 @@
+import numpy as np
+from abc import abstractmethod
+
+from mlquantify.base import BaseQuantifier
+
+from mlquantify.base_aggregative import (
+    AggregationMixin,
+    _get_learner_function
+)
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.utils._validation import check_classes_attribute, validate_predictions, validate_y, validate_data, validate_prevalences
+from mlquantify.utils._get_scores import apply_cross_validation
+
+
+
+
+class BaseCount(AggregationMixin, BaseQuantifier):
+    r"""Base class for count-based quantifiers.
+
+    Implements the foundation for *count-based quantification* methods,
+    where class prevalences are estimated directly from classifier outputs
+    without any correction.
+
+    The method assumes a classifier :math:`f(x)` producing either hard or
+    probabilistic predictions. The prevalence of each class :math:`c` in
+    the unlabeled test set is estimated as:
+
+    .. math::
+        \hat{\pi}_c = \frac{1}{N} \sum_{i=1}^{N} I(f(x_i) = c)
+
+    for *hard* classifiers, or equivalently as:
+
+    .. math::
+        \hat{\pi}_c = \frac{1}{N} \sum_{i=1}^{N} f_c(x_i)
+
+    for *soft* classifiers where :math:`f_c(x)` denotes the posterior
+    probability of class :math:`c`.
+
+    This is the classical *Classify and Count (CC)* and *Probabilistic
+    Classify and Count (PCC)* approach, introduced by Forman (2005, 2008)
+    and unified in the constrained regression framework of Firat et al. (2016).
+
+    Parameters
+    ----------
+    learner : object, optional
+        A supervised learning model implementing `fit` and `predict`
+        or `predict_proba`.
+
+    Attributes
+    ----------
+    learner : object
+        Underlying classification model.
+    classes : ndarray of shape (n_classes,)
+        Unique class labels observed during training.
+
+    Examples
+    --------
+    >>> from mlquantify.base_count import BaseCount
+    >>> from mlquantify.utils.validation import validate_prevalences
+    >>> import numpy as np
+
+    >>> class CC(CrispLearnerQMixin, BaseCount):
+    ...     def __init__(self, learner=None, threshold=0.5):
+    ...         super().__init__(learner)
+    ...         self.threshold = threshold
+    ...     def aggregate(self, predictions):
+    ...         predictions = validate_predictions(self, predictions)
+    ...         self.classes = self.classes if hasattr(self, 'classes') else np.unique(predictions)
+    ...         counts = np.array([np.count_nonzero(predictions == c) for c in self.classes])
+    ...         prevalences = counts / len(predictions)
+    ...         return validate_prevalences(self, prevalences, self.classes)
+
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> X = np.random.randn(100, 5)
+    >>> y = np.random.randint(0, 2, 100)
+    >>> q = CC(learner=LogisticRegression())
+    >>> q.fit(X, y)
+    >>> q.predict(X).round(3)
+    array([0.47, 0.53])
+
+    References
+    ----------
+    [1] Forman, G. (2005). *Counting Positives Accurately Despite Inaccurate Classification.*
+        ECML, pp. 564-575.
+    [2] Forman, G. (2008). *Quantifying Counts and Costs via Classification.*
+        Data Mining and Knowledge Discovery, 17(2), 164-206.
+    """
+
+    @abstractmethod
+    def __init__(self, learner=None):
+        self.learner = learner
+        
+    def __mlquantify_tags__(self):
+        tags = super().__mlquantify_tags__()
+        tags.prediction_requirements.requires_train_proba = False
+        tags.prediction_requirements.requires_train_labels = False
+        return tags
+
+    @_fit_context(prefer_skip_nested_validation=True)
+    def fit(self, X, y, learner_fitted=False, *args, **kwargs):
+        """Fit the quantifier using the provided data and learner."""
+        X, y = validate_data(self, X, y)
+        validate_y(self, y)
+        self.classes_ = np.unique(y)
+        if not learner_fitted:
+            self.learner.fit(X, y, *args, **kwargs)
+        return self
+    
+    def predict(self, X):
+        """Predict class prevalences for the given data."""
+        estimator_function = _get_learner_function(self)
+        predictions = getattr(self.learner, estimator_function)(X)
+        prevalences = self.aggregate(predictions)
+        return prevalences
+    
+    @abstractmethod
+    def aggregate(self, predictions):
+        """Aggregate predictions into class prevalence estimates."""
+        ...
+
+
+class BaseAdjustCount(AggregationMixin, BaseQuantifier):
+    r"""Base class for adjustment-based quantifiers.
+
+    This class generalizes *adjusted count* quantification methods,
+    providing a framework for correcting bias in raw classifier outputs
+    based on estimated confusion matrices or rate statistics.
+
+    Following Forman (2005, 2008), in the binary case the correction
+    uses true positive (TPR) and false positive (FPR) rates to adjust
+    the observed positive proportion :math:`\hat{p}'_{+}`:
+
+    .. math::
+        \hat{p}_{+} = \frac{\hat{p}'_{+} - \text{FPR}}{\text{TPR} - \text{FPR}}
+
+    In the multiclass extension (Firat et al., 2016), the same principle
+    can be expressed using matrix algebra. Let :math:`C` denote the
+    normalized confusion matrix where :math:`C_{ij} = P(\hat{y}=i|y=j)`
+    estimated via cross-validation. Then, given the observed distribution
+    of predictions :math:`\hat{\pi}'`, the corrected prevalence vector
+    :math:`\hat{\pi}` is obtained as:
+
+    .. math::
+        \hat{\pi}' = C \hat{\pi}
+        \quad \Rightarrow \quad
+        \hat{\pi} = C^{-1} \hat{\pi}'
+
+    subject to non-negativity and unit-sum constraints:
+
+    .. math::
+        \hat{\pi}_c \ge 0, \quad \sum_c \hat{\pi}_c = 1
+
+    This formulation can be solved via constrained least squares
+    (L2), least absolute deviation (L1), or Hellinger divergence
+    minimization, as discussed by Firat et al. (2016).
+
+    Parameters
+    ----------
+    learner : object, optional
+        Supervised learner implementing `fit`, `predict`, or `predict_proba`.
+
+    Attributes
+    ----------
+    learner : object
+        Underlying classification model.
+    train_predictions : ndarray of shape (n_samples_train, n_classes)
+        Predictions on training data from cross-validation.
+    train_y_values : ndarray of shape (n_samples_train,)
+        True labels corresponding to training predictions.
+    classes : ndarray of shape (n_classes,)
+        Unique class labels.
+
+    Examples
+    --------
+    >>> from mlquantify.base_count import BaseAdjustCount
+    >>> import numpy as np
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> class ACC(CrispLearnerQMixin, BaseAdjustCount):
+    ...     def _adjust(self, preds, train_preds, y_train):
+    ...         tpr = np.mean(train_preds[y_train == 1])
+    ...         fpr = np.mean(train_preds[y_train == 0])
+    ...         p_obs = np.mean(preds)
+    ...         p_adj = (p_obs - fpr) / (tpr - fpr)
+    ...         return np.clip([1 - p_adj, p_adj], 0, 1)
+    >>> X = np.random.randn(100, 5)
+    >>> y = np.random.randint(0, 2, 100)
+    >>> q = ACC(learner=LogisticRegression())
+    >>> q.fit(X, y)
+    >>> q.predict(X).round(3)
+    array([0.52, 0.48])
+
+    References
+    ----------
+    [1] Forman, G. (2005). *Counting Positives Accurately Despite Inaccurate Classification.*
+        ECML 2005, LNAI 3720, pp. 564-575.
+    [2] Forman, G. (2008). *Quantifying Counts and Costs via Classification.*
+        Data Mining and Knowledge Discovery, 17(2), 164-206.
+    [3] Firat, A. (2016). *Unified Framework for Quantification.*
+        Proceedings of the AAAI Conference on Artificial Intelligence, Sections 3.2-3.3.
+    """
+
+    @abstractmethod
+    def __init__(self, learner=None):
+        self.learner = learner
+
+    @_fit_context(prefer_skip_nested_validation=True)
+    def fit(self, X, y, learner_fitted=False):
+        """Fit the quantifier using the provided data and learner."""
+        X, y = validate_data(self, X, y)
+        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)
+            y_train_labels = y
+        else:
+            train_predictions, y_train_labels = apply_cross_validation(
+                self.learner,
+                X,
+                y,
+                function=learner_function,
+                cv=5,
+                stratified=True,
+                random_state=None,
+                shuffle=True
+            )
+        
+        self.train_predictions = train_predictions
+        self.train_y_values = y_train_labels
+        return self
+    
+    def predict(self, X):
+        """Predict class prevalences for the given data."""
+        predictions = getattr(self.learner, _get_learner_function(self))(X)
+        prevalences = self.aggregate(predictions, self.train_predictions, self.train_y_values)
+        return prevalences
+
+    def aggregate(self, predictions, train_predictions, y_train_values):
+        """Aggregate predictions and apply matrix- or rate-based bias correction."""
+        self.classes_ = check_classes_attribute(self, np.unique(y_train_values))
+        predictions = validate_predictions(self, train_predictions)
+        prevalences = self._adjust(predictions, train_predictions, y_train_values)
+        prevalences = validate_prevalences(self, prevalences, self.classes_)
+        return prevalences

mlquantify/adjust_counting/_counting.py

@@ -0,0 +1,153 @@
+import numpy as np
+
+from mlquantify.base_aggregative import (
+    SoftLearnerQMixin,
+    CrispLearnerQMixin
+)
+
+from mlquantify.adjust_counting._base import BaseCount
+from mlquantify.utils._validation import validate_predictions, validate_prevalences, check_classes_attribute
+from mlquantify.utils._constraints import Interval
+        
+
+
+class CC(CrispLearnerQMixin, BaseCount):
+    r"""Classify and Count (CC) quantifier.
+
+    Implements the Classify and Count method for quantification, describe as a
+    baseline approach in the literature [1][2].
+
+    Parameters
+    ----------
+    learner : estimator, optional
+        A supervised learning estimator with `fit` and `predict` methods.
+        If None, it is expected that the aggregate method is used directly.
+    threshold : float, default=0.5
+        Decision threshold for converting predicted probabilities into class labels.
+        Must be in the interval [0.0, 1.0].
+
+    Attributes
+    ----------
+    learner : estimator
+        Underlying classification model.
+
+    Notes
+    -----
+    The Classify and Count approach performs quantification by classifying each instance 
+    using the classifier's predicted labels at a given threshold, then counting the 
+    prevalence of each class.
+
+    This method can be biased when class distributions differ between training and test sets,
+    motivating further adjustment methods.
+
+    Examples
+    --------
+    >>> from mlquantify.adjust_counting import CC
+    >>> import numpy as np
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> X = np.random.randn(100, 5)
+    >>> y = np.random.randint(0, 2, 100)
+    >>> q = CC(learner=LogisticRegression())
+    >>> q.fit(X, y)
+    >>> q.predict(X)
+    {0: 0.47, 1: 0.53}
+    >>> q2 = CC()
+    >>> predictions = np.random.rand(200)
+    >>> q2.aggregate(predictions)
+    {0: 0.51, 1: 0.49}
+
+    References
+    ----------
+    .. [1] Forman, G. (2005). "Counting Positives Accurately Despite Inaccurate Classification",
+           *ECML*, pp. 564-575.
+    .. [2] Forman, G. (2008). "Quantifying Counts and Costs via Classification",
+           *Data Mining and Knowledge Discovery*, 17(2), 164-206.
+    """
+    
+    _parameters_constraints = {
+        "threshold": [
+            Interval(0.0, 1.0),
+            Interval(0, 1, discrete=True),
+        ],
+    }
+
+    def __init__(self, learner=None, threshold=0.5):
+        super().__init__(learner=learner)
+        self.threshold = threshold
+
+    def aggregate(self, predictions):
+        predictions = validate_predictions(self, predictions)
+        
+        self.classes_ = check_classes_attribute(self, np.unique(predictions))
+        class_counts = np.array([np.count_nonzero(predictions == _class) for _class in self.classes_])
+        prevalences = class_counts / len(predictions)
+        
+        prevalences = validate_prevalences(self, prevalences, self.classes_)
+        return prevalences
+
+
+class PCC(SoftLearnerQMixin, BaseCount):
+    r"""Probabilistic Classify and Count (PCC) quantifier.
+    
+    Implements the Probabilistic Classify and Count method for quantification as described in:
+    [1] Forman, G. (2005). *Counting Positives Accurately Despite Inaccurate Classification.*
+        ECML, pp. 564-575.
+    [2] Forman, G. (2008). *Quantifying Counts and Costs via Classification.*
+        Data Mining and Knowledge Discovery, 17(2), 164-206.
+        
+        
+    Parameters
+    ----------
+    learner : estimator, optional
+        A supervised learning estimator with fit and predict_proba methods.
+        If None, it is expected that will be used the aggregate method directly.
+        
+        
+    Attributes
+    ----------
+    learner : estimator
+        Underlying classification model.
+    classes : ndarray of shape (n_classes,)
+        Unique class labels observed during training.
+        
+        
+    Examples
+    --------
+    >>> from mlquantify.adjust_counting import PCC
+    >>> import numpy as np
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> X = np.random.randn(100, 5)
+    >>> y = np.random.randint(0, 2, 100)
+    >>> q = PCC(learner=LogisticRegression())
+    >>> q.fit(X, y)
+    >>> q.predict(X)
+    {0: 0.48, 1: 0.52}
+    >>> q2 = PCC()
+    >>> predictions = np.random.rand(200, 2)
+    >>> q2.aggregate(predictions)
+    {0: 0.50, 1: 0.50}
+    """
+
+    def __init__(self, learner=None):
+        super().__init__(learner=learner)
+
+    def aggregate(self, predictions):
+        predictions = validate_predictions(self, predictions)
+        
+        # Handle categorical predictions (1D array with class labels)
+        if predictions.ndim == 1 and not np.issubdtype(predictions.dtype, (np.floating, np.integer)):
+            self.classes_ = check_classes_attribute(self, np.unique(predictions))
+            class_counts = np.array([np.count_nonzero(predictions == _class) for _class in self.classes_])
+            prevalences = class_counts / len(predictions)
+        else:
+            # Handle probability predictions (2D array or 1D probabilities)
+            if predictions.ndim == 2:
+                self.classes_ = check_classes_attribute(self, np.arange(predictions.shape[1]))
+            else:
+                self.classes_ = check_classes_attribute(self, np.arange(2))
+            prevalences = np.mean(predictions, axis=0) if predictions.ndim == 2 else predictions.mean()
+            if predictions.ndim == 1:
+                prevalences = np.array([1-prevalences, prevalences])
+        
+        prevalences = validate_prevalences(self, prevalences, self.classes_)
+        return prevalences

mlquantify/adjust_counting/_utils.py

@@ -0,0 +1,109 @@
+import numpy as np
+
+
+def compute_table(y, y_pred, classes):
+    r"""Compute the confusion matrix table for a binary classification task.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The true labels.
+    y_pred : np.ndarray
+        The predicted labels.
+    classes : np.ndarray
+        The unique classes in the dataset.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the counts of True Positives, False Positives,
+        False Negatives, and True Negatives respectively.
+    """
+    TP = np.logical_and(y == y_pred, y == classes[1]).sum()
+    FP = np.logical_and(y != y_pred, y == classes[0]).sum()
+    FN = np.logical_and(y != y_pred, y == classes[1]).sum()
+    TN = np.logical_and(y == y_pred, y == classes[0]).sum()
+    return TP, FP, FN, TN
+
+
+def compute_tpr(TP, FN):
+    r"""Compute the True Positive Rate (Recall) for a binary classification task.
+
+    Parameters
+    ----------
+    TP : int
+        The number of True Positives.
+    FN : int
+        The number of False Negatives.
+
+    Returns
+    -------
+    float
+        The True Positive Rate (Recall).
+    """
+    if TP + FN == 0:
+        return 0
+    return TP / (TP + FN)
+
+
+def compute_fpr(FP, TN):
+    r"""Compute the False Positive Rate for a binary classification task.
+
+    Parameters
+    ----------
+    FP : int
+        The number of False Positives.
+    TN : int
+        The number of True Negatives.
+
+    Returns
+    -------
+    float
+        The False Positive Rate.
+    """
+    if FP + TN == 0:
+        return 0
+    return FP / (FP + TN)
+
+
+def evaluate_thresholds (y, probabilities:np.ndarray) -> tuple:
+    r"""Evaluate a range of classification thresholds to compute the corresponding
+    True Positive Rate (TPR) and False Positive Rate (FPR) for a binary quantification task.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The true labels.
+    probabilities : np.ndarray
+        The predicted probabilities (scores) for the positive class.
+    classes : np.ndarray
+        The unique classes in the dataset.
+
+    Returns
+    -------
+    tuple
+        A tuple of (thresholds, tprs, fprs), where:
+        - thresholds is a numpy array of evaluated thresholds,
+        - tprs is a numpy array of corresponding True Positive Rates,
+        - fprs is a numpy array of corresponding False Positive Rates.
+    """
+    unique_scores = np.linspace(0, 1, 101)
+    
+    tprs = []
+    fprs = []
+    
+    classes = np.unique(y)
+    
+    for threshold in unique_scores:
+        y_pred = np.where(probabilities >= threshold, classes[1], classes[0])
+        
+        TP, FP, FN, TN = compute_table(y, y_pred, classes)
+        
+        tpr = compute_tpr(TP, FN)
+        fpr = compute_fpr(FP, TN)
+        
+        tprs.append(tpr)
+        fprs.append(fpr)
+    
+    #best_tpr, best_fpr = self.adjust_threshold(np.asarray(tprs), np.asarray(fprs))
+    return (unique_scores, np.asarray(tprs), np.asarray(fprs))