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

mlquantify/{classification/methods.py → neighbors/_classification.py}

@@ -1,73 +1,54 @@
-from sklearn.neighbors import NearestNeighbors
-from sklearn.base import BaseEstimator
+
 import numpy as np
-import pandas as pd
+from sklearn.neighbors import NearestNeighbors
 
-class PWKCLF(BaseEstimator):
-    """
-    Learner based on k-Nearest Neighbors (KNN) to use in the PWK method.
-    
-    This classifier adjusts the influence of neighbors using class weights 
-    derived from the `alpha` parameter. The `alpha` parameter controls the 
-    influence of class imbalance.
 
-    Parameters
-    ----------
-    alpha : float, default=1
-        Controls the influence of class imbalance. Must be >= 1.
 
-    n_neighbors : int, default=10
-        Number of neighbors to use.
+class PWKCLF:
+    r"""Probabilistic Weighted k-Nearest Neighbor Classifier (PWKCLF).
 
-    algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, default='auto'
-        Algorithm to compute nearest neighbors.
+    A weighted k-nearest neighbor classifier that assigns class probabilities to 
+    instances based on neighbor counts weighted by class-specific inverse frequency 
+    factors adjusted by a hyperparameter alpha controlling imbalance compensation. 
 
-    metric : str, default='euclidean'
-        Distance metric to use.
+    Attributes
+    ----------
+    alpha : float
+        Exponent controlling the degree of imbalance compensation.
+    n_neighbors : int
+        Number of nearest neighbors considered.
+    nbrs : sklearn.neighbors.NearestNeighbors
+        The underlying k-NN structure used for neighbor queries.
+    classes_ : ndarray
+        Unique classes observed during training.
+    class_to_index : dict
+        Mapping from class label to index used in internal arrays.
+    class_weights : ndarray
+        Per-class weights computed based on class frequency and alpha.
+    y_train : ndarray
+        Labels of training samples.
 
-    leaf_size : int, default=30
-        Leaf size passed to the tree-based algorithms.
 
-    p : int, default=2
-        Power parameter for the Minkowski metric.
+    Notes
+    -----
+    The class weights are defined as:
 
-    metric_params : dict, optional
-        Additional keyword arguments for the metric function.
+    .. math::
 
-    n_jobs : int, optional
-        Number of parallel jobs to run for neighbors search.
+        w_c = \left( \frac{N_c}{\min_{c'} N_{c'}} \right)^{-\frac{1}{\alpha}},
+
+    where :math:`N_c` is the count of class :math:`c` in the training set.
+
+    This weighting scheme reduces bias towards majority classes by downweighting them
+    in the voting process.
 
     Examples
     --------
