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

mlquantify/utils/_constraints.py

@@ -0,0 +1,219 @@
+from dataclasses import dataclass
+import numbers
+import numpy as np
+from abc import ABC, abstractmethod
+
+
+@dataclass
+class Interval:
+    """Represents a numeric range constraint."""
+    left: float | int | None
+    right: float | int | None
+    inclusive_left: bool = True
+    inclusive_right: bool = True
+    discrete: bool = False
+
+    def is_satisfied_by(self, value):
+        if not isinstance(value, (int, float, np.number)):
+            return False
+        if self.left is not None:
+            if self.inclusive_left and value < self.left:
+                return False
+            if not self.inclusive_left and value <= self.left:
+                return False
+        if self.right is not None:
+            if self.inclusive_right and value > self.right:
+                return False
+            if not self.inclusive_right and value >= self.right:
+                return False
+        if self.discrete and not float(value).is_integer():
+            return False
+        return True
+
+    def __str__(self):
+        left_bracket = "[" if self.inclusive_left else "("
+        right_bracket = "]" if self.inclusive_right else ")"
+        return f"{left_bracket}{self.left}, {self.right}{right_bracket}"
+
+
+@dataclass
+class Options:
+    """Represents a fixed set of allowed values."""
+    options: list
+
+    def is_satisfied_by(self, value):
+        return value in self.options
+
+    def __str__(self):
+        return f"one of {self.options}"
+    
+@dataclass
+class _ArrayLikes:
+    """Constraint representing array-likes"""
+
+    def is_satisfied_by(self, val):
+        from mlquantify.utils._validation import _is_arraylike_not_scalar
+        return _is_arraylike_not_scalar(val)
+
+    def __str__(self):
+        return "an array-like"
+
+@dataclass
+class HasMethods:
+    """Ensures that an object implements specific methods."""
+    methods: list[str]
+
+    def is_satisfied_by(self, value):
+        return all(hasattr(value, m) and callable(getattr(value, m)) for m in self.methods)
+
+    def __str__(self):
+        return f"an object implementing {', '.join(self.methods)}"
+
+
+@dataclass
+class Hidden:
+    """Used for internal constraints not shown to the user."""
+    constraint: object
+
+    def is_satisfied_by(self, value):
+        return self.constraint.is_satisfied_by(value)
+
+    @property
+    def hidden(self):
+        return True
+
+    def __str__(self):
+        return "<hidden constraint>"
+    
+    
+def _type_name(t):
+    """Convert type into human readable string."""
+    module = t.__module__
+    qualname = t.__qualname__
+    if module == "builtins":
+        return qualname
+    elif t == numbers.Real:
+        return "float"
+    elif t == numbers.Integral:
+        return "int"
+    return f"{module}.{qualname}"
+    
+
+
+class _Constraint(ABC):
+    """Base class for the constraint objects."""
+
+    def __init__(self):
+        self.hidden = False
+
+    @abstractmethod
+    def is_satisfied_by(self, val):
+        """Whether or not a value satisfies the constraint.
+
+        Parameters
+        ----------
+        val : object
+            The value to check.
+
+        Returns
+        -------
+        is_satisfied : bool
+            Whether or not the constraint is satisfied by this value.
+        """
+
+    @abstractmethod
+    def __str__(self):
+        """A human readable representational string of the constraint."""
+
+
+    
+class _InstancesOf(_Constraint):
+    """Constraint representing instances of a given type.
+
+    Parameters
+    ----------
+    type : type
+        The valid type.
+    """
+
+    def __init__(self, type):
+        super().__init__()
+        self.type = type
+
+    def is_satisfied_by(self, val):
+        return isinstance(val, self.type)
+
+    def __str__(self):
+        return f"an instance of {_type_name(self.type)!r}"
+
+
+def make_constraint(obj):
+    """Normalize strings and simple types into constraint objects."""
+    if isinstance(obj, str) and obj == "array-like":
+        return _ArrayLikes()
+    if isinstance(obj, (Interval, Options, HasMethods, Hidden, CallableConstraint)):
+        return obj
+    if isinstance(obj, type):
+        return _InstancesOf(obj)
+    if isinstance(obj, str):
+        return StringConstraint(obj)
+    if obj is None:
+        return NoneConstraint()
+    raise TypeError(f"Unsupported constraint type: {obj!r}")
+
+
+@dataclass
+class TypeConstraint:
+    type_: type
+
+    def is_satisfied_by(self, value):
+        return isinstance(value, self.type_)
+
+    def __str__(self):
+        return f"instance of {self.type_.__name__}"
+
+
+@dataclass
+class CallableConstraint:
+
+    def is_satisfied_by(self, value):
+        return callable(value)
+
+    def __str__(self):
+        return f"a callable"
+
+
+@dataclass
+class StringConstraint:
+    """Predefined string keywords (e.g., 'array-like', 'random_state')."""
+    keyword: str
+
+    def is_satisfied_by(self, value):
+        import scipy.sparse as sp
+        import numpy as np
+
+        if self.keyword == "array-like":
+            return isinstance(value, (list, tuple, np.ndarray))
+        if self.keyword == "sparse matrix":
+            return sp.issparse(value)
+        if self.keyword == "boolean":
+            return isinstance(value, bool)
+        if self.keyword == "random_state":
+            return isinstance(value, (np.random.RandomState, int, type(None)))
+        if self.keyword == "nan":
+            return value is np.nan
+        return False
+
+    def __str__(self):
+        return self.keyword
+
+
+@dataclass
+class NoneConstraint:
+    """Allows None as valid value."""
+
+    def is_satisfied_by(self, value):
+        return value is None
+
+    def __str__(self):
+        return "None"

