vertebrae.utils.labels

Label helpers.

Functions

coerce_label_input(labels)	Coerce user-provided labels without breaking ragged multi-label rows.
normalize_targets(y[, label_names, target_type, ...])	Normalize single-label, multi-label, or explicit regression targets.
target_type(y[, label_names, target_type, target_names])	Return the target type for labels.
class_counts(y[, label_names, target_type, target_names])	Count labels while preserving scalar label values.
labelset_counts(y[, label_names, target_type, ...])	Count exact label combinations for a multi-label target.
target_summary(y[, label_names, target_type, target_names])	Return JSON-friendly target summary metadata.
metric_labels(y[, label_names, target_type, target_names])	Return labels in the shape expected by metric libraries.
canonical_metric_targets(y[, label_names, ...])	Return the stable label representation shared by local and artifact metrics.
labels_to_jsonable(y[, label_names, target_type, ...])	Serialize labels in the canonical artifact shape.
labels_to_artifact_jsonable(y[, label_names, ...])	Serialize labels using portable semantic keys for classification artifacts.
labels_from_jsonable(payload[, label_names, ...])	Load labels from an artifact JSON payload.
decode_label_artifact_metadata(metadata)	Validate and mark semantic-key fields loaded from a v2 labels artifact.
multilabel_indicator(y[, label_names, sparse_output])	Convert a multi-label target to a dense or CSR binary indicator matrix.
stratified_label_indices(y, rate[, random_state, ...])	Select deterministic label-aware sample indices.
regression_subsample_indices(y, n_take[, random_state])	Select deterministic regression rows while preserving target variation.
display_label(label)	Convert a label value to display text.
display_labelset(labelset)	Convert a multi-label labelset to display text.
normalize_label_paths(label_paths, n_samples)	Validate and normalize one hierarchy path per sample.
normalize_level_names(level_names, max_depth)	Validate optional hierarchy level names.
normalize_label_names(label_names)	Validate optional multi-label names.
hierarchy_depth(label_paths)	Return the maximum hierarchy depth.
label_view_from_paths(label_paths, level[, level_names])	Derive a one-dimensional label view from hierarchy paths.
resolve_hierarchy_level(level, max_depth[, level_names])	Resolve an integer or named hierarchy level to a concrete index.
default_label_view_metadata()	Return metadata for the default dataset label view.
default_target_view_metadata()	Return metadata for the default dataset target view.
label_view_suffix(label_view)	Format a label-view suffix for result names.
target_view_suffix(target_view)	Format a target-view suffix for result names.

Module Contents

vertebrae.utils.labels.coerce_label_input(labels)

Coerce user-provided labels without breaking ragged multi-label rows.

Parameters:

labels (Any)

Return type:

Any

vertebrae.utils.labels.normalize_targets(y, label_names=None, target_type='auto', target_names=None)

Normalize single-label, multi-label, or explicit regression targets.

Single-label targets are returned as a one-dimensional array. Multi-label targets are returned as a one-dimensional object array where each element is a tuple of labels ordered by the resolved label names. Regression targets are returned as a one- or two-dimensional float array.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Tuple[numpy.ndarray, Dict[str, Any]]

vertebrae.utils.labels.target_type(y, label_names=None, target_type='auto', target_names=None)

Return the target type for labels.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

str

vertebrae.utils.labels.class_counts(y, label_names=None, target_type='auto', target_names=None)

Count labels while preserving scalar label values.

For multi-label targets, counts are per-label occurrence counts. Regression targets do not define classes and return an empty mapping.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Dict[Any, int]

vertebrae.utils.labels.labelset_counts(y, label_names=None, target_type='auto', target_names=None)

Count exact label combinations for a multi-label target.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Dict[str, int]

vertebrae.utils.labels.target_summary(y, label_names=None, target_type='auto', target_names=None)

Return JSON-friendly target summary metadata.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Dict[str, Any]

vertebrae.utils.labels.metric_labels(y, label_names=None, target_type='auto', target_names=None)

Return labels in the shape expected by metric libraries.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Tuple[Any, Dict[str, Any]]

vertebrae.utils.labels.canonical_metric_targets(y, label_names=None, target_type='auto', target_names=None)

Return the stable label representation shared by local and artifact metrics.

Regression targets remain numeric. Classification values become marked semantic keys so custom metrics observe the same values whether labels came directly from a dataset or from a portable v2 label artifact.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

