"""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)