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

mlquantify/meta/_classes.py

@@ -30,7 +30,7 @@ from mlquantify.utils.prevalence import get_prev_from_labels
 
 
 def get_protocol_sampler(protocol_name, batch_size, n_prevalences, min_prev, max_prev, n_classes):
-    """ Returns a prevalence sampler function based on the specified protocol name.
+    r""" Returns a prevalence sampler function based on the specified protocol name.
     
     Parameters
     ----------
@@ -80,8 +80,7 @@ def get_protocol_sampler(protocol_name, batch_size, n_prevalences, min_prev, max
     return protocol
 
 class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
-    """
-    Ensemble-based Quantifier combining multiple models trained on varied data samples 
+    r"""Ensemble-based Quantifier combining multiple models trained on varied data samples 
     with controlled prevalence distributions to improve robustness and accuracy.
 
     This quantifier constructs an ensemble of quantification models using batches of training 
@@ -128,18 +127,6 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
     posteriors_generator : callable or None
         Function to generate posterior probabilities for new samples.
 
-    Methods
-    -------
-    fit(X, y)
-        Fits all ensemble member quantifiers on sampled training batches.
-    predict(X)
-        Aggregates ensemble member predictions into final prevalence estimates.
-    ptr_selection_metric(prevalences, train_prevalences)
-        Implements PTR-based selection metric on prevalence estimates.
-    ds_get_posteriors(X, y)
-        Computes posterior probabilities for training data with cross-validated logistic regression.
-    ds_selection_metric(X, prevalences, train_distributions, posteriors_generator)
-        Implements DS-based selection metric comparing posterior distributions.
 
     Notes
     -----
@@ -149,9 +136,25 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
 
     Examples
     --------
-    >>> ensemble = EnsembleQ(quantifier=SomeQuantifier(), size=30, protocol='kraemer', selection_metric='ptr')
+    >>> from mlquantify.ensemble import EnsembleQ
+    >>> from mlquantify.mixture import DyS
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>>
+    >>> ensemble = EnsembleQ(
+    ...     quantifier=DyS(RandomForestClassifier()), 
+    ...     size=30, 
+    ...     protocol='artificial', # APP protocol 
+    ...     selection_metric='ptr'
+    ... )
     >>> ensemble.fit(X_train, y_train)
     >>> prevalence_estimates = ensemble.predict(X_test)
+    
+    References
+    ----------
+    .. [1] Pérez-Gállego, P., Castaño, A., Ramón Quevedo, J., & José del Coz, J. (2019). Dynamic ensemble selection for quantification tasks. Information Fusion, 45, 1-15. https://doi.org/10.1016/j.inffus.2018.01.001
+
+    .. [2] Pérez-Gállego, P., Quevedo, J. R., & del Coz, J. J. (2017). Using ensembles for problems with characterizable changes in data distribution: A case study on quantification. Information Fusion, 34, 87-100. https://doi.org/10.1016/j.inffus.2016.07.001
+
     """  
       
     _parameter_constraints = {
@@ -306,7 +309,7 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
 
 
     def ptr_selection_metric(self, prevalences, train_prevalences):
-        """
+        r"""
         Selects the prevalence estimates from models trained on samples whose prevalence is most similar
         to an initial approximation of the test prevalence as estimated by all models in the ensemble.
 
@@ -326,7 +329,7 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
         return _select_k(prevalences, order, k=self.p_metric)
 
     def ds_get_posteriors(self, X, y):
-        """ 
+        r""" 
         Generate posterior probabilities using cross-validated logistic regression.
         This method computes posterior probabilities for the training data via cross-validation,
         using a logistic regression classifier with hyperparameters optimized through grid search.
@@ -370,7 +373,7 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
 
 
     def ds_selection_metric(self, X, prevalences, train_distributions, posteriors_generator):
-        """
+        r"""
         Selects the prevalence estimates from models trained on samples whose distribution of posterior
         probabilities is most similar to the distribution of posterior probabilities for the test data.
         
@@ -393,7 +396,7 @@ class EnsembleQ(MetaquantifierMixin, BaseQuantifier):
         return _select_k(prevalences, order, k=self.p_metric)
 
 def _select_k(elements, order, k):
-    """
+    r"""
     Selects the k elements from the list of elements based on the order.
     If the list is empty, it returns the original list.
     
@@ -422,7 +425,7 @@ def _select_k(elements, order, k):
 
 
 class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
-    """
+    r"""
     Aggregative Bootstrap Quantifier to compute prevalence confidence regions.
 
     This metaquantifier applies bootstrapping to both training and test data predictions 
@@ -445,18 +448,17 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
     confidence_level : float between 0 and 1, default=0.95
         Confidence level for intervals or regions.
 
-    Methods
-    -------
-    fit(X, y, val_split=None)
-        Fits base quantifier and generates training predictions (optionally splitting data).
-    predict(X)
-        Returns prevalence estimates and confidence regions aggregated from bootstrap samples.
-    aggregate(predictions, train_predictions, train_y_values)
-        Performs bootstrap resampling aggregation to obtain prevalence confidence regions.
 
     Examples
     --------
-    >>> agg_boot = AggregativeBootstrap(quantifier=SomeQuantifier, n_train_bootstraps=100, n_test_bootstraps=100)
+    >>> from mlquantify.ensemble import AggregativeBootstrap
+    >>> from mlquantify.neighbors import EMQ
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> agg_boot = AggregativeBootstrap(
+    ...     quantifier=EMQ(RandomForestClassifier()), 
+    ...     n_train_bootstraps=100, 
+    ...     n_test_bootstraps=100
+    ... )
     >>> agg_boot.fit(X_train, y_train)
     >>> prevalence, conf_region = agg_boot.predict(X_test)
     """
@@ -485,7 +487,7 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
         self.confidence_level = confidence_level
         
     def fit(self, X, y, val_split=None):
-        """ Fits the aggregative bootstrap model to the given training data.
+        r""" Fits the aggregative bootstrap model to the given training data.
         
         Parameters
         ----------
@@ -498,6 +500,11 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
         -------
         self : AggregativeBootstrap
             The fitted aggregative bootstrap model.
+            
+        Raises
+        ------
+        ValueError
+            If the provided quantifier is not an aggregative quantifier.
         """
         X, y = validate_data(self, X, y)
         self.classes = np.unique(y)
@@ -524,7 +531,7 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
         return self
     
     def predict(self, X):
-        """ Predicts the class prevalences for the given test data.
+        r""" Predicts the class prevalences for the given test data.
         
         Parameters
         ----------
@@ -546,7 +553,7 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
 
 
     def aggregate(self, predictions, train_predictions, train_y_values):
-        """ Aggregates the predictions using bootstrap resampling.
+        r""" Aggregates the predictions using bootstrap resampling.
         
         Parameters
         ----------
@@ -612,10 +619,10 @@ class AggregativeBootstrap(MetaquantifierMixin, BaseQuantifier):
 
 
 class QuaDapt(MetaquantifierMixin, BaseQuantifier):
-    r"""QuaDapt Metaquantifier: Adaptive quantification using score merging and distance measures.
+    r"""QuaDapt Metaquantifier: Adaptive quantification using synthetic scores.
 
     This metaquantifier improves prevalence estimation by merging training samples 
-    with different score distributions using a merging factor \( m \). It evaluates 
+    with different score distributions using a merging factor :math: \( m \). It evaluates 
     candidate merging factors, chooses the best by minimizing a distribution distance 
     metric (Hellinger, Topsoe, ProbSymm, or SORD), and aggregates quantification accordingly.
 
@@ -625,38 +632,28 @@ class QuaDapt(MetaquantifierMixin, BaseQuantifier):
         The base quantifier model to adapt.
     measure : {'hellinger', 'topsoe', 'probsymm', 'sord'}, default='topsoe'
         The distribution distance metric used to select the best merging factor.
-    merging_factor : array-like
+    merging_factors : array-like
         Candidate merging factor values to evaluate.
 
-    Methods
-    -------
-    fit(X, y)
-        Fits the base learner on training data.
-    predict(X)
-        Predicts prevalence aggregating via the best merging factor.
-    aggregate(predictions, train_y_values)
-        Performs adaptation and aggregation based on merged score distributions.
-    _get_best_merging_factor(predictions)
-        Evaluates merging factors and selects the best based on minimum distance.
-    _get_best_distance(predictions, pos_scores, neg_scores)
-        Computes the distance metric between predicted and class score distributions.
-
-    Class Methods
-    -------------
-    MoSS(n, alpha, m)
-        Generates merged score samples modeling class conditional distributions 
-        parameterized by mixing proportion alpha and merging factor m.
-
     Examples
     --------
-    >>> quadapt = QuaDapt(quantifier=SomeQuantifier, merging_factor=[0.1, 0.5, 1.0], measure='sord')
-    >>> quadapt.fit(X_train, y_train)
-    >>> prevalence = quadapt.predict(X_test)
+    >>> from mlquantify.meta import QuaDapt
+    >>> from mlquantify.adjust_counting import ACC
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> quadapt_acc = QuaDapt(
+    ...     quantifier=ACC(RandomForestClassifier()), 
+    ...     merging_factor=[0.1, 0.5, 1.0], 
+    ...     measure='sord'
+    ... )
+    >>> quadapt_acc.fit(X_train, y_train)
+    >>> prevalence = quadapt_acc.predict(X_test)
+    
+    
     """
     
     _parameter_constraints = {
         "quantifier": [BaseQuantifier],
-        "merging_factor": "array-like",
+        "merging_factors": "array-like",
         "measure": [Options(["hellinger", "topsoe", "probsymm", "sord"])],
         "random_state": [Options([None, int])],
     }
@@ -664,10 +661,10 @@ class QuaDapt(MetaquantifierMixin, BaseQuantifier):
     def __init__(self, 
                  quantifier,
                  measure="topsoe", 
-                 merging_factor=(0.1, 1.0, 0.2)):
+                 merging_factors=(0.1, 1.0, 0.2)):
         self.quantifier = quantifier
         self.measure = measure
