mcode-neural 0.5.0__py3-none-any.whl

mcode_neural/predict.py

@@ -0,0 +1,360 @@
+# region  F I L E
+# <copyright file="mcode-neural/src/mcode_neural/predict.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.predict'
+@memberof mcode_neural
+@created  October 2026
+@author   Timothy McGuire, MicroCODE, Inc.
+@description >
+MicroCODE Shared Prediction 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 predictions from our trained models, a
+single neuron or a network: a classifier's labels and class probabilities, a
+regressor's values, and the metrics of either one or of an autoencoder, each scored on one phase of the
+model's own data, without changing the model.
+
+
+REFERENCES:
+-----------
+1. MIT xPRO Course: AI and Deep Learning: Neural Network Applications
+
+2. PyTorch -- torch.no_grad and torch.nn.Module.eval
+   https://pytorch.org/docs/stable/generated/torch.no_grad.html
+   https://pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.eval
+
+3. Fawcett, T. -- An introduction to ROC analysis, Pattern Recognition Letters 27 (2006)
+   https://doi.org/10.1016/j.patrec.2005.10.010
+"""
+
+# endregion
+
+# region  I M P O R T S
+
+import numpy as np
+
+import torch
+from torch.utils.data import DataLoader
+
+from .model import _article, _check_model, _out_of_memory, _score_batch_size
+
+# endregion
+
+# region  P R I V A T E   F U N C T I O N S
+
+
+def _check_kind(model, kind, name):
+    """
+    Raises a TypeError unless 'model' is a mcode-neural Model, and a ValueError naming 'name' unless it is of 'kind'.
+
+    Args:
+        model:  the caller's model.
+        kind:   the kind the caller needs, "classification", "regression", or "autoencoder".
+        name:   the calling function, e.g. "predict_classes".
+    """
+    _check_model(model)
+    if model.kind != kind:
+        raise ValueError(
+            f"'{name}()' needs {_article(kind)} model; 'model' is {_article(model.kind)} model"
+        )
+
+
+def _phase_scores(model, phase, score):
+    """
+    Returns 'score(X)' for every sample of one phase, scored batch by batch, and the phase's labels.
+
+    Args:
+        model:  a Model, its data loaded.
+        phase:  a phase of 'model.data', e.g. "test".
+        score:  score(X) -> a NumPy array, or a tuple of them, one row per sample of the batch X,
+                a NumPy array, e.g. 'model.classify'.
+
+    Returns:
+        (scores, labels): scores as 'score()' returns them, each array gathered over every batch
+        in phase order; labels the phase's labels as a NumPy array, or None for a phase with none.
+
+    Note:
+        The phase is read through a loader of '_score_batch_size(model)' samples, so neither
+        system RAM nor the GPU holds it whole. A GPU out-of-memory error names the phase and
+        the batch size.
+    """
+    dataset = model.data._dataset(phase)
+    batch_size = _score_batch_size(model)
+    parts, labels = [], []
+    try:
+        for batch in DataLoader(dataset, batch_size=batch_size):
+            scores = score(batch[0].numpy())
+            parts.append(scores if isinstance(scores, tuple) else (scores,))
+            if len(batch) == 2:
+                labels.append(batch[1].numpy())
+    except torch.OutOfMemoryError as error:
+        device = next(model.parameters()).device
+        raise _out_of_memory(phase, batch_size, device) from error
+    gathered = tuple(np.concatenate(arrays) for arrays in zip(*parts))
+    if not isinstance(scores, tuple):
+        gathered = gathered[0]
+    return gathered, (np.concatenate(labels) if labels else None)
+
+
+def _roc_curve(is_up, scores):
+    """
+    Returns a binary classifier's ROC curve: its false and true positive rates at every threshold.
+
+    Args:
+        is_up:  every sample's truth as a bool array, True for the higher (positive) class.
+        scores: every sample's probability of the higher class.
+
+    Returns:
+        (fpr, tpr) arrays from (0, 0) to (1, 1), one point per distinct score, highest first.
+
+    Note:
+        Fawcett's algorithm (REFERENCES 3): samples tied on a score pass the threshold together,
+        so a tie of positives and negatives steps diagonally.
+    """
+    order = np.argsort(-scores, kind='stable')
+    ranked, is_up = scores[order], is_up[order]
+    # the last sample of each run of equal scores, where the threshold lets the whole run pass
+    last = np.r_[np.flatnonzero(np.diff(ranked)), len(ranked) - 1]
+    true_positives = np.cumsum(is_up)[last]
+    false_positives = np.cumsum(~is_up)[last]
+    fpr = np.r_[0, false_positives / false_positives[-1]]
+    tpr = np.r_[0, true_positives / true_positives[-1]]
+    return fpr, tpr
+
+
+def _fit_scores(prediction, actual):
+    """
+    Returns a regressor's fit: its mean absolute error, root mean squared error, and R².
+
+    Args:
+        prediction: every sample's predicted value.
+        actual:     every sample's target value, in the same order; not constant.
+
+    Returns:
+        {"mae": float, "rmse": float, "r2": float}
+    """
+    error = prediction - actual
+    squared = error**2
+    spread = ((actual - actual.mean()) ** 2).sum()
+    return {
+        'mae': float(np.abs(error).mean()),
+        'rmse': float(np.sqrt(squared.mean())),
+        'r2': float(1 - squared.sum() / spread),
+    }
+
+
+def _classifier_scores(model, phase):
+    """
+    Returns a classifier's accuracy, and its ROC AUC when it has two classes.
+
+    Args:
+        model:  a trained classifier with one label per sample.
+        phase:  a labeled phase of 'model.data'.
+    """
+    labels = sorted(model.data.classes)
+    (columns, probabilities), Y = _phase_scores(model, phase, model.classify)
+    actual = np.ravel(Y)
+    # k sigmoid outputs are k labels per sample, not one class to score
+    if columns.ndim != 1:
+        raise ValueError(
+            f"'model' has {columns.shape[1]} outputs per sample; its metrics need one label per sample"
+        )
+    if probabilities.shape[1] != len(labels):
+        raise ValueError(
+            f"'model' outputs {probabilities.shape[1]} classes; 'model.data.classes' has {len(labels)}"
+        )
+    scores = {'accuracy': float((np.asarray(labels)[columns] == actual).mean())}
+    # a ROC curve ranks one score, the higher class's probability, so only two classes have an AUC
+    if len(labels) == 2:
+        is_up = actual == labels[1]
+        if is_up.all() or not is_up.any():
+            raise ValueError(
+                "the phase needs both classes for a ROC curve's AUC; it holds only one"
+            )
+        fpr, tpr = _roc_curve(is_up, probabilities[:, 1])
+        scores['auc'] = float(np.trapezoid(tpr, fpr))
+    return scores
+
+
+def _regressor_scores(model, phase):
+    """
+    Returns a one-target regressor's MAE, RMSE, and R².
+
+    Args:
+        model:  a trained regressor with one target.
+        phase:  a labeled phase of 'model.data'.
+    """
+    prediction, Y = _phase_scores(model, phase, model.regress)
+    actual = np.ravel(Y)
+    if prediction.ndim != 1:
+        raise ValueError(
+            f"'model' has {prediction.shape[1]} outputs; its metrics need one target"
+        )
+    if np.ptp(actual) == 0:
+        raise ValueError("the phase's targets are constant, so R² is undefined")
+    return _fit_scores(prediction, actual)
+
+
+def _reconstruction_errors(model, X):
+    """
+    Returns an autoencoder's reconstruction of every sample, and each sample's mean squared error.
+
+    Args:
+        model:  a trained autoencoder.
+        X:      the input samples, (N, ...).
+
+    Returns:
+        (rebuilt, errors): rebuilt (N, in_features), each sample encoded and decoded; errors (N,),
+        each sample's mean of (rebuilt - input)² over its values.
+    """
+    rebuilt = model.reconstruct(X)
+    errors = ((rebuilt - X.reshape(len(X), -1)) ** 2).mean(axis=1)
+    return rebuilt, errors
+
+
+def _autoencoder_scores(model, phase):
+    """
+    Returns an autoencoder's mean squared error over every value of every sample, and its root.
+
+    Args:
+        model:  a trained autoencoder.
+        phase:  a labeled phase of 'model.data'; its labels are not read, an autoencoder is
+                scored against its input.
+    """
+    errors, _ = _phase_scores(
+        model, phase, lambda X: _reconstruction_errors(model, X)[1]
+    )
+    # every sample holds the same number of values, so the mean of the means is nn.MSELoss
+    mse = float(errors.mean())
+    return {'mse': mse, 'rmse': float(np.sqrt(mse))}
+
+
+# endregion
+
+# region  P U B L I C   F U N C T I O N S
+
+
+def predict_classes(model, phase):
+    """
+    Returns a classifier's predicted column and class probabilities for every sample of one phase.
+
+    Args:
+        model:  a trained classifier, a single neuron or a network, e.g.
+                LogisticClassifierNeuronModel or ClassificationModel, its data loaded.
+        phase:  the phase of 'model.data' to predict, e.g. "test", or one added by
+                'data_frame_phase()'; its labels, if any, are not read.
+
+    Returns:
+        (columns, probabilities) as NumPy arrays, columns int64 and probabilities float64:
+        one label per sample: (N,) columns and (N, k) probabilities, each row summing to 1;
+        a binary network's k labels: (N, k) columns, one 0 / 1 per output, and (N, k)
+        probabilities, each output's probability of 1.
+
+    Note:
+        A column is a position in the sorted labels of 'model.data.classes', from 0, as the
+        model was trained; 'sorted(model.data.classes)[column]' is its label. A network is
+        scored in eval() mode, without gradients, on its own device; a neuron does not touch
+        its cached z, a, grad_w, or grad_w_0. Neither one's weights or mode change.
+
+    Example:
+        >>> columns, probabilities = predict_classes(model, "test")
+    """
+    _check_kind(model, 'classification', 'predict_classes')
+    (columns, probabilities), _ = _phase_scores(model, phase, model.classify)
+    return columns, probabilities
+
+
+def predict_values(model, phase):
+    """
+    Returns a regressor's predicted value(s) for every sample of one phase.
+
+    Args:
+        model:  a trained regressor, a single neuron or a network, e.g. RegressorNeuronModel
+                or RegressionModel, its data loaded.
+        phase:  the phase of 'model.data' to predict, e.g. "test", or one added by
+                'data_frame_phase()'; its targets, if any, are not read.
+
+    Returns:
+        a float64 NumPy array: (N,) for one target, as the targets are, or (N, k) for k targets.
+
+    Note:
+        A network is scored in eval() mode, without gradients, on its own device; a neuron
+        does not touch its cached z, a, grad_w, or grad_w_0. Neither one's weights or mode change.
+
+    Example:
+        >>> values = predict_values(model, "test")
+    """
+    _check_kind(model, 'regression', 'predict_values')
+    values, _ = _phase_scores(model, phase, model.regress)
+    return values
+
+
+def predict_metrics(model, phase):
+    """
+    Returns a trained model's metrics on one labeled phase of its data, as plain numbers.
+
+    Args:
+        model:  a trained model, a single neuron or a network, its data loaded.
+        phase:  a phase of 'model.data' that has labels, e.g. "test".
+
+    Returns:
+        a classifier's {"accuracy": float}, plus "auc", its ROC AUC, when it has two classes;
+        a one-target regressor's {"mae": float, "rmse": float, "r2": float}; an autoencoder's
+        {"mse": float, "rmse": float}.
+
+    Note:
+        The same model is scored as 'predict_classes()' or 'predict_values()' score it; the AUC
+        ranks each sample's probability of the higher label, as 'show_model_metrics()' charts it.
+        An autoencoder's mse is over every value of every reconstructed sample, the loss
+        'train_model()' prints for the phase; its labels are required but not read.
+
+    Example:
+        >>> predict_metrics(model, "test")
+        {'accuracy': 0.9615, 'auc': 0.9912}
+    """
+    scorers = {
+        'classification': _classifier_scores,
+        'regression': _regressor_scores,
+        'autoencoder': _autoencoder_scores,
+    }
+    _check_model(model)
+    if not model.data._is_labeled(phase):
+        raise ValueError(
+            f"'model.data' phase {phase!r} has no labels to score the model against"
+        )
+    return scorers[model.kind](model, phase)
+
+
+# endregion
+# endregion
+# endregion