numpy.ndarray

vertebrae.utils.labels.labels_to_jsonable(y, label_names=None, target_type='auto', target_names=None)

Serialize labels in the canonical artifact shape.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Any

vertebrae.utils.labels.labels_to_artifact_jsonable(y, label_names=None, target_type='auto', target_names=None)

Serialize labels using portable semantic keys for classification artifacts.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

Any

vertebrae.utils.labels.labels_from_jsonable(payload, label_names=None, target_type='auto', target_names=None, label_encoding=None)

Load labels from an artifact JSON payload.

Parameters:

• payload (Any)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

• label_encoding (Optional[str])

Return type:

numpy.ndarray

vertebrae.utils.labels.decode_label_artifact_metadata(metadata)

Validate and mark semantic-key fields loaded from a v2 labels artifact.

Parameters:

metadata (Dict[str, Any])

Return type:

Dict[str, Any]

vertebrae.utils.labels.multilabel_indicator(y, label_names=None, *, sparse_output=False)

Convert a multi-label target to a dense or CSR binary indicator matrix.

Parameters:

• y (Any)

• label_names (Optional[Iterable[Any]])

• sparse_output (bool)

Return type:

Any

vertebrae.utils.labels.stratified_label_indices(y, rate, random_state=42, min_samples_per_class=2, label_names=None, target_type='auto', target_names=None)

Select deterministic label-aware sample indices.

Parameters:

• y (Any)

• rate (float)

• random_state (int)

• min_samples_per_class (int)

• label_names (Optional[Iterable[Any]])

• target_type (str)

• target_names (Optional[Iterable[Any]])

Return type:

numpy.ndarray

vertebrae.utils.labels.regression_subsample_indices(y, n_take, random_state=42)

Select deterministic regression rows while preserving target variation.

Parameters:

• y (Any)

• n_take (int)

• random_state (int)

Return type:

numpy.ndarray

vertebrae.utils.labels.display_label(label)

Convert a label value to display text.

Parameters:

label (Any)

Return type:

str

vertebrae.utils.labels.display_labelset(labelset)

Convert a multi-label labelset to display text.

Parameters:

labelset (Any)

Return type:

str

vertebrae.utils.labels.normalize_label_paths(label_paths, n_samples)

Validate and normalize one hierarchy path per sample.

Parameters:

• label_paths (Any)

• n_samples (int)

Return type:

Tuple[Tuple[Any, Ellipsis], Ellipsis]

vertebrae.utils.labels.normalize_level_names(level_names, max_depth)

Validate optional hierarchy level names.

Parameters:

• level_names (Optional[Iterable[Any]])

• max_depth (int)

Return type:

Optional[Tuple[str, Ellipsis]]

vertebrae.utils.labels.normalize_label_names(label_names)

Validate optional multi-label names.

Parameters:

label_names (Optional[Iterable[Any]])

Return type:

Optional[Tuple[Any, Ellipsis]]

vertebrae.utils.labels.hierarchy_depth(label_paths)

Return the maximum hierarchy depth.

Parameters:

label_paths (Sequence[Sequence[Any]])

Return type:

int

vertebrae.utils.labels.label_view_from_paths(label_paths, level, level_names=None)

Derive a one-dimensional label view from hierarchy paths.

Parameters:

• label_paths (Sequence[Sequence[Any]])

• level (Union[int, str])

• level_names (Optional[Sequence[str]])

Return type:

Tuple[numpy.ndarray, Dict[str, Any]]

vertebrae.utils.labels.resolve_hierarchy_level(level, max_depth, level_names=None)

Resolve an integer or named hierarchy level to a concrete index.

Parameters:

• level (Union[int, str])

• max_depth (int)

• level_names (Optional[Sequence[str]])

Return type:

int

vertebrae.utils.labels.default_label_view_metadata()

Return metadata for the default dataset label view.

Return type:

Dict[str, Any]

vertebrae.utils.labels.default_target_view_metadata()

Return metadata for the default dataset target view.

Return type:

Dict[str, Any]

vertebrae.utils.labels.label_view_suffix(label_view)

Format a label-view suffix for result names.

Parameters:

label_view (Optional[Dict[str, Any]])

Return type:

str

vertebrae.utils.labels.target_view_suffix(target_view)

Format a target-view suffix for result names.

Parameters:

target_view (Optional[Dict[str, Any]])

Return type:

str