-        self.merging_factor = merging_factor
+        self.merging_factors = merging_factors
         
     
     def fit(self, X, y):
@@ -719,7 +716,7 @@ class QuaDapt(MetaquantifierMixin, BaseQuantifier):
         
     def _get_best_merging_factor(self, predictions):
         
-        MF = np.atleast_1d(np.round(self.merging_factor, 2)).astype(float)
+        MF = np.atleast_1d(np.round(self.merging_factors, 2)).astype(float)
         
         distances = []
         
@@ -748,6 +745,33 @@ class QuaDapt(MetaquantifierMixin, BaseQuantifier):
 
     @classmethod
     def MoSS(cls, n, alpha, m):
+        r"""Model for Score Simulation
+
+        MoSS has three key parameters:
+        (I) the number of observations `n`;
+        (II) the class proportion `\alpha`, which defines the prevalence of the positive class;
+        (III) the merging factor :math:`m`, which controls the overlap between positive and negative score distributions 
+        (where :math:`m=0` represents easily separable classes and :math:`m=1` represents highly overlapping ones).
+
+        .. math::
+            
+            \mathrm{moss}(n, \alpha, \mathfrak{m}) = \mathrm{syn}(\oplus, \lfloor \alpha n \rfloor, \mathfrak{m}) \cup \mathrm{syn}(\ominus , \lfloor (1 - \alpha) n \rfloor, \mathfrak{m})
+
+        Notes
+        -----
+        The MoSS generates only binary scores, simulating positive and negative class scores.
+
+        Examples
+        --------
+        >>> scores = QuaDapt.MoSS(n=1000, alpha=0.3, m=0.5)
+        >>> print(scores.shape)
+        (1000, 3)
+
+        References
+        ----------
+        .. [1] Maletzke, A., Reis, D. dos, Hassan, W., & Batista, G. (2021).
+        Accurately Quantifying under Score Variability. 2021 IEEE International Conference on Data Mining (ICDM), 1228-1233. https://doi.org/10.1109/ICDM51629.2021.00149
+        """
         p_score = np.random.uniform(size=int(n * alpha)) ** m
         n_score = 1 - (np.random.uniform(size=int(round(n * (1 - alpha), 0))) ** m)
         scores = np.column_stack(

mlquantify/metrics/_oq.py

@@ -28,7 +28,7 @@ def process_inputs(prev_pred, prev_real):
 
 
 def NMD(prev_pred, prev_real, distances=None):
-    """
+    r"""
     Compute the Normalized Match Distance (NMD), also known as Earth Mover’s Distance (EMD),
     for ordinal quantification evaluation.
 
@@ -66,7 +66,7 @@ def NMD(prev_pred, prev_real, distances=None):
 
 
 def RNOD(prev_pred, prev_real, distances=None):
-    """
+    r"""
     Compute the Root Normalised Order-aware Divergence (RNOD) for ordinal quantification evaluation.
 
     Parameters

mlquantify/metrics/_rq.py

@@ -31,7 +31,7 @@ def process_inputs(prev_pred, prev_real):
 
 
 def VSE(prev_pred, prev_real, train_values):
-    """
+    r"""
     Compute the Variance-normalised Squared Error (VSE).
 
     Parameters
@@ -60,7 +60,7 @@ def VSE(prev_pred, prev_real, train_values):
 
 
 def CvM_L1(prev_pred, prev_real, n_bins=100):
-    """
+    r"""
     Compute the L1 version of the Cramér–von Mises statistic (Xiao et al., 2006)
     between two cumulative distributions, as suggested by Bella et al. (2014).
 

mlquantify/metrics/_slq.py

@@ -30,7 +30,7 @@ def process_inputs(prev_pred, prev_real):
 
 
 def AE(prev_pred, prev_real):
-    """
+    r"""
     Compute the absolute error for each class or a dictionary of errors if input is a dictionary.
 
     Parameters
@@ -57,7 +57,7 @@ def AE(prev_pred, prev_real):
 
 
 def MAE(prev_pred, prev_real):
-    """
+    r"""
     Compute the mean absolute error between the real and predicted prevalences.
 
     Parameters
@@ -78,7 +78,7 @@ def MAE(prev_pred, prev_real):
 
 
 def KLD(prev_pred, prev_real):
-    """
+    r"""
     Compute the Kullback-Leibler divergence between the real and predicted prevalences.
 
     Parameters
@@ -99,7 +99,7 @@ def KLD(prev_pred, prev_real):
 
 
 def SE(prev_pred, prev_real):
-    """
+    r"""
     Compute the mean squared error between the real and predicted prevalences.
 
     Parameters
@@ -120,7 +120,7 @@ def SE(prev_pred, prev_real):
 
 
 def MSE(prev_pred, prev_real):
-    """ Mean Squared Error
+    r""" Mean Squared Error
 
     Parameters
     ----------
@@ -140,7 +140,7 @@ def MSE(prev_pred, prev_real):
 
 
 def NAE(prev_pred, prev_real):
-    """
+    r"""
     Compute the normalized absolute error between the real and predicted prevalences.
 
     Parameters
@@ -163,7 +163,7 @@ def NAE(prev_pred, prev_real):
 
 
 def NKLD(prev_pred, prev_real):
-    """
+    r"""
     Compute the normalized Kullback-Leibler divergence between the real and predicted prevalences.
 
     Parameters
@@ -186,7 +186,7 @@ def NKLD(prev_pred, prev_real):
 
 
 def RAE(prev_pred, prev_real):
-    """
+    r"""
     Compute the relative absolute error between the real and predicted prevalences.
 
     Parameters
@@ -207,7 +207,7 @@ def RAE(prev_pred, prev_real):
 
 
 def NRAE(prev_pred, prev_real):
-    """
+    r"""
     Compute the normalized relative absolute error between the real and predicted prevalences.
 
     Parameters

mlquantify/mixture/_base.py

@@ -15,8 +15,7 @@ from mlquantify.mixture._utils import (
 )
 
 class BaseMixture(BaseQuantifier):
-    """
-    Base class for mixture-model quantifiers.
+    r"""Base class for mixture-model quantifiers.
 
     Mixture Models (MM) for quantification estimate class prevalences by modeling 
     the test set score distribution as a mixture of the individual class score 
@@ -39,7 +38,7 @@ class BaseMixture(BaseQuantifier):
     scores or histograms, and the choice of distance can affect quantification accuracy 
     and robustness.
 
-    The DyS framework (Maletzke et al. 2019) generalizes mixture models by introducing 
+    The DyS framework [3]_ generalizes mixture models by introducing 
     a variety of distribution dissimilarity measures, enabling flexible and effective 
     quantification methods.
     
@@ -49,11 +48,13 @@ class BaseMixture(BaseQuantifier):
     Mixture models are defined for only binary quantification problems. For multi-class
     problems, a one-vs-rest strategy is applied, training a binary mixture model for
     each class against the rest.
+    
 
     Parameters
     ----------
     None directly; subclasses implement fitting and prediction logic.
 
+
     Attributes
     ----------
     _precomputed : bool
@@ -63,19 +64,6 @@ class BaseMixture(BaseQuantifier):
     classes : ndarray of shape (n_classes,)
         Unique class labels seen during training.
 
-    Methods
-    -------
-    fit(X, y, *args, **kwargs):
-        Fit the mixture quantifier with training data. Validates input and 
-        calls internal fitting procedure.
-    predict(X, *args, **kwargs):
-        Predict class prevalences for input data by leveraging best mixture parameters.
-    get_best_distance(*args, **kwargs):
-        Return the best distance measure and associated mixture parameters found.
-    best_mixture(X):
-        Abstract method to determine optimal mixture parameters on input data.
-    get_distance(dist_train, dist_test, measure="hellinger"):
-        Compute a specified distance between two distributions.
 
     References
     ----------
@@ -118,6 +106,14 @@ class BaseMixture(BaseQuantifier):
         return self._predict(X, *args, **kwargs)
     
     def get_best_distance(self, *args, **kwargs):
+        r""" Get the best distance value from the mixture fitting process.
+        
+        Notes
+        -----
+        If the quantifier has not been fitted yet, it will fit the model for getting the
+        best distance.
+        
+        """
         _, best_distance = self.best_mixture(*args, **kwargs)
         return best_distance
 
@@ -128,9 +124,7 @@ class BaseMixture(BaseQuantifier):
     
     @classmethod
     def get_distance(cls, dist_train, dist_test, measure="hellinger"):
-        """
-        Compute distance between two distributions.
-        """
+        r"""Compute distance between two distributions."""
         
         if np.sum(dist_train) < 1e-20 or np.sum(dist_test) < 1e-20:
             raise ValueError("One or both vectors are zero (empty)...")

mlquantify/mixture/_classes.py

@@ -21,8 +21,7 @@ from mlquantify.mixture._utils import (
 # =====================================================
 @define_binary
 class AggregativeMixture(SoftLearnerQMixin, AggregationMixin, BaseMixture):
-    """
-    Base class for Mixture-based Quantification Methods.
+    r"""Base class for Mixture-based Quantification Methods.
 
     These methods assume that the test score distribution is a mixture
     of the positive and negative score distributions from the training data.
@@ -105,7 +104,7 @@ class AggregativeMixture(SoftLearnerQMixin, AggregationMixin, BaseMixture):
 # =====================================================
 
 class DyS(AggregativeMixture):
-    """Distribution y-Similarity (DyS) quantification method.
+    r"""Distribution y-Similarity (DyS) quantification method.
 
     Uses mixture modeling with a dissimilarity measure between distributions
     computed on histograms of classifier scores. This method optimizes mixture 
@@ -128,7 +127,9 @@ class DyS(AggregativeMixture):
 
     Examples
     --------
-    >>> q = DyS(learner=my_learner, measure="hellinger")
+    >>> from mlquantify.mixture import DyS
+    >>> from sklearn.linear_model import LogisticRegression
+    >>> q = DyS(learner=LogisticRegression(), measure="hellinger")
     >>> q.fit(X_train, y_train)
     >>> prevalences = q.predict(X_test)
     """
@@ -147,6 +148,35 @@ class DyS(AggregativeMixture):
         self.bins_size = np.asarray(bins_size, dtype=int)
 
     def best_mixture(self, predictions, pos_scores, neg_scores):
+        r"""Determine the best mixture parameters for the given data.
+        
+        Applies ternary search to find the mixture weight minimizing the distance
+        between the test score histogram and the mixture of positive and negative
+        
+        The mixture weight :math:`\alpha` is estimated as:
+        .. math::
+            \alpha = \arg \min_{\alpha \in [0, 1]} D \left( H_{test}, \alpha H_{pos} + (1 - \alpha) H_{neg} \right)
+            
+        where :math:`D` is the selected distance measure and :math:`H` denotes histograms.
+        
+        
+        Parameters
+        ----------
+        predictions : ndarray
+            Classifier scores for the test data.
+        pos_scores : ndarray
+            Classifier scores for the positive class from training data.
+        neg_scores : ndarray
+            Classifier scores for the negative class from training data.
+            
+            
+        Returns
+        -------
+        alpha : float
+            Estimated mixture weight.
+        best_distance : float
+            Distance corresponding to the best mixture weight.
+        """
         
         prevs = []
         self.distances = []
@@ -175,7 +205,7 @@ class DyS(AggregativeMixture):
 # =====================================================
 
 class HDy(AggregativeMixture):
-    """Hellinger Distance Minimization (HDy) quantification method.
+    r"""Hellinger Distance Minimization (HDy) quantification method.
 
     Estimates class prevalences by finding mixture weights that minimize
     the Hellinger distance between the histogram of test scores and the mixture
@@ -193,6 +223,35 @@ class HDy(AggregativeMixture):
     """
     
     def best_mixture(self, predictions, pos_scores, neg_scores):
+        r"""Determine the best mixture parameters for the given data.
+
+        Compute the mixture weight :math:`\alpha` that minimizes the Hellinger distance between the test score histogram and the mixture of positive and negative class score histograms.
+
+        The mixture weight :math:`\alpha` is estimated as:
+        .. math::
+            \alpha = \arg \min_{\alpha \in [0, 1]} Hellinger \left( H_{test}, \alpha H_{pos} + (1 - \alpha) H_{neg} \right)
+            
+        where :math:`H` denotes histograms.
+        
+        
+        Parameters
+        ----------
+        predictions : ndarray
+            Classifier scores for the test data.
+        pos_scores : ndarray
+            Classifier scores for the positive class from training data.
+        neg_scores : ndarray
+            Classifier scores for the negative class from training data.
+            
+            
+        Returns
+        -------
+        alpha : float
+            Estimated mixture weight.
+        best_distance : float
+            Distance corresponding to the best mixture weight.
+        """
+        
         bins_size = np.arange(10, 110, 11)
         alpha_values = np.round(np.linspace(0, 1, 101), 2)
         
@@ -228,13 +287,12 @@ class SMM(AggregativeMixture):
 
     Estimates class prevalence by matching the mean score of the test samples 
     to a convex combination of positive and negative training scores. The mixture 
-    weight \( \alpha \) is computed as:
+    weight :math:`\alpha` is computed as:
 
-    \[
-    \alpha = \frac{\bar{s}_{test} - \bar{s}_{neg}}{\bar{s}_{pos} - \bar{s}_{neg}}
-    \]
+    .. math::
+        \alpha = \frac{\bar{s}_{test} - \bar{s}_{neg}}{\bar{s}_{pos} - \bar{s}_{neg}}
 
-    where \( \bar{s} \) denotes the sample mean.
+    where :math:`\bar{s}` denotes the sample mean.
 
     Parameters
     ----------