Source code for skactiveml.utils._target

"""Resolution of target semantics."""

from dataclasses import dataclass

import numpy as np
from sklearn.preprocessing import LabelEncoder
from sklearn.utils.validation import check_array

from ._label import MISSING_LABEL, _check_labels, is_unlabeled
from ._label_dtype import (
    _as_class_vocabulary_array,
    _as_label_array,
    _check_compatible_kinds,
)
from ._validation import (
    _has_nested_classes,
    check_classes,
    check_classifier_params,
)


[docs] @dataclass(frozen=True) class TargetSpec: """Immutable description of resolved target semantics. Parameters ---------- task : "classification" or "regression" The prediction task. target_type : "single-output" or "multi-label" The resolved structure of one sample's target. annotation_type : "single-annotator" or "multi-annotator" Whether observations come from one or multiple annotators. classes : tuple or None The normalized immutable class vocabulary for classification, or `None` for regression. Single-output classification stores one tuple. Multi-label classification stores one binary tuple per label output. Specifications compare classes by value, so `(0, 1)` equals `(0.0, 1.0)`. """ task: str target_type: str annotation_type: str classes: tuple | None def __post_init__(self): _validate_target_semantics( self.task, self.target_type, self.annotation_type, allow_auto=False, ) if self.task == "classification" and self.classes is None: raise ValueError( "`classes` is required for classification targets." ) if self.task == "regression" and self.classes is not None: raise ValueError( "`classes` is not accepted for regression targets." ) if self.classes is not None: check_classes(self.classes) has_nested_classes = _check_class_vocabulary_structure( self.target_type, self.classes ) if has_nested_classes: normalized_classes = tuple( _normalize_class_vocabulary( classes_i, [], f"`classes[{output_idx}]`" ) for output_idx, classes_i in enumerate(self.classes) ) else: normalized_classes = _normalize_class_vocabulary( self.classes, [], "`classes`" ) object.__setattr__(self, "classes", normalized_classes) @classmethod def _from_normalized( cls, *, task, target_type, annotation_type, classes, ): """Construct a target specification from trusted normalized values.""" target_spec = object.__new__(cls) object.__setattr__(target_spec, "task", task) object.__setattr__(target_spec, "target_type", target_type) object.__setattr__(target_spec, "annotation_type", annotation_type) object.__setattr__(target_spec, "classes", classes) return target_spec
def _validate_target_semantics( task, target_type, annotation_type, *, allow_auto ): if task not in {"classification", "regression"}: raise ValueError( "`task` must be either 'classification' or 'regression'." ) target_types = {"single-output", "multi-label"} if allow_auto: target_types.add("auto") if target_type not in target_types: allowed = ( "{'auto', 'single-output', 'multi-label'}" if allow_auto else "{'single-output', 'multi-label'}" ) raise ValueError(f"`target_type` must be one of {allowed}.") if annotation_type not in {"single-annotator", "multi-annotator"}: raise ValueError( "`annotation_type` must be either 'single-annotator' or " "'multi-annotator'." ) if task == "regression" and target_type == "multi-label": raise ValueError( "`target_type='multi-label'` requires classification." ) if target_type == "multi-label" and annotation_type == "multi-annotator": raise ValueError( "Multi-label targets cannot be combined with " "`annotation_type='multi-annotator'`." ) def _check_class_vocabulary_structure(target_type, classes): """Validate nesting, width, and output dtypes against a target type.""" has_nested_classes = _has_nested_classes(classes) if target_type == "single-output" and has_nested_classes: raise ValueError( "Single-output classification requires a flat class vocabulary." ) if target_type == "multi-label": if not has_nested_classes: raise ValueError( "Multi-label classification requires nested binary class " "vocabularies." ) if not all(len(classes_i) == 2 for classes_i in classes): raise ValueError( "Each multi-label class vocabulary must contain exactly two " "classes." ) return has_nested_classes
[docs] def resolve_target_spec( y, *, task, target_type="auto", annotation_type="single-annotator", classes=None, missing_label=MISSING_LABEL, ): """Resolve declared intent and target evidence to a target specification. Parameters ---------- y : array-like of shape (n_samples,) or (n_samples, n_outputs) Target observations, including values equal to `missing_label`. task : "classification" or "regression" The prediction task. target_type : "auto" or "single-output" or "multi-label", default="auto" Declared target type. The returned specification is always concrete. annotation_type : "single-annotator" or "multi-annotator", \ default="single-annotator" Declared annotation type. classes : array-like or tuple of array-like, default=None Optional classification class vocabularies. A flat vocabulary describes single-output classification. Nested binary vocabularies describe multi-label classification. missing_label : scalar or str or None, default=np.nan Value representing a missing target observation. Returns ------- target_spec : TargetSpec The resolved immutable target specification. """ _validate_target_semantics( task, target_type, annotation_type, allow_auto=True ) if task == "regression" and classes is not None: raise ValueError("`classes` is not accepted for regression targets.") if task == "classification" and classes is not None: check_classifier_params(classes, missing_label) y = _check_target_array(y) if target_type == "auto": if annotation_type == "multi-annotator": if classes is not None and _has_nested_classes(classes): raise ValueError( "Nested class vocabularies contradict " "`annotation_type='multi-annotator'`." ) target_type = "single-output" elif task == "regression": target_type = "single-output" elif classes is not None: target_type = ( "multi-label" if _has_nested_classes(classes) else "single-output" ) elif y.ndim == 1 or y.shape[1] == 1: target_type = "single-output" else: raise ValueError( "Two-dimensional labels `y` are ambiguous, because they can " "be multi-label targets or the labels of several annotators. " "Declare multi-label targets on the classifier with " "`target_type='multi-label'` or nested binary `classes`, and " "pass the labels of several annotators to a multi-annotator " "component. For single-output labels, pass a one-dimensional " "`y`." ) if classes is not None: _check_class_vocabulary_structure(target_type, classes) if target_type == "multi-label": return _resolve_multilabel( y, classes=classes, missing_label=missing_label, ) _validate_single_output_shape(y, task, annotation_type) normalized_classes = None if task == "regression": _check_labels(y, missing_label, task="regression") else: observed = np.asarray(y)[~is_unlabeled(y, missing_label=missing_label)] declared = observed if classes is None else classes if classes is None and len(observed) == 0: raise ValueError( "No class label is observed and `classes` is not defined." ) normalized_classes = _normalize_class_vocabulary( declared, observed, "`classes`" ) if classes is None: check_classes(normalized_classes) return TargetSpec._from_normalized( task=task, target_type="single-output", annotation_type=annotation_type, classes=normalized_classes, )
def _resolve_task_agnostic_target_type( y, *, target_type="auto", missing_label=MISSING_LABEL, ): """Resolve target structure without assigning a prediction task.""" _validate_target_semantics( "classification", target_type, "single-annotator", allow_auto=True, ) y = _check_target_array(y) if target_type == "auto": if y.ndim == 2 and y.shape[1] != 1: raise ValueError( "Two-dimensional labels `y` are ambiguous for a strategy " "without a classifier, because they can be multi-label " "targets or the labels of several annotators. Declare " "multi-label targets with `target_type='multi-label'` on the " "strategy, and pass the labels of several annotators to a " "multi-annotator component. For single-output labels, pass a " "one-dimensional `y`." ) return "single-output" if target_type == "single-output": if y.ndim == 2 and y.shape[1] == 1: return target_type if y.ndim != 1: raise ValueError( "Single-output targets must be one-dimensional or a column " "vector." ) return target_type if y.ndim != 2: raise ValueError("Multi-label targets must be two-dimensional.") is_unlabeled( y, missing_label=missing_label, target_type="multi-label", ) return target_type def _check_target_array(y): y = check_array( _as_label_array(y), ensure_2d=False, ensure_all_finite=False, ensure_min_samples=0, dtype=None, ) if y.ndim == 0: raise TypeError("`y` must be a one- or two-dimensional array-like.") return y def _validate_single_output_shape(y, task, annotation_type): if annotation_type == "multi-annotator": if y.ndim != 2: raise ValueError( "Targets with multi-annotator annotation type must be " "two-dimensional." ) return if y.ndim == 2 and y.shape[1] != 1: if task == "classification": raise ValueError( "Single-output, single-annotator classification targets " "must be one-dimensional or a column vector." ) raise ValueError( "Single-output regression targets must be one-dimensional or a " "column vector." ) def _resolve_multilabel(y, *, classes, missing_label): if y.ndim != 2: raise ValueError("Multi-label targets must be two-dimensional.") is_missing = is_unlabeled( y, missing_label=missing_label, target_type="multi-label" ) observed_y = y[~is_missing] if classes is None: normalized_classes = [] for output_idx in range(y.shape[1]): classes_i = _normalize_class_vocabulary( observed_y[:, output_idx], observed_y[:, output_idx], f"`classes[{output_idx}]`", ) if len(classes_i) != 2: raise ValueError( "Each multi-label output must expose exactly two observed " "classes when `classes=None`; output " f"{output_idx} exposes {len(classes_i)}." ) normalized_classes.append(classes_i) else: if len(classes) != y.shape[1]: raise ValueError( "Multi-label `classes` must contain one vocabulary per " "target column." ) normalized_classes = [] for output_idx, declared in enumerate(classes): classes_i = _normalize_class_vocabulary( declared, observed_y[:, output_idx], f"`classes[{output_idx}]`", ) normalized_classes.append(classes_i) normalized_classes = tuple(normalized_classes) if classes is None: check_classes(normalized_classes) _check_class_vocabulary_structure("multi-label", normalized_classes) return TargetSpec._from_normalized( task="classification", target_type="multi-label", annotation_type="single-annotator", classes=normalized_classes, ) def _predicted_target_spec(target_spec): """Describe predictions independently of the training annotation type. Parameters ---------- target_spec : TargetSpec The fitted estimator's resolved training target specification. Returns ------- prediction_spec : TargetSpec The same task, target type, and class vocabulary with single-annotator semantics. """ if target_spec.annotation_type == "single-annotator": return target_spec return TargetSpec._from_normalized( task=target_spec.task, target_type=target_spec.target_type, annotation_type="single-annotator", classes=target_spec.classes, ) def _check_target_matches_spec(y, target_spec, *, missing_label): """Raise when `y` does not match a resolved target specification.""" resolve_target_spec( y, task=target_spec.task, target_type=target_spec.target_type, annotation_type=target_spec.annotation_type, classes=target_spec.classes, missing_label=missing_label, ) def _check_refit_capability(estimator): """Reject an estimator that a query cannot fit on single-annotator labels. A multi-annotator classifier would fit a column vector as the labels of one annotator without any error, so it is rejected before training. """ capabilities = estimator._target_capabilities if not any(c[2] == "single-annotator" for c in capabilities): raise ValueError( f"{type(estimator).__name__} does not support single-annotator " "labels `y`, so it cannot be fitted on them. Pass a fitted " "estimator instead." ) def _check_target_spec_capability(component, target_spec, capabilities): """Raise when a component does not declare an exact target capability.""" capability = ( target_spec.task, target_spec.target_type, target_spec.annotation_type, ) _check_target_capability(component, capability, capabilities) def _check_target_capability(component, capability, capabilities): """Raise when a component does not declare an exact semantic triple.""" if capability not in capabilities: supported = ", ".join(repr(value) for value in sorted(capabilities)) raise ValueError( f"{component} does not support target capability {capability!r}. " f"Supported capabilities are: {supported}." ) def _normalize_class_vocabulary(declared, observed, name): classes_array = _as_class_vocabulary_array(declared) classes_array = LabelEncoder().fit(classes_array).classes_ _check_compatible_kinds(observed, classes_array, name=name) if not np.isin(np.asarray(observed), classes_array).all(): raise ValueError( f"`y` contains labels outside {name}. All observed labels must " "belong to the class vocabulary, whether declared explicitly " "or inferred during fitting." ) return tuple(classes_array)