mcode-neural 0.5.0__py3-none-any.whl

mcode_neural/data.py

@@ -0,0 +1,773 @@
+# region  F I L E
+# <copyright file="mcode-neural/src/mcode_neural/data.py" company="MicroCODE Incorporated">Copyright © 2026 MicroCODE, Inc. Troy, MI</copyright><author>Timothy J. McGuire</author>
+# region  M O D U L E
+# region  D O C U M E N T A T I O N
+"""
+Project:  MicroCODE Python Packages
+Customer: Internal + MIT xPRO Course
+@module   'mcode_neural.data'
+@memberof mcode_neural
+@created  October 2026
+@author   Timothy McGuire, MicroCODE, Inc.
+@description >
+MicroCODE Shared Dataset Library
+
+LICENSE:
+--------
+MIT License: MicroCODE.mcode-neural
+
+Copyright (c) 2026 Timothy McGuire, MicroCODE, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+DESCRIPTION:
+------------
+This module implements MicroCODE's common Python functions for preparing
+PyTorch datasets for training: reading every label of a dataset without
+loading its inputs; splitting a dataset into training and
+validation subsets, optionally stratified by class; splitting a PyTorch
+training dataset beside its test dataset into a model's train, val, and test
+data; splitting a pandas DataFrame into a model's standardized train, val, and
+test data; scaling new
+DataFrame rows the same way, as another phase; one DataLoader per phase; and
+a classifier's 'classes', a color and a name per label, for any number of classes.
+Each split returns a 'Data', of a kind in 'DATA_KINDS', which a model reads.
+
+
+REFERENCES:
+-----------
+1. MIT xPRO Course: AI and Deep Learning: Neural Network Applications
+
+2. PyTorch -- torch.utils.data (Dataset, Subset, random_split, TensorDataset, DataLoader)
+   https://pytorch.org/docs/stable/data.html
+
+3. pandas -- DataFrame.sample
+   https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.sample.html
+
+4. Python -- dataclasses
+   https://docs.python.org/3/library/dataclasses.html
+"""
+
+# endregion
+
+# region  I M P O R T S
+
+import math
+
+from dataclasses import dataclass
+
+import colorsys
+import numbers
+
+import pandas as pd
+import torch
+from torch.utils.data import DataLoader, Subset, TensorDataset
+
+# endregion
+
+# region  C O N S T A N T S
+
+# the phases 'data_frame_split()' makes, in the order a trainer runs them
+SPLIT_PHASES = ('train', 'val', 'test')
+LABEL_ATTRIBUTES = {  # where a dataset keeps its labels, in lookup order, each read without loading an input
+    'targets': lambda held: held,  # MNIST, CIFAR, ImageFolder
+    'labels': lambda held: held,  # SVHN, STL10
+    '_labels': lambda held: held,  # Flowers102, Food101, DTD, OxfordIIITPet
+    'y': lambda held: held,  # Caltech101
+    # GTSRB, StanfordCars: (path, label) pairs
+    '_samples': lambda held: [label for _, label in held],
+}
+# what all data of one kind holds, keyed by where it came from:
+#   has_features: it names its feature columns, 'feature', which label a neuron's weights
+#   has_scaling: it keeps a DataFrame contract, 'frame', so 'data_frame_phase()' can add rows
+DATA_KINDS = {
+    'frame': {'has_features': True, 'has_scaling': True},
+    'dataset': {'has_features': False, 'has_scaling': False},
+}
+# the colors of 'data_classes()': up to 10 classes, matplotlib's cycle, so every existing chart is unchanged
+CLASS_COLORS = tuple(f'C{k}' for k in range(10))
+# past 10, label k's hue is k x the golden ratio's conjugate around the wheel, so neighbors are never near in hue
+CLASS_HUE_STEP = 0.618033988749895
+CLASS_LIGHTNESS = (
+    0.62,
+    0.74,
+)  # alternating by label; both read on the dark chart background
+CLASS_SATURATION = 0.75
+
+# endregion
+
+# region  C L A S S E S
+
+
+@dataclass(frozen=True)
+class Data:
+    """
+    The data a model reads: its datasets by phase, and the contract that names and scales them.
+
+    Args:
+        kind:       where the data came from, a key of 'DATA_KINDS': "frame" for rows split from a
+                    DataFrame by 'data_frame_split()', "dataset" for PyTorch datasets, e.g. images.
+        datasets:   {phase: dataset}, e.g. {"train": ..., "val": ..., "test": ...}; each item is
+                    (features, labels), or (features,) for a phase with no labels.
+        feature:    one name per feature, in the model's column order, for "frame" data; None for
+                    "dataset" data, which has no named columns.
+        classes:    for a classifier, {label: (color, name)} for every label; None for a regressor;
+                    either for an autoencoder, whose latent view they color.
+        frame:      for "frame" data, the DataFrame contract 'data_frame_phase()' scales new rows by,
+                    {"label_column": a name or a list of names, "label_dtype": a torch dtype,
+                    "scaling": {column: (mean, std)}}; None for "dataset" data.
+        split:      how the datasets were split, the split function and its settings, e.g.
+                    {"function": "data_frame_split", "train_split": 0.6, ..., "seed": 42}, which the
+                    model's "data" event records; None when not recorded, e.g. data built by hand.
+
+    Note:
+        Frozen, so the contract is never replaced piece by piece; 'datasets' is a dict, so
+        'data_frame_phase()' can add a phase to it. A 'feature' or 'frame' its kind does not
+        hold, or lacks, fails by name.
+
+    Example:
+        >>> model.data = data_frame_split(df, input_columns, "color", torch.int64,
+        ...                               input_columns, wine_classes, seed=42)
+        >>> X, Y = model.data.samples("test")
+    """
+
+    kind: str
+    datasets: dict
+    feature: list | None
+    classes: dict | None
+    frame: dict | None
+    split: dict | None
+
+    def __post_init__(self):
+        if self.kind not in DATA_KINDS:
+            raise ValueError(
+                f"'Data' kind must be one of {list(DATA_KINDS)}, got {self.kind!r}"
+            )
+        row = DATA_KINDS[self.kind]
+        if (self.feature is not None) != row['has_features']:
+            needs = (
+                'names its features' if row['has_features'] else 'has no named features'
+            )
+            raise ValueError(
+                f"'Data' kind {self.kind!r} {needs}; got feature={self.feature!r}"
+            )
+        if (self.frame is not None) != row['has_scaling']:
+            needs = (
+                'keeps a DataFrame contract'
+                if row['has_scaling']
+                else 'has no DataFrame contract'
+            )
+            got = 'frame=None' if self.frame is None else 'a frame'
+            raise ValueError(f"'Data' kind {self.kind!r} {needs}; got {got}")
+
+    def samples(self, phase):
+        """
+        Returns every sample of one phase in one batch, as NumPy arrays.
+
+        Args:
+            phase:  the phase's name, a key of 'datasets', e.g. "test".
+
+        Returns:
+            (X, Y): X of shape (N, ...), one sample per row; Y of shape (N,) or (N, k), or None
+            for a phase with no labels.
+        """
+        dataset = self._dataset(phase)
+        # one batch of the whole phase: the default collate stacks any dataset's items, rows or images
+        batch = next(iter(DataLoader(dataset, batch_size=len(dataset))))
+        labels = batch[1].numpy() if len(batch) == 2 else None
+        return batch[0].numpy(), labels
+
+    def _dataset(self, phase):
+        """
+        Returns one phase's dataset, failing by name when the phase is missing or holds no samples.
+
+        Args:
+            phase:  the phase's name, a key of 'datasets', e.g. "test".
+        """
+        if phase not in self.datasets:
+            raise ValueError(
+                f"'model.data' has no phase {phase!r}; its phases are {list(self.datasets)}"
+            )
+        dataset = self.datasets[phase]
+        if len(dataset) == 0:
+            raise ValueError(f"'model.data' phase {phase!r} holds no samples")
+        return dataset
+
+    def _is_labeled(self, phase):
+        """Returns whether one phase's items hold labels, (features, labels), read from its first item."""
+        return len(self._dataset(phase)[0]) == 2
+
+
+# endregion
+
+# region  P R I V A T E   F U N C T I O N S
+
+
+def _held_labels(dataset):
+    """
+    Returns the labels a dataset holds, read without loading an input, or None when it holds none.
+
+    Args:
+        dataset:    any PyTorch dataset of (input, label) items.
+
+    Returns:
+        the labels as one tensor, one per datapoint, in the dataset's order: a Subset's are its
+        parent's at its indices, down to the root dataset; any other dataset's are its first
+        'LABEL_ATTRIBUTES' entry, through its 'target_transform' when it has one. None when
+        the dataset, or a Subset's root, holds none of them.
+    """
+    if isinstance(dataset, Subset):
+        labels = _held_labels(dataset.dataset)
+        if labels is None:
+            return None
+        return labels[torch.as_tensor(dataset.indices, dtype=torch.long)]
+    for attribute, read in LABEL_ATTRIBUTES.items():
+        held = getattr(dataset, attribute, None)
+        if held is not None:
+            labels = read(held)
+            # a dataset serves each label through its target_transform, one Python scalar at a time
+            transform = getattr(dataset, 'target_transform', None)
+            if transform is not None:
+                labels = [
+                    transform(label) for label in torch.as_tensor(labels).tolist()
+                ]
+            return torch.as_tensor(labels)
+    return None
+
+
+def _check_columns(df, name, columns):
+    """
+    Raises a ValueError naming 'name' unless every column is in 'df', numeric, and complete.
+
+    Args:
+        df:         the pandas DataFrame.
+        name:       the argument that named the columns, e.g. "feature_columns".
+        columns:    the column names to check.
+    """
+    for column in columns:
+        if column not in df.columns:
+            raise ValueError(
+                f"'{name}' names {column!r}, which is not a column of 'df'"
+            )
+        if not pd.api.types.is_numeric_dtype(df[column]):
+            raise ValueError(
+                f"'{name}' column {column!r} is {df[column].dtype}, not numeric; encode it first, e.g. one-hot"
+            )
+        if df[column].isna().any():
+            raise ValueError(f"'{name}' column {column!r} holds missing values (NaN)")
+
+
+def _check_labels(df, label_columns, label_dtype, classes):
+    """
+    Raises a ValueError naming the label column unless its labels fit 'label_dtype' and 'classes'.
+
+    Args:
+        df:             the pandas DataFrame, its label columns already checked by '_check_columns()'.
+        label_columns:  the label column names.
+        label_dtype:    the labels' torch dtype; an integer dtype would truncate fractions.
+        classes:        {label: (color, name)} that must name every label, or None for a regressor.
+    """
+    for column in label_columns:
+        if not label_dtype.is_floating_point and (df[column] % 1 != 0).any():
+            raise ValueError(
+                f"'label_column' {column!r} holds fractions, which 'label_dtype' {label_dtype} would truncate"
+            )
+        if classes is not None:
+            unknown = sorted(set(df[column].tolist()) - set(classes))
+            if unknown:
+                raise ValueError(
+                    f"'label_column' {column!r} holds {unknown}, not 'classes' labels {sorted(classes)}"
+                )
+
+
+def _class_color(label, count):
+    """
+    Returns a class's color: matplotlib's 'C0'-'C9' for up to 10 classes, else a golden-angle hex color.
+
+    Args:
+        label:  the class's label, 0 .. count - 1.
+        count:  the number of classes.
+    """
+    if count <= len(CLASS_COLORS):
+        return CLASS_COLORS[label]
+    hue = (label * CLASS_HUE_STEP) % 1
+    lightness = CLASS_LIGHTNESS[label % len(CLASS_LIGHTNESS)]
+    red, green, blue = colorsys.hls_to_rgb(hue, lightness, CLASS_SATURATION)
+    return f'#{round(red * 255):02x}{round(green * 255):02x}{round(blue * 255):02x}'
+
+
+# endregion
+
+# region  P U B L I C   F U N C T I O N S
+
+
+def data_labels(dataset):
+    """
+    Returns every label of a PyTorch dataset of (input, label) items, as one tensor, in the dataset's order.
+
+    Args:
+        dataset:    any PyTorch dataset of (input, label) items, e.g. a torchvision.datasets.GTSRB, or a
+                    torch.utils.data.Subset of one, as 'data_subset_split()' returns.
+
+    Returns:
+        the labels, one per datapoint, as the dataset serves them.
+
+    Note:
+        The labels are read where the dataset keeps them, so no input is loaded or transformed:
+        'targets' (MNIST, CIFAR, ImageFolder), 'labels' (SVHN, STL10), '_labels' (Flowers102,
+        Food101), 'y' (Caltech101), or the labels of '_samples' (GTSRB), each through the
+        dataset's 'target_transform' when it has one. A Subset reads its parent's labels at its
+        indices, down to the root dataset. Only a dataset that keeps no labels, or a Subset of
+        one, is read item by item, every input loaded.
+
+    Example:
+        >>> labels = data_labels(gtsrb_train)
+        >>> labels.bincount()                           # the datapoints of each class
+    """
+    labels = _held_labels(dataset)
+    if labels is None:
+        labels = torch.as_tensor([label for _, label in dataset])
+    return labels
+
+
+def data_subset_split(dataset, validate_split, seed=None, stratify=False):
+    """
+    Splits a dataset randomly into a training subset and a validation subset.
+
+    Args:
+        dataset:        any PyTorch dataset with a length, e.g. a torchvision.datasets.MNIST.
+        validate_split: the fraction of 'dataset' held out for validation, between 0 and 1, e.g. 1/6,
+                        as in Keras' 'validation_split'.
+        seed:           seeds the shuffle, so every run holds out the same datapoints; None for a new split each run.
+        stratify:       hold out 'validate_split' of each class, so both subsets keep the class proportions of
+                        'dataset'; the labels are read by 'data_labels()'.
+
+    Returns:
+        (train, validate), two torch.utils.data.Subset views of 'dataset'; no datapoints are copied.
+
+    Note:
+        Stratifying rounds each class's share separately, so the validation subset can differ from
+        'validate_split' of 'dataset' by up to half a datapoint per class.
+
+    Example:
+        >>> train, validate = data_subset_split(mnist_train, validate_split=1/6, seed=0, stratify=True)
+    """
+    if not 0 < validate_split < 1:
+        raise ValueError(
+            f"'validate_split' must be between 0 and 1, not {validate_split}"
+        )
+
+    # S E E D: one generator drives every shuffle below, so one seed repeats the whole split
+    # an unseeded torch.Generator() starts from the same fixed seed every run
+    generator = torch.Generator()
+    if seed is None:
+        generator.seed()
+    else:
+        generator.manual_seed(seed)
+
+    # R A N D O M   S P L I T: without 'stratify', one shuffle of the whole dataset
+    if not stratify:
+        train, validate = torch.utils.data.random_split(
+            dataset, [1 - validate_split, validate_split], generator=generator
+        )
+        return train, validate
+
+    # S T R A T I F I E D   S P L I T: hold out 'validate_split' of each class, class by class
+    labels = data_labels(dataset)
+
+    train_indices, validate_indices = [], []
+    for label in labels.unique():
+        indices = torch.nonzero(labels == label).flatten()
+        indices = indices[torch.randperm(len(indices), generator=generator)]
+        validate_count = round(len(indices) * validate_split)
+        validate_indices.append(indices[:validate_count])
+        train_indices.append(indices[validate_count:])
+
+    # the indices were gathered class by class, so an unshuffled DataLoader would serve one digit at a time
+    train_indices = torch.cat(train_indices)
+    validate_indices = torch.cat(validate_indices)
+    train_indices = train_indices[
+        torch.randperm(len(train_indices), generator=generator)
+    ]
+    validate_indices = validate_indices[
+        torch.randperm(len(validate_indices), generator=generator)
+    ]
+    return Subset(dataset, train_indices.tolist()), Subset(
+        dataset, validate_indices.tolist()
+    )
+
+
+def data_dataset_split(train, test, validate_split, classes, seed=None, stratify=False):
+    """
+    Splits a PyTorch training dataset into a model's train and val data, beside its own test dataset.
+
+    Args:
+        train:          the training dataset of (input, label) items, e.g. torchvision.datasets.MNIST(train=True).
+        test:           the test dataset of (input, label) items, e.g. torchvision.datasets.MNIST(train=False).
+        validate_split: the fraction of 'train' held out for validation, between 0 and 1, e.g. 1/6,
+                        as in Keras' 'validation_split'.
+        classes:        for a classifier, {label: (color, name)} naming every label in 'train' and 'test',
+                        e.g. {0: ("C0", "0 - zero"), ...}; None for a regressor; either for an
+                        autoencoder, whose latent view they color.
+        seed:           seeds the split, so every run holds out the same datapoints; None for a new split each run.
+        stratify:       hold out 'validate_split' of each class, so train and val keep the class proportions
+                        of 'train'.
+
+    Returns:
+        a "dataset" Data to set as 'model.data': its 'datasets' are "train" and "val", the two
+        torch.utils.data.Subset views of 'data_subset_split()', and "test", 'test' itself; its
+        'classes' are 'classes', and its 'feature' and 'frame' are None, as a dataset of images
+        has no named columns and no DataFrame scaling. Its 'split' is {"function":
+        "data_dataset_split", "validate_split", "seed", "stratify"}, for the model's history.
+
+    Note:
+        Each dataset keeps its own transform, e.g. ToTensor() and Normalize(); nothing is copied or
+        scaled here. Each dataset's labels are read by 'data_labels()'.
+
+    Example:
+        >>> mnist_train = torchvision.datasets.MNIST(data_dir, train=True, transform=transform)
+        >>> mnist_test = torchvision.datasets.MNIST(data_dir, train=False, transform=transform)
+        >>> digit_classes = {label: (f"C{label}", name) for label, name in enumerate(mnist_test.classes)}
+        >>> model.data = data_dataset_split(mnist_train, mnist_test, 1/6, digit_classes,
+        ...                                 seed=0, stratify=True)
+    """
+    # V A L I D A T E: the classes must name every label, so a stray label fails by name before training
+    if classes is not None:
+        if not isinstance(classes, dict):
+            raise TypeError(
+                f"'classes' must be {{label: (color, name)}}, or None for a regressor, not {classes!r}"
+            )
+        for name, dataset in {'train': train, 'test': test}.items():
+            unknown = sorted(set(data_labels(dataset).unique().tolist()) - set(classes))
+            if unknown:
+                raise ValueError(
+                    f"'{name}' holds labels {unknown}, not 'classes' labels {sorted(classes)}"
+                )
+
+    # S P L I T: hold out the val datapoints from 'train'; 'test' is already its own dataset
+    train_subset, val_subset = data_subset_split(
+        train, validate_split, seed=seed, stratify=stratify
+    )
+    datasets = dict(zip(SPLIT_PHASES, (train_subset, val_subset, test)))
+    split = {
+        'function': 'data_dataset_split',
+        'validate_split': validate_split,
+        'seed': seed,
+        'stratify': stratify,
+    }
+    return Data('dataset', datasets, None, classes, None, split)
+
+
+def data_frame_split(
+    df,
+    feature_columns,
+    label_column,
+    label_dtype,
+    standardize_columns,
+    classes,
+    train_split=0.6,
+    validate_split=0.2,
+    test_split=0.2,
+    seed=None,
+):
+    """
+    Splits a DataFrame into a model's train, val, and test data, standardized from the train rows only.
+
+    Args:
+        df:                     the pandas DataFrame, one row per datapoint, with a unique index.
+        feature_columns:        the feature column names, in the order the model reads them.
+        label_column:           the name of the label column; or a list of names, one label column each, e.g.
+                                the yes / no columns of a multi-label model.
+        label_dtype:            the labels' torch dtype: torch.int64 for class labels, as 'nn.CrossEntropyLoss'
+                                needs ('train_model()' casts 0 / 1 labels for 'nn.BCEWithLogitsLoss'), or
+                                torch.float32 for regression targets, as 'nn.MSELoss' needs.
+        standardize_columns:    the features to standardize, e.g. the numeric ones but not the one-hot
+                                ones; [] standardizes none. The other features pass through unscaled.
+        classes:                for a classifier, {label: (color, name)} naming every label in the label column(s),
+                                e.g. {0: ("tab:blue", "young"), 1: ("tab:orange", "old")}; None for a regressor;
+                                either for an autoencoder, whose latent view they color.
+        train_split:            the fraction of 'df' to train on.
+        validate_split:         the fraction of 'df' to validate on.
+        test_split:             the fraction of 'df' to test on; the three fractions sum to 1.
+        seed:                   seeds both samples, so every run splits the same rows; None for a new split each run.
+
+    Returns:
+        a "frame" Data to set as 'model.data': its 'datasets' hold a torch.utils.data.TensorDataset
+        per phase, "train", "val", and "test", of (features, labels): features
+        (N, len(feature_columns)) float32, labels (N,) 'label_dtype', or (N, len(label_column))
+        when 'label_column' is a list, (N, 1) for a list of one name. Its 'feature' is
+        'feature_columns', its 'classes' are 'classes', and its 'frame' keeps the label column(s),
+        'label_dtype', and each standardize column's (mean, std), for 'data_frame_phase()'. Its
+        'split' is {"function": "data_frame_split", "train_split", "validate_split",
+        "test_split", "seed"}, for the model's history.
+
+    Note:
+        Each standardize column becomes (x - mean) / std, with the mean and the population std
+        (ddof=0, as scikit-learn's 'StandardScaler') of the train rows only, so no val or test value
+        leaks into training. As in the course, 'test_split' of 'df' is sampled out first, then
+        'validate_split' of 'df' from the rest; seed=42 reproduces the course's rows in its order.
+
+    Example:
+        >>> model.data = data_frame_split(encoded_df, encoded_feature_columns, "Old", torch.int64,
+        ...                               numerical_feature_columns, abalone_classes, seed=42)
+    """
+    # V A L I D A T E: every column, dtype, and fraction fails by name before any row is sampled
+    feature_columns = list(feature_columns)
+    standardize_columns = list(standardize_columns)
+    is_label_list = isinstance(label_column, (list, tuple))
+    label_columns = list(label_column) if is_label_list else [label_column]
+    if not feature_columns:
+        raise ValueError(
+            "'feature_columns' is empty, so there are no features to split"
+        )
+    if not label_columns:
+        raise ValueError("'label_column' is empty, so there are no labels to split")
+    _check_columns(df, 'feature_columns', feature_columns)
+    _check_columns(df, 'label_column', label_columns)
+    for column in label_columns:
+        if column in feature_columns:
+            raise ValueError(
+                f"'label_column' {column!r} is also in 'feature_columns', so the model would read its own answer"
+            )
+    for column in standardize_columns:
+        if column not in feature_columns:
+            raise ValueError(
+                f"'standardize_columns' names {column!r}, which is not in 'feature_columns'"
+            )
+    if not isinstance(label_dtype, torch.dtype):
+        raise TypeError(
+            f"'label_dtype' must be a torch dtype, e.g. torch.int64 or torch.float32, not {label_dtype!r}"
+        )
+    if classes is not None and not isinstance(classes, dict):
+        raise TypeError(
+            f"'classes' must be {{label: (color, name)}}, or None for a regressor, not {classes!r}"
+        )
+    _check_labels(df, label_columns, label_dtype, classes)
+    fractions = {
+        'train_split': train_split,
+        'validate_split': validate_split,
+        'test_split': test_split,
+    }
+    for name, fraction in fractions.items():
+        if not 0 < fraction < 1:
+            raise ValueError(f"'{name}' must be between 0 and 1, not {fraction}")
+    total = sum(fractions.values())
+    if not math.isclose(total, 1):
+        raise ValueError(
+            f"'train_split' + 'validate_split' + 'test_split' must be 1, not {total}"
+        )
+    if not df.index.is_unique:
+        raise ValueError(
+            "'df' repeats an index label, so its rows cannot be told apart; call 'df.reset_index(drop=True)' first"
+        )
+
+    # S P L I T: sample the test rows out first, then the val rows from the rest, as the course does
+    # the course's two stages; 1 - 0.2 / 0.8 is exactly its 0.75, where 0.6 / 0.8 is 0.7499999999999999
+    train_val = df.sample(frac=1 - test_split, random_state=seed)
+    train = train_val.sample(
+        frac=1 - validate_split / (1 - test_split), random_state=seed
+    )
+    splits = dict(
+        zip(
+            SPLIT_PHASES, (train, train_val.drop(train.index), df.drop(train_val.index))
+        )
+    )
+    for phase, rows in splits.items():
+        if rows.empty:
+            raise ValueError(
+                f"the '{phase}' split of the {len(df)} rows in 'df' is empty; 'df' needs more rows"
+            )
+
+    # S T A N D A R D I Z E: the mean and std come from the train rows only, so no val or test value leaks into training
+    mean = train[standardize_columns].mean()
+    std = train[standardize_columns].std(ddof=0)
+    for column in standardize_columns:
+        if std[column] == 0:
+            raise ValueError(
+                f"'standardize_columns' column {column!r} is constant in the train rows, so it cannot be standardized"
+            )
+
+    # D A T A S E T S: one TensorDataset of (features, labels) per phase, scaled by the train rows
+    # pandas' own rule: a name selects a column, (N,); a list selects a frame, (N, k)
+    label_key = label_columns if is_label_list else label_column
+    datasets = {}
+    for phase, rows in splits.items():
+        features = rows[feature_columns].astype('float64')
+        features[standardize_columns] = (features[standardize_columns] - mean) / std
+        datasets[phase] = TensorDataset(
+            torch.tensor(features.to_numpy(), dtype=torch.float32),
+            torch.tensor(rows[label_key].to_numpy(), dtype=label_dtype),
+        )
+
+    # C O N T R A C T: what new rows need to be read the same way; plain floats, so a model saves it
+    frame = {
+        'label_column': label_key,
+        'label_dtype': label_dtype,
+        'scaling': {
+            column: (float(mean[column]), float(std[column]))
+            for column in standardize_columns
+        },
+    }
+    # the scaled columns are the keys of 'frame["scaling"]', so they are not repeated here
+    split = {'function': 'data_frame_split', **fractions, 'seed': seed}
+    return Data('frame', datasets, feature_columns, classes, frame, split)
+
+
+def data_frame_phase(model, phase, df):
+    """
+    Adds new DataFrame rows to a model's data as one more phase, scaled as its training rows were.
+
+    Args:
+        model:  a model whose data came from 'data_frame_split()', or 'model_load()' of one.
+        phase:  the new phase's name, e.g. "new"; not "train", "val", or "test", the split's own
+                rows. An existing phase of that name is replaced.
+        df:     the raw, unscaled rows: a pandas DataFrame holding every one of the model's feature
+                columns; and either every label column, to score the rows, or none, to predict them.
+
+    Note:
+        Each feature is scaled by the train rows' (mean, std) that 'data_frame_split()' kept in
+        'model.data.frame', and read in the model's own column order; extra columns are ignored.
+        The datasets of 'model.data' gain the phase; the model's weights are not touched.
+
+    Example:
+        >>> data_frame_phase(model, "new", new_wines)
+        >>> columns, probabilities = predict_classes(model, "new")
+    """
+    # V A L I D A T E: the model's contract, the phase name, and every column fail by name first
+    data = model.data
+    if not DATA_KINDS[data.kind]['has_scaling']:
+        raise ValueError(
+            "'model.data' did not come from 'data_frame_split()', so it has no scaling for new rows"
+        )
+    if phase in SPLIT_PHASES:
+        raise ValueError(
+            f"'phase' {phase!r} is one of the split's own phases {list(SPLIT_PHASES)}; name new rows another phase, e.g. 'new'"
+        )
+    if df.empty:
+        raise ValueError("'df' has no rows to add")
+    frame = data.frame
+    label_key = frame['label_column']
+    label_columns = label_key if isinstance(label_key, list) else [label_key]
+    _check_columns(df, 'feature_columns', data.feature)
+    present = [column for column in label_columns if column in df.columns]
+    # some labels but not all would score the rows against half an answer
+    if present and len(present) != len(label_columns):
+        missing = [column for column in label_columns if column not in present]
+        raise ValueError(
+            f"'df' holds label column(s) {present} but not {missing}; give every label column, or none"
+        )
+
+    # S C A L E: each standardize column by the train rows' (mean, std), the rest as they are
+    features = df[data.feature].astype('float64')
+    for column, (mean, std) in frame['scaling'].items():
+        features[column] = (features[column] - mean) / std
+    tensors = [torch.tensor(features.to_numpy(), dtype=torch.float32)]
+    if present:
+        _check_columns(df, 'label_column', label_columns)
+        _check_labels(df, label_columns, frame['label_dtype'], data.classes)
+        tensors.append(
+            torch.tensor(df[label_key].to_numpy(), dtype=frame['label_dtype'])
+        )
+    data.datasets[phase] = TensorDataset(*tensors)
+
+
+def data_loaders(datasets, batch_size):
+    """
+    Wraps each dataset in a DataLoader of 'batch_size' batches, keyed by the same phase names.
+
+    Args:
+        datasets:   {phase: dataset}, e.g. the train, val, and test datasets of 'data_frame_split()'.
+        batch_size: the number of datapoints in each batch.
+
+    Returns:
+        {phase: torch.utils.data.DataLoader}, the same keys in the same order.
+
+    Note:
+        No loader shuffles, as in the course: every epoch serves the same batches in the same order,
+        and 'data_frame_split()' has already put the train rows in random order. A phase's size is
+        'len(loaders[phase].dataset)', so no separate 'dataset_sizes' dict is needed.
+
+    Example:
+        >>> loaders = data_loaders(datasets, batch_size=10)
+    """
+    if not datasets:
+        raise ValueError("'datasets' is empty, so there are no loaders to make")
+    return {
+        phase: DataLoader(dataset, batch_size=batch_size)
+        for phase, dataset in datasets.items()
+    }
+
+
+def data_classes(names):
+    """
+    Returns a classifier's 'classes', {label: (color, name)}, for labels 0 .. n-1, each its own color.
+
+    Args:
+        names:  the class names in label order, a list or tuple of strings, e.g. 'dataset.classes';
+                or the number of classes, a whole number of at least 1, each then named by its label,
+                e.g. 43 for GTSRB, whose dataset names none.
+
+    Returns:
+        {0: (color, name), 1: (color, name), ...}, as 'data_frame_split()', 'data_dataset_split()',
+        and every classifier view take 'classes'.
+
+    Note:
+        Up to 10 classes take matplotlib's cycle, "C0" to "C9", as a hand-built dict did, so a
+        chart's colors are unchanged. Past 10, label k's hue is k times the golden ratio's
+        conjugate around the color wheel, so labels next to each other are never near in hue,
+        at two lightness levels, alternating, both readable on the charts' dark background;
+        each is a "#rrggbb" string, the same on every run, which 'model_save()' keeps.
+
+    Example:
+        >>> fashion_classes = data_classes(fashion_mnist_train.classes)
+        >>> gtsrb_classes = data_classes(43)            # names "0" ... "42"
+        >>> gtsrb_classes = data_classes(sign_names)    # 43 names, in label order
+    """
+    # V A L I D A T E: a list of names or a count, each failing by name
+    if isinstance(names, bool) or not isinstance(
+        names, (list, tuple, numbers.Integral)
+    ):
+        raise TypeError(
+            f"'names' must be a list of class names or a number of classes, got {type(names).__name__}"
+        )
+    if isinstance(names, numbers.Integral):
+        if names < 1:
+            raise ValueError(
+                f"'names' as a number of classes must be at least 1, got {names}"
+            )
+        names = [str(label) for label in range(names)]
+    if not names:
+        raise ValueError("'names' is empty, so there are no classes to name")
+    for label, name in enumerate(names):
+        if not isinstance(name, str):
+            raise TypeError(
+                f"'names[{label}]' must be a string, got {type(name).__name__}"
+            )
+
+    # C L A S S E S: one color and one name per label, in label order
+    return {
+        label: (_class_color(label, len(names)), name)
+        for label, name in enumerate(names)
+    }
+
+
+# endregion
+# endregion
+# endregion