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

mlquantify/likelihood/_base.py

@@ -0,0 +1,161 @@
+import numpy as np
+from abc import abstractmethod
+
+from mlquantify.base import BaseQuantifier
+
+from mlquantify.base_aggregative import (
+    AggregationMixin,
+    _get_learner_function
+)
+from mlquantify.adjust_counting import CC
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.utils._validation import check_classes_attribute, validate_predictions, validate_y, validate_data, validate_prevalences
+
+
+
+class BaseIterativeLikelihood(AggregationMixin, BaseQuantifier):
+    """
+    Iterative, likelihood-based quantification via EM adjustment.
+    
+    This is the base class for quantification methods that estimate class prevalences
+    by solving the maximum likelihood problem under prior probability shift, using
+    iterative procedures such as the EM (Expectation-Maximization) algorithm 
+    [1], [2].
+    
+    These methods repeatedly adjust the estimated class prevalences for a test set
+    by maximizing the likelihood of observed classifier outputs (posterior probabilities),
+    under the assumption that the within-class conditional distributions remain fixed
+    between training and test domains.
+    
+    Mathematical formulation
+    ------------------------
+    Let:
+    - \( p_k^t \) denote the prior probability for class \( k \) in the training set (\( \sum_k p_k^t = 1 \)),
+    - \( s_k(x) \) be the classifier's posterior probability estimate (for class \( k \), given instance \( x \), fitted on training set),
+    - \( p_k \) be the (unknown) prior for the test set,
+    - \( x_1, \dots, x_N \) the unlabeled test set instances.
+
+    The procedure iteratively estimates \( p_k \) by maximizing the observed data likelihood
+
+    \[
+    L = \prod_{i=1}^N \sum_{k=1}^K s_k(x_i) \frac{p_k}{p_k^t}
+    \]
+    
+    The E-step updates soft memberships:
+
+    \[
+    w_{ik}^{(t)} = \frac{s_k(x_i) \cdot (p_k^{(t-1)} / p_k^t)}{\sum_{j=1}^K s_j(x_i) \cdot (p_j^{(t-1)} / p_j^t)}
+    \]
+    and the M-step re-estimates prevalences:
+
+    \[
+    p_k^{(t)} = \frac{1}{N} \sum_{i=1}^N w_{ik}^{(t)}
+    \]
+    See also [1].
+
+    Notes
+    -----
+    - Defined for multiclass and binary quantification (single-label), as long as the classifier provides well-calibrated posterior probabilities.
+    - Assumes prior probability shift only.
+    - Converges to a (local) maximum of the data likelihood.
+    - The algorithm is Fisher-consistent under prior probability shift [2].
+    - Closely related to the Expectation-Maximization (EM) algorithm for mixture models.
+
+    Parameters
+    ----------
+    learner : estimator, optional
+        Probabilistic classifier instance with `fit(X, y)` and `predict_proba(X)`.
+    tol : float, default=1e-4
+        Convergence tolerance for prevalence update.
+    max_iter : int, default=100
+        Maximum number of EM update iterations.
+
+    Attributes
+    ----------
+    learner : estimator
+        Underlying classifier instance.
+    tol : float
+        Stopping tolerance for EM prevalence estimation.
+    max_iter : int
+        Maximum updates performed.
+    classes : ndarray of shape (n_classes,)
+        Unique class labels seen in training.
+    priors : ndarray of shape (n_classes,)
+        Class distribution of the training set.
+    y_train : array-like
+        Training labels (used for estimating priors and confusion matrix if needed).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> class MyEM(BaseIterativeLikelihood):
+    ...     def _iterate(self, predictions, priors):
+    ...         # EM iteration logic here
+    ...         pass
+    >>> X = np.random.randn(200, 8)
+    >>> y = np.random.randint(0, 3, size=(200,))
+    >>> q = MyEM(learner=LogisticRegression(max_iter=200))
+    >>> q.fit(X, y)
+    >>> q.predict(X)
+    {0: 0.32, 1: 0.40, 2: 0.28}
+
+    References
+    ----------
+    [1] Saerens, M., Latinne, P., & Decaestecker, C. (2002). *Adjusting the Outputs of a Classifier to New a Priori Probabilities: A Simple Procedure.* Neural Computation, 14(1), 2141-2156.
+    
+    [2] Esuli, A., Moreo, A., & Sebastiani, F. (2023). *Learning to Quantify.* The Information Retrieval Series 47, Springer. https://doi.org/10.1007/978-3-031-20467-8
+    """
+
+
+
+    @abstractmethod
+    def __init__(self, 
+                 learner=None,
+                 tol=1e-4,
+                 max_iter=100):
+        self.learner = learner
+        self.tol = tol
+        self.max_iter = max_iter
+        
+    def __mlquantify_tags__(self):
+        tags = super().__mlquantify_tags__()
+        tags.prediction_requirements.requires_train_proba = False
+        return tags
+    
+    
+    @_fit_context(prefer_skip_nested_validation=True)
+    def fit(self, X, y):
+        """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)
+        self.learner.fit(X, y)
+        counts = np.array([np.count_nonzero(y == _class) for _class in self.classes_])
+        self.priors = counts / len(y)
+        self.y_train = y
+                
+        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, self.y_train)
+        return prevalences
+
+    def aggregate(self, predictions, y_train):
+        predictions = validate_predictions(self, predictions)
+        self.classes_ = check_classes_attribute(self, np.unique(y_train))
+        
+        if not hasattr(self, 'priors') or len(self.priors) != len(self.classes_):
+            counts = np.array([np.count_nonzero(y_train == _class) for _class in self.classes_])
+            self.priors = counts / len(y_train)
+            
+        prevalences = self._iterate(predictions, self.priors)
+        prevalences = validate_prevalences(self, prevalences, self.classes_)
+        return prevalences
+    
+    @abstractmethod
+    def _iterate(self, predictions, priors):
+        ...

mlquantify/likelihood/_classes.py

@@ -0,0 +1,414 @@
+import numpy as np
+from mlquantify.base_aggregative import SoftLearnerQMixin
+from mlquantify.likelihood._base import BaseIterativeLikelihood
+from mlquantify.metrics._slq import MAE
+from mlquantify.multiclass import define_binary
+from mlquantify.utils._constraints import (
+    Interval,
+    CallableConstraint,
+    Options
+)
+
+class EMQ(SoftLearnerQMixin, BaseIterativeLikelihood):
+    """Expectation-Maximization Quantifier.
+    
+    Implements iterative quantification using an EM algorithm to adjust class
+    prevalences under prior probability shift, assimilating posterior probabilities
+    (soft predictions) from a probabilistic classifier.
+    
+    The EM procedure alternates between estimating posterior memberships of test
+    instances (E-step) and re-estimating class prevalences (M-step), iterating until
+    convergence (tolerance or max iterations) on prevalence change measured by a
+    user-defined criteria (default: Mean Absolute Error, MAE).
+    
+    Supports optional calibration of predicted posteriors before iteration.
+    
+    Parameters
+    ----------
+    learner : estimator, optional
+        Probabilistic classifier fit on training data with `predict_proba`.
+    tol : float, default=1e-4
+        Convergence threshold for EM iterative updates.
+    max_iter : int, default=100
+        Maximum number of EM iterations.
+    calib_function : str or callable, optional
+        Calibration method applied to posterior probabilities.
+        Supported strings: 'bcts', 'ts', 'vs', 'nbvs'.
+    criteria : callable, default=MAE
+        Function to measure convergence between prevalence estimates.
+        
+    Methods
+    -------
+    _iterate(predictions, priors)
+        Executes EM iterations to estimate prevalences from posterior probabilities.
+    EM(posteriors, priors, tolerance, max_iter, criteria)
+        Static method implementing the EM loop with E-step and M-step.
+    _apply_calibration(predictions)
+        Applies optional calibration method to posterior predictions.
+    
+    References
+    ----------
+    [1] Saerens et al. (2002). Adjusting the Outputs of a Classifier to New a Priori Probabilities. Neural Computation, 14(1), 2141-2156.
+    [2] Esuli et al. (2023). Learning to Quantify. Springer.
+    """
+
+    _parameter_constraints = {
+        "tol": [Interval(0, None, inclusive_left=False)],
+        "max_iter": [Interval(1, None, inclusive_left=True)],
+        "calib_function": [
+            Options(["bcts", "ts", "vs", "nbvs", None]),
+        ],
+        "criteria": [CallableConstraint()],
+    }
+
+    def __init__(self, 
+                 learner=None, 
+                 tol=1e-4, 
+                 max_iter=100, 
+                 calib_function=None,
+                 criteria=MAE):
+        super().__init__(learner=learner, tol=tol, max_iter=max_iter)
+        self.calib_function = calib_function
+        self.criteria = criteria
+        
+    def _iterate(self, predictions, priors):
+        """
+        Perform EM quantification iteration.
+        
+        Steps:
+        - Calibrate posterior predictions if calibration function specified.
+        - Apply EM procedure to re-estimate prevalences, based on training priors and calibrated posteriors.
+        
+        Parameters
+        ----------
+        predictions : ndarray of shape (n_samples, n_classes)
+            Posterior probabilities for each class on test data.
+        priors : ndarray of shape (n_classes,)
+            Training set class prevalences, serving as initial priors.
+        
+        Returns
+        -------
+        prevalences : ndarray of shape (n_classes,)
+            Estimated class prevalences after EM iteration.
+        """
+        calibrated_predictions = self._apply_calibration(predictions)
+        prevalences, _ = self.EM(
+            posteriors=calibrated_predictions,
+            priors=priors,
+            tolerance=self.tol,
+            max_iter=self.max_iter,
+            criteria=self.criteria
+        )
+        return prevalences
+
+
+    @classmethod
+    def EM(cls, posteriors, priors, tolerance=1e-6, max_iter=100, criteria=MAE):
+        """
+        Static method implementing the EM algorithm for quantification.
+
+        Parameters
+        ----------
+        posteriors : ndarray of shape (n_samples, n_classes)
+            Posterior probability predictions.
+        priors : ndarray of shape (n_classes,)
+            Training class prior probabilities.
+        tolerance : float
+            Convergence threshold based on difference between iterations.
+        max_iter : int
+            Max number of EM iterations.
+        criteria : callable
+            Metric to assess convergence, e.g., MAE.
+
+        Returns
+        -------
+        qs : ndarray of shape (n_classes,)
+            Estimated test set class prevalences.
+        ps : ndarray of shape (n_samples, n_classes)
+            Updated soft membership probabilities per instance.
+        """
+        
+        Px = np.array(posteriors, dtype=np.float64)
+        Ptr = np.array(priors, dtype=np.float64)
+        
+        
+
+        if np.prod(Ptr) == 0:
+            Ptr += tolerance
+            Ptr /= Ptr.sum()
+
+        qs = np.copy(Ptr)
+        s, converged = 0, False
+        qs_prev_ = None
+        
+        while not converged and s < max_iter:
+            # E-step:
+            ps_unnormalized = (qs / Ptr) * Px
+            ps = ps_unnormalized / ps_unnormalized.sum(axis=1, keepdims=True)
+
+            # M-step:
+            qs = ps.mean(axis=0)
+
+            if qs_prev_ is not None and criteria(qs_prev_, qs) < tolerance and s > 10:
+                converged = True
+
+            qs_prev_ = qs
+            s += 1
+
+        if not converged:
+            print('[warning] the method has reached the maximum number of iterations; it might have not converged')
+
+        return qs, ps
+
+
+    def _apply_calibration(self, predictions):
+        """
+        Calibrate posterior predictions with specified calibration method.
+        
+        Parameters
+        ----------
+        predictions : ndarray
+            Posterior predictions to calibrate.
+        
+        Returns
+        -------
+        calibrated_predictions : ndarray
+            Calibrated posterior predictions.
+        
+        Raises
+        ------
+        ValueError
+            If calib_function is unrecognized.
+        """
+        if self.calib_function is None:
+            return predictions
+
+        if isinstance(self.calib_function, str):
+            method = self.calib_function.lower()
+            if method == "ts":
+                return self._temperature_scaling(predictions)
+            elif method == "bcts":
+                return self._bias_corrected_temperature_scaling(predictions)
+            elif method == "vs":
+                return self._vector_scaling(predictions)
+            elif method == "nbvs":
+                return self._no_bias_vector_scaling(predictions)
+
+        elif callable(self.calib_function):
+            return self.calib_function(predictions)
+
+        raise ValueError(
+            f"Invalid calib_function '{self.calib_function}'. Expected one of {{'bcts', 'ts', 'vs', 'nbvs', None, callable}}."
+        )
+
+    def _temperature_scaling(self, preds):
+        """Temperature Scaling calibration applied to logits."""
+        T = 1.0
+        preds = np.clip(preds, 1e-12, 1.0)
+        logits = np.log(preds)
+        scaled = logits / T
+        exp_scaled = np.exp(scaled - np.max(scaled, axis=1, keepdims=True))
+        return exp_scaled / np.sum(exp_scaled, axis=1, keepdims=True)
+
+    def _bias_corrected_temperature_scaling(self, preds):
+        """Bias-Corrected Temperature Scaling calibration."""
+        T = 1.0
+        bias = np.zeros(preds.shape[1])
+        preds = np.clip(preds, 1e-12, 1.0)
+        logits = np.log(preds)
+        logits = logits / T + bias
+        exp_logits = np.exp(logits - np.max(logits, axis=1, keepdims=True))
+        return exp_logits / np.sum(exp_logits, axis=1, keepdims=True)
+
+    def _vector_scaling(self, preds):
+        """Vector Scaling calibration."""
+        W = np.ones(preds.shape[1])
+        b = np.zeros(preds.shape[1])
+        preds = np.clip(preds, 1e-12, 1.0)
+        logits = np.log(preds)
+        scaled = logits * W + b
+        exp_scaled = np.exp(scaled - np.max(scaled, axis=1, keepdims=True))
+        return exp_scaled / np.sum(exp_scaled, axis=1, keepdims=True)
+
+    def _no_bias_vector_scaling(self, preds):
+        """No-Bias Vector Scaling calibration."""
+        W = np.ones(preds.shape[1])
+        preds = np.clip(preds, 1e-12, 1.0)
+        logits = np.log(preds)
+        scaled = logits * W
+        exp_scaled = np.exp(scaled - np.max(scaled, axis=1, keepdims=True))
+        return exp_scaled / np.sum(exp_scaled, axis=1, keepdims=True)
+
+
+
+class MLPE(SoftLearnerQMixin, BaseIterativeLikelihood):
+    """
+    Maximum Likelihood Prevalence Estimation (MLPE) quantifier.
+    
+    A simple iterative likelihood quantification method that returns the
+    training priors as the estimated prevalences, effectively skipping iteration.
+    
+    This method assumes no prior probability shift between training and test.
+    
+    Parameters
+    ----------
+    learner : estimator, optional
+        Base classifier for possible extension/fitting.
+    """
+
+    def __init__(self, learner=None):
+        super().__init__(learner=learner, max_iter=1)
+        
+    def _iterate(self, predictions, priors):
+        """Returns training priors without adjustment.
+        
+        Parameters
+        ----------
+        predictions : array-like
+            Ignored in this implementation.
+        priors : array-like
+            Training priors, returned as is.
+        
+        Returns
+        -------
+        prevalences : array-like
+            Equal to the training priors.
+        """
+        return priors
+    
+@define_binary
+class CDE(SoftLearnerQMixin, BaseIterativeLikelihood):
+    """
+    CDE-Iterate (Class Distribution Estimation Iterate) for binary classification.
+    
+    This method iteratively estimates class prevalences under prior probability shift
+    by updating the false positive cost in a cost-sensitive classification framework,
+    using a thresholding strategy based on posterior probabilities.
+    
+    The procedure:
+    - Calculates a threshold from false-positive (cFP) and false-negative (cFN) costs.
+    - Assigns hard positive predictions where posterior probability exceeds threshold.
+    - Estimates the prevalence via classify-and-count on thresholded predictions.
+    - Updates false positive cost according to prevalence estimates and training priors.
+    - Iterates until prevalence estimates converge or max iterations reached.
+    
+    This implementation adopts the transductive thresholding variant described in 
+    Esuli et al. (2023), rather than retraining a cost-sensitive classifier as in 
+    Xue & Weiss (2009).
+    
+    Parameters
+    ----------
+    learner : estimator, optional
+        Wrapped classifier (unused here but part of base interface).
+    tol : float, default=1e-4
+        Absolute tolerance for convergence of estimated prevalences.
+    max_iter : int, default=100
+        Max number of iterations allowed.
+    init_cfp : float, default=1.0
+        Initial false positive cost coefficient.
+    
+    References
+    ----------
+    [2] Esuli, A., Moreo, A., & Sebastiani, F. (2023). Learning to Quantify. Springer.
+    """
+
+    _parameter_constraints = {
+        "tol": [Interval(0, None, inclusive_left=False)],
+        "max_iter": [Interval(1, None, inclusive_left=True)],
+        "init_cfp": [Interval(0, None, inclusive_left=False)]
+    }
+
+    def __init__(self, learner=None, tol=1e-4, max_iter=100, init_cfp=1.0):
+        super().__init__(learner=learner, tol=tol, max_iter=max_iter)
+        self.init_cfp = float(init_cfp)
+
+    def _iterate(self, predictions, priors):
+        """
+        Iteratively estimate prevalences via cost-sensitive thresholding.
+
+        Parameters
+        ----------
+        predictions : ndarray, shape (n_samples, 2)
+            Posterior probabilities for binary classes [neg, pos].
+        priors : ndarray, shape (2,)
+            Training priors [p(neg), p(pos)].
+
+        Returns
+        -------
+        prevalences : ndarray, shape (2,)
+            Estimated prevalences for classes [neg, pos].
+        """
+        P = np.asarray(predictions, dtype=np.float64)
+        Ptr = np.asarray(priors, dtype=np.float64)
+
+        # basic checks
+        if P.ndim != 2 or P.shape[1] != 2:
+            raise ValueError("CDE implementation here supports binary case only: predictions shape (n,2).")
+
+        # ensure no zeros
+        eps = 1e-12
+        P = np.clip(P, eps, 1.0)
+
+        # training priors pL(+), pL(-)
+        # assume Ptr order matches columns of P; if Ptr sums to 1 but order unknown, user must match.
+        pL_pos = Ptr[1]
+        pL_neg = Ptr[0]
+        if pL_pos <= 0 or pL_neg <= 0:
+            # keep them positive to avoid divisions by zero
+            pL_pos = max(pL_pos, eps)
+            pL_neg = max(pL_neg, eps)
+
+        # initialize costs
+        cFN = 1.0
+        cFP = float(self.init_cfp)
+
+        prev_prev_pos = None
+        s = 0
+
+        # iterate: compute threshold from costs, classify, estimate prevalences via CC,
+        # update cFP via eq. (4.27), repeat
+        while s < self.max_iter:
+            # decision threshold tau for positive class:
+            # Derivation:
+            # predict positive if cost_FP * p(-|x) < cost_FN * p(+|x)
+            # => predict positive if p(+|x) / p(-|x) > cost_FP / cost_FN
+            # since p(+|x) / p(-|x) = p(+|x) / (1 - p(+|x)):
+            # p(+|x) > cost_FP / (cost_FP + cost_FN)
+            tau = cFP / (cFP + cFN)
+
+            # hard predictions for positive class using threshold on posterior for positive (col 1)
+            pos_probs = P[:, 1]
+            hard_pos = (pos_probs > tau).astype(float)
+
+            # classify-and-count prevalence estimate on U
+            prev_pos = hard_pos.mean()
+            prev_neg = 1.0 - prev_pos
+
+            # update cFP according to Eq. 4.27:
+            # cFP_new = (pL_pos / pL_neg) * (pU_hat(neg) / pU_hat(pos)) * cFN
+            # guard against zero prev_pos / prev_neg
+            prev_pos_safe = max(prev_pos, eps)
+            prev_neg_safe = max(prev_neg, eps)
+
+            cFP_new = (pL_pos / pL_neg) * (prev_neg_safe / prev_pos_safe) * cFN
+
+            # check convergence on prevalences (absolute change)
+            if prev_prev_pos is not None and abs(prev_pos - prev_prev_pos) < self.tol:
+                break
+
+            # prepare next iter
+            cFP = cFP_new
+            prev_prev_pos = prev_pos
+            s += 1
+
+        # if didn't converge within max_iter we keep last estimate (book warns about lack of fisher consistency)
+        if s >= self.max_iter:
+            # optional: warning
+            # print('[warning] CDE-Iterate reached max_iter without converging')
+            pass
+
+        prevalences = np.array([prev_neg, prev_pos], dtype=np.float64)
+        # ensure sums to 1 (numerical safety)
+        prevalences = prevalences / prevalences.sum()
+
+        return prevalences

mlquantify/meta/__init__.py

@@ -0,0 +1 @@
+from ._classes import EnsembleQ, QuaDapt, AggregativeBootstrap