mlquantify/utils/_context.py

@@ -0,0 +1,21 @@
+import contextlib
+import threading
+
+# Thread-local flag para suportar execuções paralelas
+_validation_context = threading.local()
+
+
+@contextlib.contextmanager
+def validation_context(skip: bool = False):
+    """Context manager para controlar se a validação deve ser ignorada."""
+    old_state = getattr(_validation_context, "skip_validation", False)
+    _validation_context.skip_validation = skip
+    try:
+        yield
+    finally:
+        _validation_context.skip_validation = old_state
+
+
+def is_validation_skipped():
+    """Verifica se a validação está desativada no contexto atual."""
+    return getattr(_validation_context, "skip_validation", False)

mlquantify/utils/_decorators.py

@@ -0,0 +1,36 @@
+from functools import wraps
+
+from mlquantify.utils._validation import _is_fitted
+from mlquantify.utils._context import validation_context, is_validation_skipped
+
+
+def _fit_context(prefer_skip_nested_validation: bool = False):
+    """
+    Decorator to manage validation context during the fit process.
+    
+    Parameters
+    ----------
+    prefer_skip_nested_validation : bool, optional
+        If True, prefer to skip nested validation during fitting, by default False.
+    """
+    def decorator(fit_method):
+        @wraps(fit_method)
+        def wrapper(estimator, *args, **kwargs):
+            global_skip_validation = is_validation_skipped()
+
+            # Avoid validation for partial_fit if already fitted
+            partial_fit_and_fitted = (
+                fit_method.__name__ == "partial_fit" and _is_fitted(estimator)
+            )
+
+            if not global_skip_validation and not partial_fit_and_fitted:
+                estimator._validate_params()
+
+            with validation_context(
+                skip=(prefer_skip_nested_validation or global_skip_validation)
+            ):
+                return fit_method(estimator, *args, **kwargs)
+
+        return wrapper
+
+    return decorator

mlquantify/utils/_exceptions.py

@@ -0,0 +1,12 @@
+# mlquantify/utils/_exceptions.py
+class InputValidationError(ValueError):
+    """Raised when invalid predictions are passed to a quantifier."""
+    pass
+
+class InvalidParameterError(ValueError):
+    """Raised when a parameter value does not meet its constraint."""
+    pass
+
+class NotFittedError(ValueError):
+    """Raised when an operation is attempted on an unfitted quantifier."""
+    pass

mlquantify/utils/_get_scores.py