-    >>> from sklearn.datasets import load_breast_cancer
-    >>> from sklearn.model_selection import train_test_split
-    >>> from mlquantify.methods.aggregative import PWK
-    >>> from mlquantify.utils.general import get_real_prev
-    >>> from mlquantify.classification import PWKCLF
-    >>> 
-    >>> # Load dataset
-    >>> features, target = load_breast_cancer(return_X_y=True)
-    >>> 
-    >>> # Split into training and testing sets
-    >>> X_train, X_test, y_train, y_test = train_test_split(features, target, test_size=0.3, random_state=32)
-    >>> 
-    >>> # Create and configure the PWKCLF learner
-    >>> learner = PWKCLF(alpha=1, n_neighbors=10)
-    >>> 
-    >>> # Create the PWK quantifier
-    >>> model = PWK(learner=learner)
-    >>> 
-    >>> # Train the model
-    >>> model.fit(X_train, y_train)
-    >>> 
-    >>> # Predict prevalences
-    >>> y_pred = model.predict(X_test)
-    >>> 
-    >>> # Display results
-    >>> print("Real:", get_real_prev(y_test))
-    >>> print("PWK:", y_pred)
+    >>> clf = PWKCLF(alpha=2.0, n_neighbors=7)
+    >>> clf.fit(X_train, y_train)
+    >>> labels = clf.predict(X_test)
     """
-
+    
     def __init__(self,
                  alpha=1,
                  n_neighbors=10,
@@ -77,9 +58,6 @@ class PWKCLF(BaseEstimator):
                  p=2,
                  metric_params=None,
                  n_jobs=None):
-        if alpha < 1:
-            raise ValueError("alpha must not be smaller than 1")
-        
         self.alpha = alpha
         self.n_neighbors = n_neighbors
 
@@ -119,9 +97,6 @@ class PWKCLF(BaseEstimator):
             
         self.y_train = y
         
-        if isinstance(y, pd.DataFrame):
-            self.y_train = y.reset_index(drop=True)
-            
         unique_classes, class_counts = np.unique(y, return_counts=True)
         self.classes_ = unique_classes
         self.class_to_index = dict(zip(self.classes_, range(len(self.classes_))))

mlquantify/neighbors/_kde.py

@@ -0,0 +1,268 @@
+import numpy as np
+from sklearn.neighbors import KernelDensity
+from mlquantify.utils._constraints import Interval
+from mlquantify.neighbors._base import BaseKDE
+from mlquantify.neighbors._utils import (
+    gaussian_kernel,
+    negative_log_likelihood,
+    EPS,
+)
+from mlquantify.utils import check_random_state
+from scipy.optimize import minimize
+
+
+# ============================================================
+# Auxiliary functions
+# ============================================================
+
+def _optimize_on_simplex(objective, n_classes, x0=None):
+    r"""Optimize an objective function over the probability simplex.
+    
+    This function performs constrained optimization to find the mixture weights
+    :math:`\alpha` on the simplex :math:`\Delta^{n-1} = \{ \alpha \in \mathbb{R}^n : \alpha_i \geq 0, \sum_i \alpha_i = 1 \}`
+    that minimize the given objective function.
+
+    Parameters
+    ----------
+    objective : callable
+        Function from :math:`\mathbb{R}^n \to \mathbb{R}` to minimize.
+    n_classes : int
+        Dimensionality of the simplex (number of classes).
+    x0 : array-like, optional
+        Initial guess for the optimization, defaults to uniform vector.
+
+    Returns
+    -------
+    alpha_opt : ndarray of shape (n_classes,)
+        Optimized weights summing to 1.
+    min_loss : float
+        Objective function value at optimum.
+
+    Notes
+    -----
+    The optimization uses scipy's `minimize` with bounds and equality constraint.
+    """
+    if x0 is None:
+        x0 = np.ones(n_classes) / n_classes
+
+    constraints = {'type': 'eq', 'fun': lambda x: np.sum(x) - 1}
+    bounds = [(0, 1)] * n_classes
+
+    res = minimize(objective, x0, bounds=bounds, constraints=constraints)
+    alpha_opt = res.x / np.sum(res.x)
+    return alpha_opt, res.fun
+
+
+# ============================================================
+# KDEy-ML — Maximum Likelihood
+# ============================================================
+
+class KDEyML(BaseKDE):
+    r"""KDEy Maximum Likelihood quantifier.
+    
+    Models class-conditional densities of posterior probabilities via Kernel Density
+    Estimation (KDE) and estimates class prevalences by maximizing the likelihood of 
+    test data under a mixture model of these KDEs.
+    
+    The mixture weights correspond to class prevalences, optimized under the simplex 
+    constraint. The optimization minimizes the negative log-likelihood of the mixture
+    density evaluated at test posteriors.
+
+    This approach generalizes EM-based quantification methods by using KDE instead 
+    of discrete histograms, allowing smooth multivariate density estimation over 
+    the probability simplex.
+
+    References
+    ----------
+    The method is based on ideas presented by Moreo et al. (2023), extending KDE-based 
+    approaches for distribution matching and maximum likelihood estimation.
+    """
+
+    def _precompute_training(self, train_predictions, train_y_values):
+        r"""
+        Fit KDE models on class-specific training posterior predictions.
+        """
+        super()._fit_kde_models(train_predictions, train_y_values)
+
+    def _solve_prevalences(self, predictions):
+        r"""
+        Estimate class prevalences by maximizing log-likelihood under KDE mixture.
+        
+        Parameters
+        ----------
+        predictions : ndarray, shape (n_samples, n_features)
+            Posterior probabilities of test set instances.
+
+        Returns
+        -------
+        alpha_opt : ndarray, shape (n_classes,)
+            Estimated class prevalences.
+        min_loss : float
+            Minimum negative log-likelihood achieved.
+
+        Notes
+        -----
+        The optimization is solved over the probability simplex.
+        """
+        n_classes = len(self._class_kdes)
+        class_likelihoods = np.array([
+            np.exp(kde.score_samples(predictions)) + EPS for kde in self._class_kdes
+        ])  # (n_classes, n_samples)
+
+        def objective(alpha):
+            mixture = np.dot(alpha, class_likelihoods)
+            return negative_log_likelihood(mixture)
+
+        alpha_opt, min_loss = _optimize_on_simplex(objective, n_classes)
+        
+        self.best_distance = min_loss
+
+        return alpha_opt, min_loss
+
+
+# ============================================================
+# KDEy-HD — Hellinger Distance Minimization
+# ============================================================
+
+class KDEyHD(BaseKDE):
+    r"""KDEy Hellinger Distance Minimization quantifier.
+    
+    Estimates class prevalences by minimizing the Hellinger distance \( HD \) between
+    the KDE mixture of class-conditional densities and the KDE of test data, estimated
+    via Monte Carlo sampling and importance weighting.
+    
+    This stochastic approximation enables practical optimization of complex divergence
+    measures otherwise lacking closed-form expressions for Gaussian Mixture Models.
+
+    Parameters
+    ----------
+    montecarlo_trials : int
+        Number of Monte Carlo samples used in approximation.
+    random_state : int or None
+        Seed or random state for reproducibility.
+
+    References
+    ----------
+    Builds on f-divergence Monte Carlo approximations for KDE mixtures as detailed 
+    by Moreo et al. (2023) and importance sampling techniques.
+    """
+
+    _parameter_constraints = {
+        "montecarlo_trials": [Interval(1, None)],
+    }
+
+    def __init__(self, learner=None, bandwidth=0.1, kernel="gaussian", montecarlo_trials=1000, random_state=None):
+        super().__init__(learner, bandwidth, kernel)
+        self.montecarlo_trials = montecarlo_trials
+        self.random_state = random_state
+
+    def _precompute_training(self, train_predictions, train_y_values):
+        """
+        Precompute reference samples from class KDEs and their densities.
+        """
+        super()._fit_kde_models(train_predictions, train_y_values)
+        n_class = len(self._class_kdes)
+        trials = int(self.montecarlo_trials)
+        rng = check_random_state(self.random_state)
+        # Convert to integer seed for sklearn compatibility
+        seed = rng.integers(0, 2**31 - 1) if hasattr(rng, 'integers') else self.random_state
+
+        samples = np.vstack([
+            kde.sample(max(1, trials // n_class), random_state=seed)
+            for kde in self._class_kdes
+        ])
+
+        ref_classwise = np.array([np.exp(k.score_samples(samples)) + EPS for k in self._class_kdes])
+        ref_density = np.mean(ref_classwise, axis=0) + EPS
+
+        self._ref_samples = samples
+        self._ref_classwise = ref_classwise
+        self._ref_density = ref_density
+
+    def _solve_prevalences(self, predictions):
+        """
+        Minimize Hellinger distance between test KDE and mixture KDE via importance sampling.
+        """
+        test_kde = KernelDensity(bandwidth=self.bandwidth).fit(predictions)
+        qs = np.exp(test_kde.score_samples(self._ref_samples)) + EPS
+        iw = qs / self._ref_density
+        fracs = self._ref_classwise / qs
+
+        def objective(alpha):
+            alpha = np.clip(alpha, EPS, None)
+            alpha /= np.sum(alpha)
+            ps_div_qs = np.dot(alpha, fracs)
+            vals = (np.sqrt(ps_div_qs) - 1.0) ** 2 * iw
+            return np.mean(vals)
+
+        alpha_opt, min_loss = _optimize_on_simplex(objective, len(self._class_kdes))
+
+        self.best_distance = min_loss
+
+        return alpha_opt, min_loss
+
+
+# ============================================================
+# KDEy-CS — Cauchy–Schwarz Divergence
+# ============================================================
+
+class KDEyCS(BaseKDE):
+    r"""KDEy Cauchy-Schwarz Divergence quantifier.
+    
+    Uses a closed-form solution for minimizing the Cauchy-Schwarz (CS) divergence between
+    Gaussian Mixture Models representing class-conditional densities fitted via KDE.
+    
+    This mathematically efficient approach leverages precomputed kernel Gram matrices
+    of train-train, train-test, and test-test instances for fast divergence evaluation,
+    enabling scalable multiclass quantification.
+
+    References
+    ----------
+    Based on closed-form CS divergence derivations by Kampa et al. (2011) and KDEy 
+    density representations, as discussed by Moreo et al. (2023).
+    """
+
+    def _precompute_training(self, train_predictions, train_y_values):
+        """
+        Precompute kernel sums and Gram matrices needed for CS divergence evaluation.
+        """
+        P = np.atleast_2d(train_predictions)
+        y = np.asarray(train_y_values)
+        centers = [P[y == c] for c in self.classes_]
+        counts = np.array([len(x) if len(x) > 0 else 1 for x in centers])
+        h_eff = np.sqrt(2) * self.bandwidth
+
+        B_bar = np.zeros((len(self.classes_), len(self.classes_)))
+        for i, Xi in enumerate(centers):
+            for j, Xj in enumerate(centers[i:], start=i):
+                val = np.sum(gaussian_kernel(Xi, Xj, h_eff))
+                B_bar[i, j] = B_bar[j, i] = val
+        self._centers = centers
+        self._counts = counts
+        self._B_bar = B_bar
+        self._h_eff = h_eff
+
+    def _solve_prevalences(self, predictions):
+        """
+        Minimize Cauchy-Schwarz divergence over class mixture weights on the probability simplex.
+        """
+        Pte = np.atleast_2d(predictions)
+        n = len(self.classes_)
+        a_bar = np.array([np.sum(gaussian_kernel(Xi, Pte, self._h_eff)) for Xi in self._centers])
+        counts = self._counts + EPS
+        B_bar = self._B_bar + EPS
+        t = 1.0 / max(1, Pte.shape[0])
+
+        def objective(alpha):
+            alpha = np.clip(alpha, EPS, None)
+            alpha /= np.sum(alpha)
+            rbar = alpha / counts
+            partA = -np.log(np.dot(rbar, a_bar) * t + EPS)
+            partB = 0.5 * np.log(rbar @ (B_bar @ rbar) + EPS)
+            return partA + partB
+
+        alpha_opt, min_loss = _optimize_on_simplex(objective, n)
+
+        self.best_distance = min_loss
+
+        return alpha_opt, min_loss

mlquantify/neighbors/_utils.py

@@ -0,0 +1,131 @@
+import numpy as np
+from sklearn.metrics import pairwise_distances
+from math import pi
+from scipy.optimize import minimize
+
+
+EPS = 1e-12
+
+# ============================================================
+# Utilitários
+# ============================================================
+
+def gaussian_kernel(X, Y, bandwidth):
+    r"""Compute the Gaussian kernel matrix K(x, y) with specified bandwidth.
+
+    This kernel matrix represents the similarity between each pair of points in X and Y,
+    computed using the Gaussian (RBF) kernel function:
+
+    .. math::
+
+        K(x, y) = \frac{1}{(2 \pi)^{D/2} h^D} \exp\left(- \frac{\|x - y\|^2}{2 h^2}\right)
+
+    where :math:`h` is the bandwidth (smoothing parameter), and :math:`D` is the dimensionality
+    of the input feature space.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_samples_X, n_features)
+        Input data points.
+    Y : array-like of shape (n_samples_Y, n_features) or None
+        Input data points for kernel computation. If None, defaults to X.
+    bandwidth : float
+        Kernel bandwidth parameter :math:`h`.
+
+    Returns
+    -------
+    K : ndarray of shape (n_samples_X, n_samples_Y)
+        Gaussian kernel matrix.
+    """
+    X = np.atleast_2d(X)
+    if Y is None:
+        Y = X
+    else:
+        Y = np.atleast_2d(Y)
+    sqd = pairwise_distances(X, Y, metric="euclidean") ** 2
+    D = X.shape[1]
+    norm = (bandwidth ** D) * ((2 * pi) ** (D / 2))
+    return np.exp(-sqd / (2 * (bandwidth ** 2))) / (norm + EPS)
+
+
+def negative_log_likelihood(mixture_likelihoods):
+    r"""Compute the negative log-likelihood of given mixture likelihoods in a numerically stable way.
+
+    Given mixture likelihood values :math:`p_i` for samples, the negative log-likelihood is:
+
+    .. math::
+
+        - \sum_i \log(p_i)
+
+    Numerical stability is achieved by clipping likelihoods below a small epsilon.
+
+    Parameters
+    ----------
+    mixture_likelihoods : array-like
+        Likelihood values for the mixture distribution evaluated at samples.
+
+    Returns
+    -------
+    nll : float
+        Negative log-likelihood value.
+    """
+    mixture_likelihoods = np.clip(mixture_likelihoods, EPS, None)
+    return -np.sum(np.log(mixture_likelihoods))
+
+
+def _simplex_constraints(n):
+    r"""Define constraints and bounds for optimization over the probability simplex.
+
+    The simplex is defined as all vectors :math:`\alpha \in \mathbb{R}^n` such that:
+
+    .. math::
+
+        \alpha_i \geq 0, \quad \sum_{i=1}^n \alpha_i = 1
+
+    Parameters
+    ----------
+    n : int
+        Dimensionality of the simplex (number of mixture components).
+
+    Returns
+    -------
+    constraints : list of dict
+        List containing equality constraint for sum of elements equaling 1.
+    bounds : list of tuple
+        Bounds for each element to lie between 0 and 1.
+    """
+    cons = [{"type": "eq", "fun": lambda a: np.sum(a) - 1.0}]
+    bounds = [(0.0, 1.0) for _ in range(n)]
+    return cons, bounds
+
+
+def _optimize_on_simplex(objective, n, x0=None):
+    r"""Minimize an objective function over the probability simplex.
+
+    This function solves for mixture weights \( \boldsymbol{\alpha} \) that minimize the 
+    objective function under the constraints \(\alpha_i \geq 0\) and \(\sum_i \alpha_i = 1\).
+
+    The optimization uses Sequential Least SQuares Programming (SLSQP).
+
+    Parameters
+    ----------
+    objective : callable
+        The objective function to minimize. It should accept a vector of length n and
+        return a scalar loss.
+    n : int
+        Number of mixture components (dimension of \( \boldsymbol{\alpha} \)).
+    x0 : array-like, optional
+        Initial guess for \( \boldsymbol{\alpha} \). If None, defaults to uniform.
+
+    Returns
+    -------
+    alpha_opt : ndarray of shape (n,)
+        Optimized mixture weights summing to one.
+    """
+    if x0 is None:
+        x0 = np.ones(n) / n
+    cons, bounds = _simplex_constraints(n)
+    res = minimize(objective, x0, method="SLSQP", constraints=cons, bounds=bounds)
+    x = np.clip(getattr(res, "x", x0), 0.0, None)
+    s = np.sum(x)
+    return x / s if s > 0 else np.ones(n) / n

mlquantify/neural/__init__.py

@@ -0,0 +1 @@
+# TODO

mlquantify/utils/__init__.py

@@ -1,2 +1,47 @@
-from .general import *
-from .method import *
+from mlquantify.utils._tags import (
+    Tags,
+    TargetInputTags,
+    get_tags
+)   
+from mlquantify.utils._constraints import (
+    Interval,
+    Options,
+    CallableConstraint
+)
+from mlquantify.utils.prevalence import (
+    get_prev_from_labels,
+    normalize_prevalence
+)
+from mlquantify.utils._load import load_quantifier
+from mlquantify.utils._artificial import make_prevs
+from mlquantify.utils._context import validation_context, is_validation_skipped
+from mlquantify.utils._decorators import _fit_context
+from mlquantify.utils._exceptions import (
+    InputValidationError,
+    InvalidParameterError,
+    NotFittedError
+)
+from mlquantify.utils._get_scores import apply_cross_validation
+from mlquantify.utils._parallel import resolve_n_jobs
+from mlquantify.utils._random import check_random_state
+from mlquantify.utils._sampling import (
+    simplex_uniform_kraemer,
+    simplex_grid_sampling,
+    simplex_uniform_sampling,
+    get_indexes_with_prevalence
+)
+from mlquantify.utils._validation import (
+    _validate_is_numpy_array,
+    _validate_2d_predictions,
+    _validate_1d_predictions,
+    validate_y,
+    validate_predictions,
+    validate_parameter_constraints,
+    validate_learner_contraints,
+    _is_fitted,
+    check_is_fitted,
+    _is_arraylike_not_scalar,
+    _is_arraylike,
+    validate_data,
+    check_classes_attribute
+)

mlquantify/utils/_artificial.py

@@ -0,0 +1,27 @@
+import numpy as np
+
+
+def make_prevs(ndim:int) -> list:
+    """
+    Generate a list of n_dim values uniformly distributed between 0 and 1 that sum exactly to 1.
+    
+    Parameters
+    ----------
+    ndim : int
+        Number of dimensions.
+    
+    Returns
+    -------
+    list
+        List of n_dim values uniformly distributed between 0 and 1 that sum exactly to 1.
+    """
+    # Generate n_dim-1 random u_dist uniformly distributed between 0 and 1
+    u_dist = np.random.uniform(0, 1, ndim - 1)
+    # Add 0 and 1 to the u_dist
+    u_dist = np.append(u_dist, [0, 1])
+    # Sort the u_dist
+    u_dist.sort()
+    # Calculate the differences between consecutive u_dist
+    prevs = np.diff(u_dist)
+
+    return prevs