mcode-neural 0.5.0__py3-none-any.whl

mcode_neural-0.5.0.dist-info/METADATA

@@ -0,0 +1,767 @@
+Metadata-Version: 2.5
+Name: mcode-neural
+Version: 0.5.0
+Summary: Our AI and Neural Network tools. Clean, aligned, readable views of PyTorch tensors, single neuron models, and multi-layer networks, for Jupyter Notebooks and the console.
+Project-URL: Homepage, https://www.mcode.com/products-python-packages.html
+Author: Timothy McGuire
+License-Expression: MIT AND OFL-1.1
+License-File: LICENSE
+License-File: src/mcode_neural/fonts/MicroCODE-Mono/OFL.txt
+License-File: src/mcode_neural/fonts/RobotoMono/OFL.txt
+Keywords: AI,Debugging,Display,Jupyter,MicroCODE,Neural Network,Notebook,PyTorch,Tensor
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: ipython
+Requires-Dist: ipywidgets
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: torch
+Requires-Dist: varname
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: nbconvert; extra == 'dev'
+Requires-Dist: poethepoet; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff~=0.17.3; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MicroCODE's 'mcode-neural' package
+
+A public PyPI Package of our internal Neural Network tools for Jupyter Notebooks and the console.
+
+It includes our PyTorch Tensor display functions, our NumPy single neuron models, and our PyTorch multi-layer networks for regression and classification.
+
+It is a 'light weight' package built only on the standard Notebook stack: PyTorch, NumPy, pandas, Matplotlib, IPython, ipywidgets, and 'varname'.
+
+## Description
+
+This is our internal tensor display code. It replaces the use of "print(tensor)" with "show_tensor(tensor)"
+which shows **everything you need to know about a tensor in one aligned block**.
+
+- **show_tensor()** - prints a tensor's Name, Shape, Datatype, Device, and Values with right-aligned labels.
+
+## show_tensor() vs. print()
+
+Why did we write this package? We were unhappy with how much work it took to inspect a tensor while learning
+and debugging. A plain **print(tensor)** shows only the values, wrapped in 'tensor(...)' and extra brackets,
+and you must make separate calls to see its shape, dtype, and device.
+
+- **print()**...
+
+```
+tensor([[1, 2, 3],
+        [4, 5, 6],
+        [7, 8, 9]])
+```
+
+- **show_tensor()**...
+
+```
+    Name: tp_data
+   Shape: (3, 3)
+Datatype: int64
+  Device: cpu
+  Tensor: [1, 2, 3]
+          [4, 5, 6]
+          [7, 8, 9]
+```
+
+Features:
+
+1. The **Name** is taken automatically from the expression passed in, or can be given explicitly.
+2. The 'torch.' prefix is removed from Datatypes and 'torch.Size' from Shapes.
+3. The 'tensor(...)' wrapper and the outermost brackets are removed, rows stay aligned under the label.
+4. Scalars (0-D), Vectors (1-D), Matrices (2-D), and higher dimensions are all handled.
+5. Every tensor in a cell is shown, not just the last one Jupyter auto-displays.
+
+## Dependencies
+
+- **Production**
+
+1. Python 3.12+ - required for our f-string quoting style
+2. PyTorch - the tensors being displayed
+3. NumPy - the arrays used by the single neuron models
+4. varname - used to retrieve the caller's variable name
+5. pandas - the tables shown by the model views
+6. Matplotlib - the bar charts drawn by the model views
+7. IPython - displays the model views' tables and Markdown in a Notebook
+8. ipywidgets - the slider that browses the trace sample by sample
+
+- **Development**
+
+1. pytest - our preferred Python testing framework
+2. build - builds the distributable wheel and source archive
+3. twine - uploads the distributables to PyPI
+
+## Fonts
+
+Two monospace fonts ship inside the package, so nothing has to be installed on your machine:
+
+- **Roboto Mono** (v3.001, Regular and Bold) - every model view's table is drawn in it. The first table each time a
+  Notebook cell runs carries the font inside its own HTML, so the tables read the same on every machine.
+- **MicroCODE Mono** (v1.0.83) - MicroCODE's own monospace font, derived from ProFont, with complete Box Drawing and
+  Block Elements coverage.
+
+Both are registered with Matplotlib when 'mcode_neural' is imported, so your own charts can use either by name; the
+package's charts keep their Arial text.
+
+```python
+import matplotlib.pyplot as plt
+import mcode_neural
+
+plt.text(0.1, 0.5, "┌──┐ MicroCODE Mono", family="MicroCODE Mono")
+```
+
+## Light Mode and Dark Mode
+
+Every view draws in Dark Mode by default: near-black charts and dark gray tables, for an editor in a dark theme. For a
+light theme, call show_mode("light") once, near the top of the Notebook, before any view:
+
+```python
+from mcode_neural import show_mode
+
+show_mode("light")
+```
+
+- Light Mode draws white charts, light gray tables, and dark text. The data colors (class colors, the weights' signs,
+  the color maps) are the same in both modes.
+- Keep one mode per Notebook. A table's and a slider's styles apply to every output in the Notebook, so the last mode
+  set restyles every table and widget already shown. A chart keeps the mode it was drawn in.
+- An unknown mode raises a ValueError naming the two modes, and the mode stays as it was.
+- With '%autoreload 2', editing the package reloads it in Dark Mode; run the show_mode() cell again.
+
+## GPU (CUDA)
+
+- Nothing in the package changes for a GPU: the multi-layer networks train and predict on whatever device the network
+  is on. train_model() moves each batch to the network's device, and predict_classes() / predict_values() return NumPy
+  arrays from the CPU.
+- 'pip install torch' on Windows installs a CPU-only build. Replace it with the CUDA build that matches your NVIDIA
+  driver, from the [PyTorch install selector](https://pytorch.org/get-started/locally/); uninstall first, as pip treats
+  the CPU build of the same version as already installed...
+
+```
+pip uninstall torch
+pip install torch --index-url https://download.pytorch.org/whl/cu128     # e.g. CUDA 12.8
+```
+
+- Move a network to the GPU when you create it, and again after model_load(), which loads every model on the CPU so a
+  model saved on a GPU loads on any machine (a wrapped Model loads where the networks given to it are):
+
+```python
+device = model_device()       # CUDA when available, else the CPU; prints the GPU, its memory, and the cap
+model = ClassificationModel(in_features=4, hidden_size=(64, 32), out_features=2).to(device)
+model = model_load("wine_network.pt").to(device)
+```
+
+- model_device() caps this process's GPU memory at 75% of the GPU's (model_device(fraction=0.5) for half), leaving the
+  rest to the desktop. On Windows the NVIDIA driver otherwise lets a batch too big for the GPU spill into shared system
+  RAM, where it runs many times slower with no message. With the cap it fails at once, and train_model() names it:
+  "phase 'train' at batch_size=100 needs more than the 6.00 GiB cap; try a smaller batch_size".
+
+- train_probe() finds the batch size that fits before a long run: it trains two batches at each size, smallest first,
+  prints each peak, stops at the first that does not fit, and leaves the model and optimizer as they were.
+- train_model() records each run's device, cap, and peak GPU memory in its history, and prints the peak and what the
+  process still holds when it ends. However it ends, its gradients and PyTorch's cached blocks go back to the GPU. An
+  interrupted run (Interrupt Kernel, or an out-of-memory error) records nothing and puts back the weights the model had
+  when it started. The optimizer's state is yours: 'del optimizer', or build a new one for the next phase.
+- checkpoint= saves the model at each epoch whose val score is the best so far, so a kernel restart keeps it;
+  model_load() reads it, and its history shows the run "In process..." until the run ends:
+
+```python
+optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
+train_probe(model, optimizer, [32, 48, 64, 100])     # batch_size  64: 5.00 GiB allocated, 5.56 GiB reserved of the 6.00 GiB cap
+model = train_model(model, optimizer, None, num_epochs=10, batch_size=64, checkpoint="../Models/vgg11.pt")
+# Training complete in 4m 12s
+# Peak GPU memory: 5.00 GiB allocated, 5.56 GiB reserved of the 6.00 GiB cap
+# GPU memory held: 0.55 GiB
+```
+
+- Every prediction, metric, and view scores its phase batch by batch, in batches of the model's latest training's
+  batch_size (64 before any training), so a phase of any size fits the GPU memory one training batch did.
+  model_test() keeps the scoring's peak GPU memory beside its metrics in the history.
+- The single neuron models are NumPy, and always run on the CPU.
+- A small network on tabular data can train slower on a GPU, as every batch is copied to it; the GPU pays off for
+  larger networks, larger batches, and image data such as MNIST.
+
+## Usage
+
+```python
+import torch as tp
+from mcode_neural import show_tensor
+
+x_rand = tp.rand(3, 2)
+show_tensor(x_rand)                     # Name: x_rand
+show_tensor(x_rand, 'Random Tensor')    # Name: Random Tensor
+```
+
+- Every model is **self-describing**: it knows its kind (model.kind, "classification" or "regression"), the arguments
+  it was built with, its data (model.data, its datasets by phase with their feature names, classes, and scaling), and
+  its history (model.history: how it was created, given its data, trained, and tested; model.curves and
+  model.best_epoch read its latest training). So nearly every function takes only the model, and a phase of its data
+  by name: create it, load its data, train it, validate it, evaluate it, examine it, look inside it, and read how it
+  came to be:
+
+```python
+import torch
+from mcode_neural import (LogisticClassifierNeuronModel, NeuronOptimizer, data_frame_split, train_model,
+                      show_training_curves, model_test, show_model_metrics, show_misclassified,
+                      show_neuron_trace, show_model_history)
+
+wine_classes = {0: ("goldenrod", "white wine"), 1: ("red", "red wine")}
+
+model = LogisticClassifierNeuronModel(in_features=len(input_columns))         # create it
+model.data = data_frame_split(wine_df, input_columns, "color", torch.int64,   # load its data
+                              input_columns, wine_classes, seed=42)
+model = train_model(model, NeuronOptimizer(lr=0.01), None, 10, batch_size=1)  # train and validate it
+show_training_curves(model)
+model_test(model, "test")                                                     # evaluate it
+show_model_metrics(model, "test")                                             # examine it
+show_misclassified(model, "test")
+show_neuron_trace(model, "test", i=10)                                        # look inside it
+show_model_history(model)                                                     # how it came to be
+```
+
+```python
+import numpy as np
+from mcode_neural import RegressorNeuronModel
+
+x = np.random.randn(100, 1)
+y = 3.0 * x[:, 0] + 1.0
+
+model = RegressorNeuronModel(in_features=1)
+for x_i, y_i in zip(x, y):
+    model.forward(x_i)
+    model.gradient(x_i)
+    model.update(grad_loss=2 * (model.a - y_i), learning_rate=0.05)  # Squared Error loss
+```
+
+- The multi-layer networks are PyTorch modules sized by their data: **hidden_size** lists each hidden layer's width,
+  so (64, 32) is a two hidden layer network; **dropout** adds a Dropout after each hidden ReLU.
+
+```python
+import torch
+from mcode_neural import ClassificationModel, RegressionModel
+
+model = ClassificationModel(in_features=4, hidden_size=(64, 32), out_features=2, dropout=0.25)
+print(model.classifier)                         # Linear, ReLU, Dropout, ... Linear
+
+criterion = torch.nn.CrossEntropyLoss()         # the outputs are logits, one per class
+optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
+predicted = model(inputs).argmax(1)             # the class with the highest logit
+
+regressor = RegressionModel(in_features=4, hidden_size=(64, 64, 64), out_features=1)
+```
+
+- BinaryClassificationModel has sigmoid outputs, each one yes / no logit, trained on nn.BCEWithLogitsLoss:
+  **out_features=1** is one two-class label, **out_features=k** is k independent labels (multi-label):
+
+```python
+from mcode_neural import BinaryClassificationModel
+
+binary = BinaryClassificationModel(in_features=4, hidden_size=(64, 32), out_features=1)
+predicted = binary(inputs) > 0                  # yes where the logit is above 0, sigmoid 0.5
+```
+
+- AutoencoderModel encodes each sample to a **latent_size** code and decodes it back, its decoder the mirror of
+  **encoder_size**. **output_activation** fits the output to the inputs' range: "linear" (any value), "sigmoid"
+  (0 to 1), or "tanh" (-1 to 1), the entries of AUTOENCODER_OUTPUTS. train_model() trains it on its own inputs as
+  targets; its data's classes are optional, and only color its latent view:
+
+```python
+from mcode_neural import AutoencoderModel, show_latent_space, show_reconstructions
+
+model = AutoencoderModel(in_features=784, encoder_size=(128, 64), latent_size=2)
+model.data = data_dataset_split(mnist_train, mnist_test, 0.25, digit_classes, seed=0)
+model = train_model(model, optimizer, scheduler, num_epochs=5, batch_size=100)
+
+codes = model.encode(X)                         # (N, 2), each sample's latent code
+show_latent_space(model, "test")                # one dot per sample, by class or by value
+show_reconstructions(model, "test", n=6)        # each input beside its reconstruction
+```
+
+- show_3d_latent_space() draws the same dots in 3D: a latent size of 3 as it is on z1 / z2 / z3, a wider code on its
+  3 principal components; show_3d_slider() spins it, chosen by the model's kind:
+
+```python
+from mcode_neural import show_3d_latent_space, show_3d_slider
+
+model = AutoencoderModel(in_features=784, encoder_size=(128, 64), latent_size=32)
+show_3d_latent_space(model, "test")             # the 32-value codes on their 3 principal components
+show_3d_slider(model, "test")                   # the same chart, turned by the sliders
+```
+
+- Every network takes **convolution**, the convolution stages before its Linear layers, for images read in their 2D
+  shape: each stage is a dict of "channels", "kernel" (odd, so the image keeps its size), and "pool" (1 for no
+  pooling), and **in_shape** is one image's (channels, height, width). An autoencoder's decoder mirrors its stages
+  back to the image. train_model() and the predictors shape each sample to **in_shape**, so images and flattened rows
+  score the same:
+
+```python
+from mcode_neural import AutoencoderModel, ClassificationModel
+
+stages = ({"channels": 8, "kernel": 3, "pool": 2},)  # Conv2d, ReLU, MaxPool2d: (8, 14, 14)
+model = ClassificationModel(784, (64,), 10, in_shape=(1, 28, 28), convolution=stages)
+print(model.classifier)                         # Conv2d, ReLU, MaxPool2d, Flatten, Linear, ReLU, Linear
+autoencoder = AutoencoderModel(784, (), 32, in_shape=(1, 28, 28), convolution=stages)
+print(autoencoder.hidden_size)                 # ((8, 14, 14), 32, (8, 14, 14))
+```
+
+```python
+from mcode_neural import show_misclassified, show_model_trace, show_neuron_trace
+
+show_model_trace(model, "test")            # a neuron's weights, or a network's PyTorch modules
+show_neuron_trace(model, "test", i=10)
+show_misclassified(model, "test")              # a single neuron or a network
+```
+
+- `show_model_trace()` also shows an external network, any `torch.nn.Module`, with no `phase`: it has no
+  `model.data` to score, so its chart has no score line.
+
+```python
+from torchvision import models
+from torchvision.models import VGG16_Weights
+
+show_model_trace(models.vgg16(weights=VGG16_Weights.IMAGENET1K_V1))   # 'features', 'avgpool', 'classifier'
+```
+
+- Every model is **Networks of Layers of Neurons**: model.network lists its Networks, each one named network of the
+  model and what it reads (its source: the data, or an earlier network, as a decoder reads its encoder); each
+  Network's layer lists its Layers, each one weight module (Linear, Conv2d, or ConvTranspose2d) with the modules after
+  it, e.g. ReLU and Dropout; and each Layer's neuron lists its Neurons, one per output. A single NumPy neuron is one
+  Network of one Layer of one Neuron. All three are views of the trained weights, so they always read the model as it
+  is. An indexed name is singular, so model.layer[2].neuron[5] reads as one neuron. A model of one network reads
+  model.layer for model.network[0].layer, and its labels drop "network[0]."; an autoencoder's read in full, e.g.
+  network[1].layer[0]. Zoom in from the model to one neuron, or draw the model once and click into each view:
+
+```python
+from mcode_neural import show_layer_internals, show_layer_trace, show_model, show_model_internals, show_network_internals, show_neuron_internals
+
+show_model(model, "test")                                      # the network as a diagram; a click opens each view below
+show_model_internals(model, "test")                            # one row per Layer, a mean |w| bar each
+show_network_internals(autoencoder.network[1], "test")         # the decoder: its source, shapes, and Layers
+show_layer_internals(model.layer[0], "test")                   # one row per Neuron, a mean a bar each
+show_neuron_internals(model.layer[0].neuron[5], "test", n=10)  # its 10 largest weights, a sample slider
+show_layer_trace(model, "test", i=10)                          # sample 10 through every Layer, its a per Layer
+
+layer = model.layer[0]
+layer.kind, layer.activation, layer.in_shape, layer.out_shape  # ('linear', 'relu', (11,), (64,))
+z, a = layer.neuron[5].outputs(X)                              # its z and a for every sample of X
+decoder = autoencoder.network[1]
+decoder.name, decoder.source, decoder.in_shape                 # ('decoder', ('encoder',), (2,))
+```
+
+- A regression model's data has **classes=None**; a classifier's data names every label in its classes.
+
+- Pass **chart=False** or **tables=False** to show_neuron_trace() to show one part alone, e.g. its tables
+  above a Notebook slider and its chart below it.
+
+- show_neuron_slider() browses the trace sample by sample, its tables above a slider and its chart below; the "-" and
+  "+" at the ends of its track step 1 sample a click, and a sample number typed in the box after them moves it there:
+
+```python
+from mcode_neural import show_neuron_slider
+
+show_neuron_slider(model, "test")
+```
+
+- show_confusion_matrix() charts a classifier's counts by true and predicted class, a single neuron or a network,
+  each square's rate (TNR, FPR / FNR, TPR) in its upper right corner:
+
+```python
+from mcode_neural import show_confusion_matrix
+
+show_confusion_matrix(model, "test")
+```
+
+- show_2d_scores() charts a classifier's score z by class either side of the decision boundary z = 0;
+  show_3d_results() charts its samples in 3D around its decision plane, on its three largest |w| features:
+
+```python
+from mcode_neural import show_2d_scores, show_3d_results
+
+show_2d_scores(model, "test")
+show_3d_results(model, "test")
+```
+
+- show_3d_slider() spins the same 3D chart with Elevation, Azimuth, and Roll sliders below it, each track between a
+  "-" and a "+" button that turn it 1 degree a click, and an angle typed in the box after them turns it there; an
+  autoencoder's slider spins show_3d_latent_space() instead.
+  show_3d_results() takes the same three angles, in degrees, for a still view:
+
+```python
+from mcode_neural import show_3d_results, show_3d_slider
+
+show_3d_slider(model, "test")
+show_3d_results(model, "test", elev=0, azim=90)
+```
+
+- show_model_metrics() scores a two-class model itself, a single neuron or a network (two softmax outputs, or one
+  sigmoid output), and charts its ROC curve, the AUC under it, and the threshold 0.5 point, then its confusion matrix
+  at that point. For a one-target regression model it charts every sample's prediction against its actual value
+  around the dashed y = x line, with R² and RMSE in the header. Either way the model's weights and train() / eval()
+  mode are left as they were:
+
+```python
+from mcode_neural import show_model_metrics
+
+show_model_metrics(model, "test")
+show_model_metrics(regressor, "test")               # predicted vs actual, R², RMSE
+```
+
+- For a regression model the Model chart shows R², RMSE, and predicted vs actual, the trace shows the
+  sample's error, and show_largest_errors() lists the worst predictions:
+
+```python
+from mcode_neural import show_largest_errors
+
+show_largest_errors(model, "test", n=20)       # a single neuron or a network
+```
+
+- show_training_curves() charts how a model's training went, one chart per metric and one line per phase, with a
+  dashed line labeled "best" at the epoch whose weights the model kept. It reads model.curves
+  ({"train_loss": [...], "val_acc": [...], ...}) and model.best_epoch, which train_model() records;
+  a model trained by another loop sets both itself:
+
+```python
+from mcode_neural import show_training_curves
+
+show_training_curves(model)                 # loss and acc charts; a regressor's curves hold only loss
+```
+
+- data_subset_split() holds out a validation subset of any PyTorch dataset, optionally stratified by class:
+
+```python
+from mcode_neural import data_subset_split
+
+train, validate = data_subset_split(mnist_train, validate_split=1/6, seed=0, stratify=True)
+```
+
+- data_dataset_split() makes that split a model's data: the train and val subsets of a PyTorch training dataset, and
+  its test dataset as it is, in a "dataset" Data to set as model.data, with the classes that name every label; each
+  dataset keeps its own transform:
+
+```python
+from mcode_neural import data_dataset_split
+
+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)
+```
+
+- data_labels() reads every label of a dataset without loading its inputs: from where torchvision keeps them
+  (targets, labels, \_labels, y, or GTSRB's \_samples), through the dataset's target_transform, and for a Subset from
+  its parent's at its indices. Both splits read their labels with it; only a dataset that keeps no labels is read item
+  by item:
+
+```python
+from mcode_neural import data_labels
+
+labels = data_labels(gtsrb_train)               # 26,640 labels, not one image loaded
+print(labels.bincount())                        # the datapoints of each of its 43 classes
+```
+
+- data_frame_split() splits a pandas DataFrame 60 / 20 / 20 into train, val, and test datasets, standardizing the
+  columns you name from the train rows only; features keep the order you list them in, and labels take the dtype you
+  give. It returns a "frame" Data to set as model.data: the datasets by phase, and the contract that names and scales
+  them (the feature names, the classes, and each standardized column's mean and std). data_loaders() makes one
+  DataLoader per phase from any dict of datasets:
+
+```python
+from mcode_neural import data_frame_split, data_loaders
+
+model.data = data_frame_split(encoded_df, encoded_feature_columns, "Old", torch.int64,
+                              numerical_feature_columns, abalone_classes, seed=42)
+loaders = data_loaders(model.data.datasets, batch_size=10)
+```
+
+- data_frame_phase() adds new raw rows to the model's data as a named phase, scaled by the model's own contract, so
+  every view and predict function takes them by name; rows without the label column are a phase with no labels:
+
+```python
+from mcode_neural import data_frame_phase, predict_classes
+
+data_frame_phase(model, "new", new_wines)
+columns, probabilities = predict_classes(model, "new")
+```
+
+- Pass a list of label columns for a multi-label model: the labels are (N, k), one column per name, where a single
+  name gives (N,).
+
+- train_model() trains any Model on its own data, in batches of batch_size, on the model's own device: each epoch
+  trains on "train" and scores every other phase, printed from epoch 0, and the best "val" epoch's weights are kept
+  (a classifier's highest accuracy, a regressor's lowest loss). Each batch runs through the Model's own train_step(),
+  which makes its loss and steps its optimizer; a network's loss comes from its class (nn.CrossEntropyLoss for a
+  classifier, nn.BCEWithLogitsLoss for a binary classifier, whose 0 / 1 labels it casts to float, nn.MSELoss for a
+  regressor). A Model of several networks, e.g. a GAN, names its optimizer_keys and takes a dict of one optimizer per
+  key, and a dict of one scheduler per key or None. It returns the model, with the curves show_training_curves()
+  charts in model.curves and the kept epoch in model.best_epoch. Each run adds a "train" event to model.history: the
+  optimizer by its constructor's names (optimizer.lr, and the settings left at their defaults, kept apart), the
+  scheduler, num_epochs, batch_size, and the run's results; training again adds another, so every run is kept:
+
+```python
+from mcode_neural import train_model
+
+optimizer = torch.optim.Adam(model.parameters(), lr=learning_rate)
+scheduler = torch.optim.lr_scheduler.ExponentialLR(optimizer, gamma=0.95)      # or None
+model = train_model(model, optimizer, scheduler, num_epochs=50, batch_size=10)
+show_training_curves(model)
+```
+
+- A single neuron trains through the same train_model(), stepped by a NeuronOptimizer that holds its learning rate, on
+  the neuron's own loss: the squared error for a regressor, the binary cross-entropy for a sigmoid classifier, and the
+  binary cross-entropy of (a + 1) / 2 for a tanh classifier with -1 / +1 labels. batch_size=1 steps once per sample,
+  as the course's loops do; a larger batch steps once by the mean of its samples' updates. A NumPy neuron has no GPU,
+  so its run records no device or memory:
+
+```python
+from mcode_neural import NeuronOptimizer, train_model
+
+model = train_model(model, NeuronOptimizer(lr=0.01), None, num_epochs=10, batch_size=1)
+show_training_curves(model)
+```
+
+- predict_classes() and predict_values() predict for every sample of one phase, a single neuron or a network; a
+  network is scored in eval() mode without gradients on its own device, its train() / eval() mode left as it was. A
+  classifier returns its output columns (the k-th lowest label is column k) and class probabilities, a regressor its
+  values shaped like its targets, all as NumPy arrays. predict_metrics() returns a model's metrics on a labeled phase
+  as plain numbers:
+
+```python
+from mcode_neural import predict_classes, predict_metrics, predict_values
+
+columns, probabilities = predict_classes(model, "test")    # (N,) columns and (N, k) probabilities
+values = predict_values(regressor, "test")                 # (N,) for one target, (N, k) for k
+predict_metrics(model, "test")                             # {'accuracy': 0.9615, 'auc': 0.9912}
+predict_metrics(regressor, "test")                         # {'mae': ..., 'rmse': ..., 'r2': ...}
+predict_metrics(autoencoder, "test")                       # {'mse': ..., 'rmse': ...}
+```
+
+- model_test() returns the same metrics and keeps them in the model's latest training, so its history says how the
+  weights it kept scored; testing the same phase again replaces them:
+
+```python
+from mcode_neural import model_test
+
+model_test(model, "test")                                  # {'accuracy': 0.9615, 'auc': 0.9912}, kept
+```
+
+- show_model_comparison() shows several models' metrics side by side, one row per model, each scored on the named
+  phase of its own data; each row starts with the model's layers (a single neuron is 1) and hidden sizes:
+
+```python
+from mcode_neural import show_model_comparison
+
+show_model_comparison({"neuron": neuron, "2 layers": network}, "test")
+```
+
+- For autoencoders of images, pass **n** to also chart the phase's first n samples, each beside every model's
+  reconstruction, one column per model:
+
+```python
+show_model_comparison({"linear": model, "tanh": tanh_model}, "test", n=6)
+```
+
+- model_save() saves a model with what it knows about itself: its class, weights, data contract (and how its data was
+  split), and history (not its datasets). model_load() builds it again, ready to score new rows, and adds a "load"
+  event to its history; a file saved by a pre-release build that kept no history loads with a history built from
+  what it held:
+
+```python
+from mcode_neural import model_load, model_save
+
+model_save(model, "wine_neuron.pt")
+model = model_load("wine_neuron.pt")
+data_frame_phase(model, "new", new_wines)
+```
+
+- show_model_history() shows how a model came to be, oldest first, one block of rows per event: "create" (its
+  arguments and seed, a default marked "(default)", and the mcode-neural and torch versions), "data"
+  (how it was split, and the samples per phase),
+  each "train" (the trainer's settings, a default marked "(default)", and its best epoch, val score, seconds, and
+  tests), and "load". Each event's time reads as a local 12-hour clock, e.g. "2026-10-31 8:16:52 AM".
+  Pass **seed** to any model to build the same starting weights again:
+
+```python
+from mcode_neural import ClassificationModel, show_model_history
+
+model = ClassificationModel(11, (16, 8), 2, dropout=0.25, seed=7)   # the same weights for seed=7
+show_model_history(model)
+```
+
+- The **classes** keys are the labels in Y: {0: ..., 1: ...} for the sigmoid model, {-1: ..., 1: ...}
+  for the tanh model; the lower label is the class below the threshold.
+
+- Pass **n** to show_misclassified() to list only the n most confident misses, as in .head(n);
+  leave it out to list every miss.
+
+## Development
+
+### Installing
+
+- Use "pip install" to load the package...
+
+```
+pip install mcode-neural
+```
+
+- To use local modifications to the package (the Python equivalent of 'npm link')...
+- From the **mcode-neural** package directory, with your project's virtual environment active...
+
+```
+pip install -e .[dev]
+```
+
+...edits to the source are used immediately, restart your Jupyter kernel to pick them up.
+
+### Testing
+
+- From the **mcode-neural** package directory...
+
+```
+pytest
+```
+
+## Included Functions
+
+| Function                 | Description                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| data_classes()           | Returns a classifier's classes, a color and name per label, for any class count.    |
+| data_dataset_split()     | Splits a PyTorch training dataset, beside its test set, into a model's data.        |
+| data_frame_phase()       | Adds new raw rows to a model's data as a named phase, scaled by its contract.       |
+| data_frame_split()       | Splits a DataFrame into a model's train, val, and test data, standardized.          |
+| data_labels()            | Reads every label of a dataset, or a subset of one, without loading its inputs.     |
+| data_loaders()           | Makes one DataLoader per phase from a dict of datasets.                             |
+| data_subset_split()      | Splits a PyTorch dataset into train and validate subsets, optionally stratified.    |
+| model_device()           | Returns the device to train on, CUDA or the CPU, its GPU memory capped; prints it.  |
+| model_freeze()           | Freezes a network, or named parts of it, for transfer learning; prints what trains. |
+| model_load()             | Builds a saved model again; a wrapped Model takes its networks by name.             |
+| model_replace_output()   | Replaces a network's output layer, its last Linear, with one of new out_features.   |
+| model_save()             | Saves a model with its class, weights, data contract, and history.                  |
+| model_test()             | Scores a trained model on a phase, and keeps the metrics in its history.            |
+| model_unfreeze()         | Unfreezes a network, or named parts of it, to fine-tune; prints what trains.        |
+| predict_classes()        | Predicts a classifier's columns and class probabilities for every sample.           |
+| predict_metrics()        | Returns a model's metrics on a phase: accuracy, AUC; MAE, RMSE, R²; or MSE, RMSE.   |
+| predict_values()         | Predicts a regressor's value(s) for every sample, shaped like its targets.          |
+| show_2d_scores()         | Charts a single neuron classifier's score z by class, either side of z = 0.         |
+| show_3d_latent_space()   | Charts the same latent codes in 3D: a latent size of 3 as it is, or on 3 PCs.       |
+| show_3d_results()        | Charts a single neuron classifier's samples in 3D around its decision plane.        |
+| show_3d_slider()         | Spins a 3D chart, results or latent space by kind, with "-" / "+" stepped sliders.  |
+| show_confusion_matrix()  | Charts a classifier's counts and rates by true and predicted class.                 |
+| show_largest_errors()    | Lists the n samples a regressor predicts worst, largest error first.                |
+| show_latent_space()      | Charts an autoencoder's latent code of each sample, colored by its class or value.  |
+| show_layer_internals()   | Shows one Layer: one row per Neuron, and a bar of each neuron's mean activation.    |
+| show_layer_trace()       | Traces one sample through every Layer of a model: its z and range of a per Layer.   |
+| show_misclassified()     | Lists every sample a classifier gets wrong, most confident first.                   |
+| show_mode()              | Sets the mode every later view draws in: "dark", the default, or "light".           |
+| show_model()             | Draws a model as a network diagram; a click on any part opens its view below it.    |
+| show_model_comparison()  | Shows several models' metrics side by side, one row per model.                      |
+| show_model_history()     | Shows how a model came to be: each event's settings and results, oldest first.      |
+| show_model_internals()   | Shows a model as its Layers: one row and a mean \|w\| bar per Layer.                |
+| show_model_metrics()     | Charts a classifier's ROC curve and confusion matrix, or a regressor's fit.         |
+| show_model_trace()       | Shows a model's internals: a neuron's weights, or a network's PyTorch modules.      |
+| show_network_internals() | Shows one Network of a model: its source and shapes, one row and a bar per Layer.   |
+| show_neuron_internals()  | Shows one Neuron: its weights (bars or grids), its a by class, and a sample slider. |
+| show_neuron_slider()     | Browses a single neuron model's trace sample by sample with a slider.               |
+| show_neuron_trace()      | Traces one sample through a single neuron model, charting each term of its score z. |
+| show_reconstructions()   | Charts the first n samples beside an autoencoder's reconstruction of each.          |
+| show_samples()           | Shows a model's first n samples, of each class if named: images, or DataFrame rows. |
+| show_tensor()            | Prints a tensor's Name, Shape, Datatype, Device, and Values, aligned.               |
+| show_training_curves()   | Charts each training metric by epoch, one line per phase (train, val, test).        |
+| train_model()            | Trains any Model, scoring each phase per epoch; keeps its best val weights.         |
+| train_probe()            | Measures a network's peak GPU memory at each batch size; leaves it as it was.       |
+
+## Included Classes
+
+| Class                         | Description                                                                         |
+| ----------------------------- | ----------------------------------------------------------------------------------- |
+| Model                         | Self-describing model: its kind, data, history, and networks (model.network).       |
+| Data                          | A model's datasets by phase, feature names (data.feature), classes, scaling, split. |
+| Network                       | One network of a model: its name, what it reads (source), shapes, and its Layers.   |
+| Layer                         | A model's weight module and the modules after it; its neurons, inputs, z, and a.    |
+| Neuron                        | One output of a Layer: its weights (neuron.weight), bias, z, and a.                 |
+| NeuronModel                   | Abstract single neuron; subclasses set activation_name, a key of NEURON_KINDS.      |
+| RegressorNeuronModel          | Single neuron regressor, a linear activation, for any real target.                  |
+| LogisticClassifierNeuronModel | Single neuron logistic classifier, a sigmoid activation, for 0 / 1 labels.          |
+| BipolarClassifierNeuronModel  | Single neuron bipolar classifier, a tanh activation, for -1 / +1 labels.            |
+| NeuronOptimizer               | A single neuron's optimizer for train_model(): its learning rate, lr.               |
+| FeedforwardModel              | Abstract network: conv stages (optional), ReLU hidden layers, a Linear output.      |
+| ClassificationModel           | Multi-layer network for classification, one logit per class.                        |
+| BinaryClassificationModel     | Multi-layer network for binary or multi-label classification, one logit per label.  |
+| RegressionModel               | Multi-layer network for regression, one value per target.                           |
+| AutoencoderModel              | Autoencoder: a ReLU encoder (conv stages optional) to a latent code, mirrored back. |
+| ExternalClassificationModel   | A classifier built elsewhere, e.g. torchvision's VGG11, as a ClassificationModel.   |
+| ExternalRegressionModel       | A regressor built elsewhere, as a RegressionModel.                                  |
+| ExternalAutoencoderModel      | An encoder and decoder built elsewhere, as an AutoencoderModel.                     |
+
+| Table               | Description                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| MODEL_KINDS         | Each model kind's metrics and best-epoch rule: classification, regression, autoencoder.  |
+| NETWORK_KINDS       | How each network kind reads layers, weights, z, inputs, outputs, device: torch, numpy.   |
+| LAYER_KINDS         | Each layer kind's weight module, fields, and neuron axis: linear, conv, deconv.          |
+| NEURON_KINDS        | Each neuron kind's label, module, range, activation, slope, curve: linear ... softmax.   |
+| DATA_KINDS          | What each kind of data holds: "frame" names and scales its features, "dataset" does not. |
+| AUTOENCODER_OUTPUTS | The neuron kinds an autoencoder's output may take: linear, sigmoid, tanh.                |
+
+## Help
+
+Contact Timothy McGuire, support@mcode.com.
+
+## Terminology
+
+| Word or Acronym | Description/Definition                                                                       |
+| --------------- | -------------------------------------------------------------------------------------------- |
+| **PyPI**        | The Python Package Index, the Python equivalent of the npm registry.                         |
+| **pip**         | The Python package installer, the Python equivalent of 'npm install'.                        |
+| **PyTorch**     | An optimized tensor library for deep learning using GPUs and CPUs.                           |
+| **Tensor**      | A multi-dimensional array, like a NumPy 'ndarray', that can run on GPUs and track gradients. |
+| **CUDA**        | NVIDIA's GPU computing platform; a CUDA build of PyTorch runs tensors on an NVIDIA GPU.      |
+| **Jupyter**     | An interactive Notebook environment mixing code, output, and Markdown documentation.         |
+
+## Authors
+
+Contributor's names and contact info...
+
+- Timothy McGuire [@TimothyMcGuire](https://x.com/TimothyMcGuire) - Founder, President-CEO of MicroCODE, Inc. a software and controls engineering company in Detroit, Michigan USA.
+
+## Version History
+
+- v0.5.0
+    - The first release published to PyPI; earlier version numbers were pre-release builds, never published.
+    - 'show_tensor()': a PyTorch tensor printed as a readable table, in Dark Mode or Light Mode ('show_mode()'), in the bundled Roboto Mono and MicroCODE Mono fonts.
+    - Self-describing models: NumPy single neurons ('RegressorNeuronModel', 'LogisticClassifierNeuronModel', 'BipolarClassifierNeuronModel') and PyTorch networks ('FeedforwardModel', 'ClassificationModel', 'BinaryClassificationModel', 'RegressionModel', 'AutoencoderModel'), with optional convolution stages; 'ExternalClassificationModel', 'ExternalRegressionModel', and 'ExternalAutoencoderModel' wrap a network built elsewhere, e.g. torchvision's VGG11. Every model knows its kind, its data, and its history, and reads as Networks of Layers of Neurons.
+    - Data, training, and prediction: 'data_frame_split()', 'data_dataset_split()', 'data_loaders()', 'data_classes()', and 'data_labels()'; 'train_model()', 'train_probe()', and 'model_device()'; 'predict_classes()', 'predict_values()', 'predict_metrics()', and 'model_test()'; 'model_save()' and 'model_load()'; 'model_freeze()', 'model_unfreeze()', and 'model_replace_output()' for transfer learning.
+    - Views: 'show_model()', a clickable network diagram; the internals views from a model down to one neuron; traces, metrics, confusion matrices, training curves, latent spaces, reconstructions, samples, comparisons, and a model's history.
+
+## Future Development
+
+- v0.6.\*
+    - Any additional core code we develop for general PyTorch and Neural Network coding, debug, and support.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details
+
+The bundled fonts are licensed under the SIL Open Font License, Version 1.1 - see the 'OFL.txt' beside each font in
+'mcode_neural/fonts/'. Roboto Mono is © 2015 The Roboto Mono Project Authors; MicroCODE Mono is © 2025 MicroCODE, Inc.,
+with "MicroCODE Mono" as a Reserved Font Name, and its 'OFL.txt' carries the MIT notice of ProFont, from which it is
+derived.
+
+## MicroCODE Mantra
+
+MicroCODE, Inc. was founded in 1987 as a controls engineering and software development company.<br>
+We specialize in manufacturing and quality control applications that must run 24x7x365 for years at a time.
+
+Our slogan, distilled from over three decades of developing, testing, installing, and supporting 24x7x365
+manufacturing applications, is..
+
+**"Hail CAESAR"**℠ — _"Code like a Machine: Consistently and Explicitly, Simply and for Readability."_