@@ -0,0 +1,159 @@
+import numpy as np
+from sklearn.model_selection import KFold, StratifiedKFold
+
+def apply_cross_validation(
+    model,
+    X: np.ndarray,
+    y: np.ndarray,
+    cv= 5,
+    function= 'predict_proba',
+    stratified= True,
+    random_state= None,
+    shuffle= True):
+    """
+    Perform cross-validation and return predictions with true labels for each fold.
+    
+    Parameters:
+    -----------
+    model : estimator
+        Model with fit and predict/predict_proba methods
+    X : np.ndarray
+        Feature matrix
+    y : np.ndarray
+        Target vector
+    cv : int, default=5
+        Number of cross-validation folds
+    function : str, default='predict_proba'
+        Method to use for predictions ('predict' or 'predict_proba' or any callable)
+    stratified : bool, default=True
+        Whether to use stratified cross-validation
+    random_state : int or None, default=None
+        Random state for reproducibility
+    shuffle : bool, default=True
+        Whether to shuffle data before splitting
+        
+    Returns:
+    --------
+    Tuple[np.ndarray, np.ndarray]
+        predictions, true_labels for all folds
+    """
+    
+    # Choose cross-validation strategy
+    if stratified:
+        cv_splitter = StratifiedKFold(
+            n_splits=cv, 
+            shuffle=shuffle, 
+            random_state=random_state
+        )
+    else:
+        cv_splitter = KFold(
+            n_splits=cv, 
+            shuffle=shuffle, 
+            random_state=random_state
+        )
+    
+    # Pre-allocate arrays
+    all_predictions = []
+    all_true_labels = []
+    
+    # Perform cross-validation
+    for train_idx, test_idx in cv_splitter.split(X, y):
+        X_train, X_test = X[train_idx], X[test_idx]
+        y_train, y_test = y[train_idx], y[test_idx]
+        
+        # Fit model
+        model.fit(X_train, y_train)
+        
+        if type(function) is str:
+            if not hasattr(model, function):
+                raise AttributeError(f"The model does not have the method '{function}'.")
+            predictions = getattr(model, function)(X_test)
+        elif callable(function):
+            predictions = function(X_test)
+        else:
+            raise ValueError("The 'function' parameter must be a string or a callable.")
+        
+        all_predictions.append(predictions)
+        all_true_labels.append(y_test)
+    
+    # Concatenate all predictions and labels
+    final_predictions = np.vstack(all_predictions) if function == 'predict_proba' else np.concatenate(all_predictions)
+    final_true_labels = np.concatenate(all_true_labels)
+    
+    return final_predictions, final_true_labels
+
+
+
+def apply_bootstrap(
+    model,
+    X: np.ndarray,
+    y: np.ndarray = None,
+    n_bootstraps: int = 100,
+    function: str = 'predict_proba',
+    random_state: int = None
+):
+    """
+    Perform bootstrap resampling and return predictions with true labels for each bootstrap sample.
+    If y is None, bootstrap and fit using only X, and check if model is fitted.
+    
+    Parameters:
+    -----------
+    model : estimator
+        Model with fit and predict/predict_proba methods
+    X : np.ndarray
+        Feature matrix
+    y : np.ndarray or None
+        Target vector (optional)
+    n_bootstraps : int, default=100
+        Number of bootstrap samples
+    function : str or callable, default='predict_proba'
+        Method to use for predictions ('predict' or 'predict_proba' or any callable)
+    random_state : int or None, default=None
+        Random state for reproducibility
+    """
+
+    if random_state is not None:
+        np.random.seed(random_state)
+
+    all_predictions = []
+    all_true_labels = [] if y is not None else None
+
+    for _ in range(n_bootstraps):
+        bootstrap_indices = np.random.choice(len(X), size=len(X), replace=True)
+        X_bootstrap = X[bootstrap_indices]
+        if y is not None:
+            y_bootstrap = y[bootstrap_indices]
+            model.fit(X_bootstrap, y_bootstrap)
+        else:
+            model.fit(X_bootstrap)
+
+            # Check if model is fitted - raise error if not
+            if not hasattr(model, "fitted_") or not getattr(model, "fitted_"):
+                # Some models have other indicators, as a fallback we could just pass
+                # or do other checks. For simplicity, we check fitted_
+                # If not fitted, raise exception
+                raise ValueError("Model does not appear to be fitted after fit(X).")
+
+        if type(function) is str:
+            if not hasattr(model, function):
+                raise AttributeError(f"The model does not have the method '{function}'.")
+            predictions = getattr(model, function)(X_bootstrap)
+        elif callable(function):
+            predictions = function(X_bootstrap)
+        else:
+            raise ValueError("The 'function' parameter must be a string or a callable.")
+
+        all_predictions.append(predictions)
+        if y is not None:
+            all_true_labels.append(y_bootstrap)
+
+    if function == 'predict_proba':
+        final_predictions = np.vstack(all_predictions)
+    else:
+        final_predictions = np.concatenate(all_predictions)
+
+    if y is not None:
+        final_true_labels = np.concatenate(all_true_labels)
+        return final_predictions, final_true_labels
+    else:
+        return final_predictions

mlquantify/utils/_load.py

@@ -0,0 +1,18 @@
+from joblib import load
+
+
+def load_quantifier(path:str):
+    """
+    Load a quantifier from a file.
+    
+    Parameters
+    ----------
+    path : str
+        Path to the file containing the quantifier.
+    
+    Returns
+    -------
+    Quantifier
+        Loaded quantifier.
+    """
+    return load(path)

mlquantify/utils/_parallel.py

@@ -0,0 +1,6 @@
+import os
+from joblib import effective_n_jobs
+
+def resolve_n_jobs(n_jobs=None):
+    """Resolve n_jobs like sklearn, with support for -1 and nested contexts."""
+    return effective_n_jobs(n_jobs)

mlquantify/utils/_random.py

@@ -0,0 +1,36 @@
+import numpy as np
+from numpy.random import RandomState, Generator, default_rng
+
+
+def check_random_state(seed=None):
+    """
+    Turn seed into a np.random.RandomState or np.random.Generator instance.
+
+    Parameters
+    ----------
+    seed : None, int, RandomState, Generator
+        - If None, return the global RandomState singleton used by np.random.
+        - If int, return a new RandomState instance seeded with seed.
+        - If RandomState or Generator, return it.
+        - Otherwise, raise ValueError.
+
+    Returns
+    -------
+    rng : np.random.Generator
+        A numpy random generator compatible with modern numpy APIs.
+    """
+    if seed is None or seed is np.random:
+        return default_rng()  # new independent generator each call
+    if isinstance(seed, (int, np.integer)):
+        return default_rng(seed)
+    if isinstance(seed, Generator):
+        return seed
+    if isinstance(seed, RandomState):
+        # Wrap legacy RandomState inside a Generator for uniformity
+        bitgen = np.random.MT19937()
+        bitgen.state = seed.get_state()
+        return Generator(bitgen)
+    raise ValueError(
+        f"{seed!r} cannot be used to seed a numpy random number generator. "
+        "Valid options are None, int, RandomState, or Generator."
+    )