docs: add the missing time-series classification section to how-training-works

join-use-case/how-training-works.mdx

@@ -1,9 +1,9 @@
 ---
 title: "How training works"
 description: "What the tracebloc client does to your data and model in each use case, so you can reproduce a run locally and compare results."
 ---
 
 This page documents the training and inference pipeline that the tracebloc client runs for every supported use case. The goal is full transparency: you can read what happens step-by-step, write an equivalent script on your own machine against the same dataset, and compare metrics number-for-number against what the platform reports.
 
 If something here does not match what you observe in your run, please [contact us](mailto:support@tracebloc.io) so we can investigate together.
 
@@ -13,7 +13,7 @@
 
 <Steps>
  <Step title="Resolve the experiment">
  The platform reads your experiment configuration — dataset, hyperparameters, framework choice, training-or-inference mode — and selects the right framework backend (PyTorch, TensorFlow, scikit-learn, lifelines, or scikit-survival).
  </Step>
  <Step title="Load your model">
  Your uploaded model file is fetched and instantiated. For continued cycles and inference, the latest weights from the experiment are loaded into it.
@@ -22,7 +22,7 @@
  The platform loads your raw data, runs the use-case-specific preprocessing, and produces training and validation batches (or a single test set in inference mode).
  </Step>
  <Step title="Configure optimizer and loss">
  Your hyperparameters are normalized, your loss function is constructed, and your optimizer (and learning-rate scheduler, if any) is built — all from the values you set in the notebook.
  </Step>
  <Step title="Run the training loop">
  For each epoch, every training batch goes through forward, loss, backward, and optimizer step. Validation batches run a forward pass only. Per-batch numbers feed into the metrics layer.
@@ -34,7 +34,7 @@
 
 ### Experiment parameters (shared across all use cases)
 
 Every use case below pulls its run-time configuration from the same set of experiment parameters. **You set these values in your Jupyter notebook** when you configure and submit the experiment with the `tracebloc` Python package; the platform deserializes them on the edge before training begins. The same parameter names work the same way across image classification, object detection, segmentation, keypoint detection, text, tabular, time series, and survival use cases — only the subset that applies to a given task is read.
 
 The values that reach the platform are always whatever you set in the notebook. The SDK initializes every parameter to a default at construction time, so even an experiment where you change nothing arrives on the edge with concrete values for every field. When you call a setter (`optimizer("adam")`, `batch_size(64)`, …), the SDK overwrites that field; on `start()` the assembled payload is what the platform receives.
 
@@ -53,7 +53,7 @@
 | All augmentation flags | off | `<flag>(...)` |
 | Pre-trained weights | off | model upload setting |
 
 **Class weighting** is applied automatically by the platform for **image classification** and **tabular classification** only, when your loss function is cross-entropy, NLL, or binary BCE. The formula is described in those sections. Other use cases do not reweight the loss.
 
 To replicate a run locally, read the actual values your experiment was launched with from the experiment view (or your notebook), then match the per-use-case preprocessing and metrics described below — those parts are baked into the platform pipeline and are not configurable from the notebook.
 
@@ -67,18 +67,18 @@
 
 **Input**
 - Image files (JPEG / PNG) supplied through the dataset metadata as `data_id` (the image filename) and `label` (the class name).
 - Class names are mapped to integer indices in the order defined by the dataset's class list, so the same class always lines up with the same logit position across cycles and inference.
 
 **Preprocessing**
 - Images are resized to a square at the size you set in the notebook (default 256). Aspect ratio is **not** preserved — the resize is a direct stretch.
 - Pixel values are normalized using ImageNet mean and standard deviation. You can override the mean and standard deviation in the notebook if your model was pre-trained against different statistics.
 - The augmentation flags you set in the notebook (rotation, shifts, brightness, etc.) drive an image augmentation pipeline that runs on the training split only — validation always sees the unaugmented preprocessing so metrics stay deterministic across epochs. For reference, the SDK only allows the geometric and color augmentation flags to be set on PyTorch experiments — horizontal and vertical flip flags are TensorFlow-only at the SDK level.
 - Train/validation split is **stratified by class label** (so class proportions are preserved on both sides) and uses a deterministic seed. If your chosen split would leave one side empty on a small dataset, it is silently retried with the ratio clamped into a safe range.
 
 **Training step**
 1. Forward pass through the model produces a logit per class.
 2. The loss function you configured in the notebook is used. Cross-entropy is the common choice; if you pick a regression-style loss (such as MSE) the labels are converted to one-hot floats automatically so the shapes line up.
 3. **Class weighting** is applied automatically: for cross-entropy / NLL, each class gets a weight inversely proportional to its training-split frequency (normalized so the weights average to 1, so balanced classes effectively pass through unchanged); for binary BCE, the positive class gets a weight equal to `negative_count / positive_count`. Regression losses like MSE and L1 are not reweighted. This means a verifier who computes loss locally without these weights will see different numbers, especially on imbalanced datasets.
 4. Backward pass and optimizer step.
 5. Per-batch monitoring metric: accuracy — the fraction of images whose predicted class matches the ground-truth class.
 
@@ -87,11 +87,11 @@
 
 **Cycle metrics**
 - **Accuracy family**: accuracy, top-3 accuracy, top-5 accuracy. For datasets with fewer than 3 (or 5) classes, the corresponding top-k accuracy collapses to 1.0 — interpret it accordingly.
 - **Probability-based**: macro-averaged AUC-ROC, macro-averaged AUC-PR, log loss, Brier score (multiclass squared-error form, not the binary sklearn version), quadratic weighted kappa.
 - **Confusion matrix** is produced and surfaced in the run output.
 
 **Inference output**
 - Per image: the predicted class index and the full softmax probability vector. The class-index ordering is the dataset's class list — match this ordering when comparing locally.
 
 </Accordion>
 
@@ -101,34 +101,34 @@
 
 **Input**
 - Images plus per-image annotation files (Pascal VOC-style XML sidecars) listing each object's class name and bounding-box coordinates.
 - Class names are matched case-insensitively against the dataset's class list and mapped to integer indices in the order that list defines.
 
 **Choosing the model family**
 
 You select the model family in the notebook — either an R-CNN family model (Faster R-CNN, Mask R-CNN) or a YOLO family model. The platform branches its training and validation logic on this choice, so it has to be set correctly for your model. If left unset, the platform falls back to inspecting the model name and class for the word "yolo"; if neither matches, it defaults to R-CNN. Picking an unsupported value will fail the run early.
 
 **Preprocessing**
 - Images are resized to a square at the size you set in the notebook (default 416 for R-CNN; for YOLO the platform pins the image size at 448 regardless of what you configure). Aspect ratio is **not** preserved — the resize is a direct stretch, and bounding-box coordinates are rescaled to the same stretched frame. Letterbox padding is **not** used today.
 - Pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied in the object-detection pipeline by default — torchvision R-CNN models normalize internally as part of the model, and YOLO consumes the `[0, 1]` tensor directly.
 - Bounding boxes are validated before training: boxes that fall outside the image, are smaller than 2 pixels on a side, have an extreme aspect ratio, or cover a near-zero area are dropped (along with their labels) so the model never sees degenerate targets.
 - Class labels are **zero-indexed** — the first class in your dataset list is class 0. This differs from torchvision's R-CNN convention where class 0 is reserved for background, so a torchvision pre-trained classifier head cannot be reused as-is.
 - The augmentation flags you set in the notebook drive a joint image-and-bounding-box augmentation pipeline that runs on the training split only. Geometric transforms are applied to the image and to its bounding-box coordinates together so labels stay aligned. Validation always sees the unaugmented preprocessing.
 - Train/validation split is random (non-stratified) and deduplicated by image filename, so all the boxes for a given image stay on the same side of the split. Default split is 85/15.
 
 **Training step**
 
 - **R-CNN family**: the model is run in training mode and returns its internal loss dict (region-proposal, classification, box-regression, objectness). The platform sums these with equal weights and backpropagates. The loss function you set in the notebook is **ignored** for R-CNN — the model defines its own losses.
 - **YOLO family**: the model returns raw grid predictions. The loss is computed by an external loss module supplied alongside your model — the platform does not ship a built-in YOLO loss.
 
 A backward pass and optimizer step follow.
 
 **Per-batch monitoring metrics** (loss-curve only, not the cycle metric)
 - **R-CNN**: an "all boxes correct" rate — an image counts as correct only if every ground-truth box has a predicted box of the same class with IoU above 0.2. Strict criterion; expect low values early in training.
 - **YOLO**: the fraction of grid cells with objectness confidence above 0.5.
 
 **Validation step**
 - For R-CNN, the model is run in evaluation mode and produces a list of per-image predictions (boxes, scores, class labels) directly. No additional non-maximum suppression or score filtering is applied by the platform — whatever thresholds the model was constructed with apply.
 - For YOLO, every grid cell with positive objectness is decoded into a box in pixel coordinates. **Non-maximum suppression is not applied** by the platform on the YOLO path. If you want NMS for a fair local comparison, apply it in your local script with the same thresholds.
 
 **Cycle metrics**
 
@@ -156,29 +156,29 @@
 
 **Preprocessing**
 - The image and mask are resized to a square at the size you set in the notebook (default 256). Aspect ratio is **not** preserved — the resize is a direct stretch.
 - The image uses bilinear resampling; the mask uses **nearest-neighbor** so class indices stay integers. This is the most common reproduction mistake — bilinear on a mask invents non-existent classes.
 - Image pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied by default in the segmentation pipeline.
 - The augmentation flags you set in the notebook drive a joint image-and-mask augmentation pipeline that runs on the training split only. The same geometric transform is applied to the image and to its mask so per-pixel labels stay aligned. Validation always sees the unaugmented preprocessing.
 - Train/validation split is random (non-stratified, deterministic seed). The platform uses your `validation_split` value, with two safety nets: a one-row dataset reuses the same data for train and val instead of crashing, and if your chosen split produces a degenerate partition the run silently retries with 80/20.
 
 **Mask handling**
 
 Mask files are first read as grayscale, even if they are RGB on disk (so a multi-color RGB-encoded mask is effectively flattened before the class-index lookup). The grayscale pixel values are then mapped to class indices:
 
 - **Binary problems (2 classes):** the mask is thresholded at the midpoint of the 8-bit range — pixel values above 127 become class 1, the rest become class 0.
 - **Multi-class problems:** the first `num_classes` sorted unique pixel values in the mask file are treated as the canonical encodings and mapped to `0..N-1` in sorted order. Extra unique values that come from JPEG noise or anti-aliased edges are snapped to the nearest canonical neighbor, so every pixel ends up in `[0, num_classes)`.
 
 A user who encodes their masks differently locally (one-hot, RGB-color → class table, etc.) will not get the same loss numbers. Match this exact mapping when reproducing.
 
 **Training step**
 1. Forward pass through the model. The pipeline accepts either a raw logits tensor or a dict-shaped output (the torchvision FCN / DeepLab family returns one), so torchvision-style models work without adaptation.
 2. The loss function you configured in the notebook is used (cross-entropy is the common choice for segmentation). If no loss is configured, cross-entropy is used as a fallback.
 3. If the model has an auxiliary classifier head (FCN / DeepLab with `aux_loss=True`), the total loss is `main_loss + 0.4 × aux_loss`, matching the torchvision reference recipe. The 0.4 weight is configurable.
 4. Backward pass and optimizer step.
 5. Per-batch monitoring metric: pixel accuracy — the fraction of pixels whose predicted class matches the ground-truth class.
 
 **Validation step**
 - Same forward pass without backward. Predictions are taken as the argmax across the class dimension, producing a per-pixel class-index mask.
 
 **Cycle metrics**
 - **Pixel-level**: pixel accuracy, mean pixel accuracy, IoU, mean IoU, frequency-weighted IoU, Dice
@@ -188,7 +188,7 @@
 - **Per-class IoU**: one number per class that appeared in the cycle
 
 A few definitions worth pinning down for local replication:
 - **IoU** here is the global Jaccard index across all pixels; **mean IoU** is the per-class IoU averaged across classes. They genuinely diverge on imbalanced data — pick the right one for your comparison.
 - **Dice** is macro-averaged across classes, computed on integer-class inputs (not one-hot).
 - **Precision / recall / F1** are macro-averaged across classes.
 
@@ -199,11 +199,11 @@
 
 <Accordion title="Keypoint detection" icon="crosshairs">
 
 **Frameworks:** PyTorch — three model families are supported: R-CNN-style keypoint detectors (KeypointRCNN), heatmap regressors, and direct coordinate regressors.
 
 **Input**
 - Images and per-image keypoint annotations supplied through the dataset metadata. Each keypoint is an `[x, y, visibility]` triple; the visibility component is optional.
 - Keypoints with non-positive x or y are treated as **missing or out-of-frame** — they contribute an all-zero plane in the heatmap target instead of needing a separate mask channel.
 
 **Choosing the model family**
 
@@ -211,24 +211,24 @@
 
 **Preprocessing**
 - Two size knobs that do different things:
  - **Image size for the model**: the size you set in the notebook for what the model actually sees. Default 224. The image is resized to a square at this size, and keypoint coordinates are rescaled by the same factors so they stay aligned with the resized image. Aspect ratio is **not** preserved — the resize is a direct stretch.
  - **PCK reference size**: a separate size used only as the reference scale for the per-batch PCK threshold (the threshold is set to 20% of this size). Default 256. Changing it does not change what the model sees — only how strict the per-batch correctness threshold is.
 - Pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied by default in the keypoint pipeline.
 - For the heatmap family, ground-truth heatmaps are generated as 2D Gaussian peaks centered on each keypoint, at the resized image size, with a fixed standard deviation of 2 pixels. They are generated **after** augmentation so the targets stay aligned with the augmented image.
 - The augmentation flags you set in the notebook drive a joint image-and-keypoint augmentation pipeline that runs on the training split only. The same geometric transform is applied to the image and to its keypoint coordinates so the labels stay consistent.
 - Train/validation split is random (non-stratified) and uses a deterministic seed. Default 85/15. If the split fails on a tiny dataset, the same data is reused for both train and val instead of crashing.
 
 **Training step**
 
 - **R-CNN family**: the model is run in training mode and returns its internal loss dict (region-proposal, classification, box-regression, keypoint losses). The platform sums these with equal weights and backpropagates. The loss function you set in the notebook is **ignored** for R-CNN — the model defines its own losses. A second forward pass in evaluation mode produces the per-image predictions used by the metrics layer.
 - **Heatmap family**: the model returns a heatmap tensor with one channel per keypoint. The loss function you configured in the notebook is applied between predicted and ground-truth heatmaps (mean squared error is the common choice). Per-batch keypoints are recovered by taking the argmax of each predicted heatmap channel.
 - **Direct regression**: the model returns keypoint coordinates directly. The loss function you configured in the notebook is applied between predicted and ground-truth coordinates.
 
 A backward pass and optimizer step follow.
 
 **Per-batch monitoring metric**
 
 Percentage of Correct Keypoints (PCK): the fraction of predicted keypoints whose Euclidean distance to the ground truth is below `0.2 × PCK reference size` (in pixels of the resized image).
 
 **Validation step**
 
@@ -237,16 +237,16 @@
 **Cycle metrics**
 
 - **Detection-style**: precision, recall, F1 — computed from a per-keypoint TP/FP/FN match against a configurable distance threshold.
 - **Position error**: Mean Per-Joint Position Error (MPJPE), the mean Euclidean distance between predicted and ground-truth keypoints in pixels of the resized image. Mean Absolute Error (MAE) is also reported.
 - **COCO-style**: Object Keypoint Similarity (OKS). Per-image scale is derived from the bounding box of the ground-truth keypoints, and per-keypoint sigma defaults to a uniform 0.05.
 - **PCK at multiple thresholds**: `pck@0.05`, `pck@0.1`, `pck@0.2`, `pck@0.3`, `pck@0.5`.
 - **Visibility accuracy**: reported only when your dataset carries a visibility component on each keypoint.
 
 **Inference output**
 
 - **R-CNN**: per-image predicted bounding boxes, confidence scores, class labels, and keypoints.
 - **Heatmap**: per-image heatmap stack; the predicted keypoint per channel is the argmax of that channel.
 - **Direct regression**: per-image `(K, 2)` keypoint coordinates.
 
 </Accordion>
 
@@ -259,15 +259,15 @@
 - The platform looks up `<dataset_path>/<filename>.txt` for each row, so your filenames must match exactly.
 
 **Preprocessing**
 - Each text is tokenized with your configured tokenizer. If you didn't specify one, the platform falls back to your configured model ID, and finally to a default tokenizer.
 - Tokens are padded and truncated to your configured **maximum sequence length** (default 512). Padding happens at tokenization time, so all batches see fixed-shape inputs.
 - **Label-to-index mapping** is fixed in the first training cycle and persisted alongside your weights. Subsequent cycles and inference reuse the same mapping, so the same class always maps to the same logit position. When reproducing locally, use the saved mapping rather than your own ordering.
 - Train/validation split is **stratified by label** with a deterministic seed (default 80/20). If stratification fails because a class has too few examples, the run silently falls back to a non-stratified random split with the same seed.
 
 **Training step**
 
 - **HuggingFace-style models**: the model is called with `input_ids`, `attention_mask`, and `labels`, and returns its own loss. Your notebook's loss function is ignored on this path — the model defines it.
 - **Plain PyTorch models**: the model is called with `input_ids` only and returns logits. The platform applies the loss function you configured in the notebook to compute the training loss. Input dtype is automatically cast to match the model's parameter dtype (float, half, or long).
 
 A backward pass and optimizer step follow. Gradient clipping is applied during the backward pass.
 
@@ -275,7 +275,7 @@
 
 **Validation step**
 
 - Same forward pass without backward. Logits are retained on CPU so the cycle metrics layer can compute probability-based metrics from them.
 
 **Optional model adaptations**
 
@@ -286,23 +286,23 @@
 - **Classification basics** (per-class, macro-averaged): precision, recall, F1.
 - **F1 variants**: F1 macro, F1 micro, F1 weighted.
 - **Agreement metrics**: Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa.
 - **Other classification**: Hamming loss, Jaccard score (macro), F-beta at β = 0.5 and β = 2.0 (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged), balanced accuracy.
 - **Probability-based**: AUC-ROC (binary on the positive class; multiclass one-vs-rest macro-averaged), AUC-PR (average precision; multiclass macro-averaged over one-hot encodings), Gini coefficient and normalized Gini, log loss, Brier score (multiclass squared-error form).
 - **Top-k accuracy** for problems with more than two classes: top-3 and top-5, reported only when *k* is strictly less than the number of classes.
 - **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
 
 Each metric is computed independently; if one fails (for example, AUC-ROC on a single-class validation slice), it falls back to zero rather than failing the entire cycle.
 
 **Class weighting** is **not** applied automatically for text classification. If your dataset is imbalanced, configure class weights in your loss function from the notebook.
 
 **Inference output**
 - Per text: the predicted class index plus the softmax probability vector. The class-index ordering follows your dataset's class list — match that ordering when comparing locally.
 
 </Accordion>
 
 <Accordion title="Tabular classification" icon="table">
 
 **Frameworks:** PyTorch, TensorFlow, and any scikit-learn-compatible estimator (including XGBoost and LightGBM).
 
 **Input**
 - A tabular file with feature columns plus a label column. The label column name is configurable; categorical feature values can be strings.
@@ -311,13 +311,13 @@
 
 The preprocessing pipeline runs in this order, and the full set of fitted statistics (which columns to use, imputation values, category mappings, label-to-index map, scaling means and standard deviations) is **frozen in the first training cycle and reused** in subsequent cycles and at inference. When reproducing a run locally, pull these statistics from the experiment artifacts rather than refitting on your own data slice.
 
 1. **Column selection.** You can configure which columns the model sees from the notebook — either an include list, an exclude list, or derived feature definitions. If you don't configure anything, all columns from the dataset's schema are used.
 2. **Missing value imputation.** Numeric columns are filled with the **median** of the training split. Categorical columns are filled with the literal string `"Unknown"`. The label column is not imputed.
 3. **Binary encoding.** Columns with exactly two distinct values that look like booleans (`Y`/`N`, `YES`/`NO`, `TRUE`/`FALSE`, `1`/`0`, plus literal Python booleans) are auto-encoded to `0`/`1` integers. The truthy and falsy strings are configurable.
 4. **Categorical encoding.** Two strategies, configurable from the notebook:
  - **Label encoding** (default): each distinct string in a categorical column maps to a small integer based on the order it first appears in the training split. Categories not seen during training map to `-1` at inference.
  - **One-hot encoding**: each distinct string becomes its own `0`/`1` column.
 5. **Label-to-index mapping.** Class labels are mapped to integer indices in the order defined by your dataset's class list, so a class always lines up with the same logit position. By default, encountering a label that isn't in the class list fails the run; this strict check is configurable.
 6. **Numeric feature scaling.** Numeric feature columns are z-scored (mean 0, standard deviation 1) using training-split statistics; the label column is excluded. On by default and can be turned off.
 
 **Train/validation split**
@@ -326,34 +326,34 @@
 
 **Training step**
 
 - **PyTorch and TensorFlow**: a forward pass produces a logit per class. The loss function you configured in the notebook is applied; cross-entropy is the typical choice. A backward pass and optimizer step follow.
 - **scikit-learn**: training is a single `fit(X, y)` call per batch using the estimator's built-in objective. There is no separate forward / backward pass and no notebook-configured loss on this path.
 
 **Class weighting** is applied automatically across all three frameworks. For cross-entropy and similar log-likelihood losses, each class is weighted in inverse proportion to its training-split frequency, normalized so the weights average to 1 — so balanced datasets effectively pass through unchanged, and imbalanced ones get the rarer classes upweighted.
 
 **Per-batch monitoring metric**: accuracy — the fraction of rows whose predicted class matches the ground-truth class.
 
 **Validation step**
 
 - Same forward pass without backward. Predictions and raw logits are retained so the cycle metrics layer can compute probability-based metrics from them.
 
 **Cycle metrics**
 
 - **Classification basics** (per-class, macro-averaged): precision, recall, F1.
 - **Other classification metrics**: balanced accuracy, F-beta at β = 0.5 and β = 2.0 (macro), Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa, Hamming loss, Jaccard score (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged).
 - **Probability-based** (when raw logits are available): AUC-ROC (binary on the positive class; multiclass one-vs-rest macro), AUC-PR (average precision; multiclass macro over one-hot), Gini coefficient and normalized Gini, Brier score (multiclass squared-error form).
 - **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
 
 Each metric is computed independently; if one fails, it falls back to zero rather than crashing the cycle.
 
 **Inference output**
 - Per row: the predicted class index plus the predicted probability vector (softmax for multiclass, sigmoid for binary). The class-index ordering follows your dataset's class list — match that ordering when comparing locally.
 
 </Accordion>
 
 <Accordion title="Tabular regression" icon="chart-line">
 
 **Frameworks:** PyTorch, TensorFlow, and any scikit-learn-compatible regressor (including XGBoost and LightGBM).
 
 **Input**
 - A tabular file with feature columns plus a continuous target column. The target column name is configurable.
@@ -364,7 +364,7 @@
 The feature pipeline is the same as tabular classification — column selection (or full schema if you don't configure one), median / `"Unknown"` imputation, binary encoding, categorical encoding (label or one-hot), and z-scoring of numeric feature columns. There are two regression-specific differences:
 
 - **Label-to-index mapping is skipped.** The target stays numeric.
 - **Target scaling.** By default, the target column is also z-scored using training-split statistics (mean and standard deviation). The platform stores the scaling parameters alongside your weights and **inverse-transforms** predictions and labels back to the original target scale before computing cycle metrics — so the reported error numbers are in your data's original units, not in the z-scored space the loss is computed in. Target scaling can be turned off from the notebook; if you turn it off but leave feature scaling on, and your target has a much wider range than your scaled features, you'll see a warning in the run log because the loss will dominate strangely.
 
 The fitted preprocessing state (column choices, imputation values, category mappings, feature scaling stats, target scaling stats) is **frozen in the first training cycle and reused** in subsequent cycles and at inference.
 
@@ -374,8 +374,8 @@
 
 **Training step**
 
 - **PyTorch and TensorFlow**: a forward pass produces a continuous prediction per row (or per timestep, for sequence-shaped outputs — the platform takes the last timestep). The loss function you configured in the notebook is applied; MSE is the typical default, with MAE, smooth L1, and Huber as common alternatives. A backward pass and optimizer step follow. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — so well-behaved training runs see no clipping and unstable runs are kept from blowing up.
 - **scikit-learn**: training is a single `fit(X, y)` call using the estimator's built-in objective. The platform fits the estimator **once** in the first training batch of the first cycle; subsequent cycles only run prediction. If you want a sklearn regressor that actually updates across federated cycles, choose one that supports incremental / warm-start fitting.
 
 **Per-batch monitoring metric**: R² (coefficient of determination), accumulated from the running residual sum of squares and target variance.
 
@@ -400,7 +400,7 @@
 
 </Accordion>
 
-<Accordion title="Timeseries forecasting" icon="wave-square">
+<Accordion title="Time-series forecasting" icon="wave-square">
 
 **Frameworks:** PyTorch
 
@@ -410,7 +410,7 @@
 **Preprocessing**
 
 - **Feature and target scaling.** Both the feature columns and the target column are scaled using statistics fit on the training window only, then re-applied to the validation window and to inference data. The choice of scaler is configurable from the notebook (Min-Max scaling or standard z-scoring); Min-Max is the default. The fitted scaler instances are persisted alongside your weights and reused in subsequent cycles and at inference, so a federated run keeps a consistent scale across cycles.
 - **Sliding-window construction.** From the chronologically ordered, scaled rows the platform builds sliding-window samples: each input is a sequence of length **sequence length** (the lookback window you set in the notebook, default 60), and each target covers the next **forecast horizon** steps (default 1). With a single-step horizon the target is scalar; with a longer horizon it's a vector of that length.
 - **Auto-adjusted sequence length.** If your training or validation window is too short to fit even one full lookback-plus-horizon sample, the platform shortens the sequence length to the largest feasible value rather than crashing, and logs a warning. Forecast horizon is never silently shrunk — that's part of your experiment contract.
 
 **Train/validation split**
@@ -436,8 +436,8 @@
 - **Standard error metrics**: mean absolute error, mean squared error, root mean squared error, max absolute error.
 - **Goodness of fit**: R² (returns NaN on degenerate slices, e.g. constant targets).
 - **Percentage errors**: mean absolute percentage error (skips rows whose true value is near zero), median absolute percentage error (robust to outliers), symmetric MAPE.
 - **Direction accuracy**: the percentage of consecutive timestep pairs where the predicted change has the same sign as the actual change — a "did the model get the trend right" metric.
 - **Theil's U**: a normalized error statistic comparing predicted vs. actual change between consecutive steps. Lower is better.
 
 Each metric is wrapped in error handling — degenerate inputs return NaN rather than failing the cycle.
 
@@ -446,6 +446,62 @@
 
 </Accordion>
 
+<Accordion title="Time-series classification" icon="heart-pulse">
+
+**Frameworks:** PyTorch
+
+**Input**
+- A table where each row is one timestep of a sequence: a `sequence_id` column (which sequence the row belongs to), a `timestamp` column (temporal order within the sequence — a SQL timestamp or a numeric step index), one or more feature columns, and a `label` column.
+- The class is a property of the **whole sequence**, not of a single row: `label` must be constant across all rows of a `sequence_id`. This is validated before training — a sequence carrying two different labels fails the run instead of training on corrupted targets.
+- The sample unit everywhere in this use case is **one sequence**: the train/validation split, the batches, the class counts, the metrics, and the predictions all count sequences, never rows.
+- Class labels are mapped to integer indices in the order defined by the dataset's class list, so the same class always lines up with the same logit position across cycles and inference. A label outside the class list fails the run.
+
+**Preprocessing**
+
+The fitted preprocessing state (imputation fallbacks, category mappings, label map, scaler statistics) is **frozen in the first training cycle and reused** in subsequent cycles and at inference, persisted alongside your weights. When reproducing a run locally, pull these statistics from the experiment artifacts rather than refitting on your own data slice.
+
+1. **Per-sequence missing-value imputation.** Each feature column is forward-filled *within its own sequence* in timestamp order — a gap takes the most recent earlier observation from the same sequence, never from another sequence and never from the future. A **leading gap** (a missing value with no earlier observation in its sequence) falls back to a per-column statistic fitted on the training split: the median for numeric columns (if you configured a different numeric imputation strategy in the notebook, its statistic is used instead; strategies that don't reduce to a per-column statistic fall back to the median here), and the most frequent observed value for categorical columns. `sequence_id`, `timestamp`, and `label` are never imputed. Imputation is on by default and can be turned off from the notebook, in which case raw missing values pass through to the model unchanged.
+2. **`sequence_id` and `timestamp` are set aside** before the feature pipeline runs and re-attached unchanged after it — they are never encoded or scaled, so timestamps don't get z-scored and sequence ids never end up in the feature matrix.
+3. **Binary and categorical encoding.** Same behavior as tabular classification: the feature set defaults to every column in the dataset's schema, two-valued boolean-like columns are auto-encoded to `0`/`1`, and categorical string columns are label-encoded (default) or one-hot encoded — the encoding strategy is configurable from the notebook.
+4. **Numeric feature scaling.** Numeric feature columns are scaled using training-split statistics with the scaler configured in the notebook — the same `scaler` parameter the forecasting use case uses, Min-Max unless you change it; z-scoring and other scikit-learn scalers are selectable. The label column is excluded. Scaling is on by default and can be turned off from the notebook.
+5. **Sequence assembly — scale first, then pad.** After scaling, rows are grouped by `sequence_id` and sorted by `timestamp`, and every sequence becomes exactly one fixed-length sample of **sequence length** timesteps (the notebook parameter shared with the forecasting use case; when neither your model template nor the notebook sets it, the platform default of **25** applies, though templates commonly declare their own — read the value your experiment ran with from the experiment view). Shorter sequences are **zero post-padded** (real timesteps first, zero rows after); longer sequences are **tail-keep truncated** (the most recent timesteps survive). Padding is applied *after* scaling, so padding zeros never pass through the scaler and a model can recover the padding mask by treating all-zero timestep rows as padding. Unlike forecasting, the sequence length is never auto-shrunk on short data — it is part of your experiment contract and identical across secure environments, which federated weight averaging requires.
+
+The model therefore sees batches of shape `(batch, sequence length, features)` as float32 with one int64 class label per sequence, and is expected to return one logit per class for each sequence.
+
+**Train/validation split**
+
+Split **by sequence**, stratified on the per-sequence class label, with a deterministic seed. All rows of a given sequence land on the same side of the split, so within-sequence signal can never leak into validation. Default 85/15. If a class has too few sequences to stratify, the run silently falls back to a random (still sequence-level) split; if the configured split would leave one side empty, it is retried with the ratio clamped into a safe range.
+
+**Training step**
+
+1. Training batches are drawn with a **weighted random sampler**: each sequence is weighted inversely to its class frequency and drawn with replacement, so minority-class sequences are oversampled toward class-balanced batches. This is the platform's class-imbalance mechanism for this use case — the **loss is not reweighted** (unlike image and tabular classification), and no synthetic samples are generated. A local run with a plain shuffled loader will see a different batch composition, and different loss curves, on imbalanced data.
+2. The forward pass produces a logit per class for each sequence. Models that emit per-timestep outputs of shape `(batch, length, classes)` are collapsed to the last timestep; 1-D outputs are lifted to a single-logit column.
+3. The loss function you configured in the notebook is applied; cross-entropy is the typical choice. BCE-style losses get one-hot (or reshaped single-column) float targets, and regression-style losses (MSE, L1, smooth L1) get float or one-hot targets so the shapes line up.
+4. Backward pass and optimizer step. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — well-behaved runs see no clipping. A non-finite loss skips the weight update for that batch, and a mini-batch reduced to a single sequence is skipped entirely (it would crash batch-normalization layers in training mode).
+
+**Per-batch monitoring metric**: accuracy — the fraction of sequences whose predicted class matches the ground-truth class.
+
+**Validation step**
+
+- Same forward pass without backward, over an unshuffled loader that sees every validation sequence exactly once — the weighted sampler applies to training only. Raw logits are retained so the cycle metrics layer can compute the probability-based metrics.
+- Predictions are the argmax over the class logits; a binary model that emits a single logit is thresholded at sigmoid > 0.5.
+
+**Cycle metrics**
+
+The metric suite is identical to tabular classification — per-sequence labels and logits have the same shape as per-row tabular ones — with every number computed over sequences:
+
+- **Classification basics** (per-class, macro-averaged): precision, recall, F1.
+- **Other classification metrics**: balanced accuracy, F-beta at β = 0.5 and β = 2.0 (macro), Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa, Hamming loss, Jaccard score (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged).
+- **Probability-based** (computed from the retained logits): AUC-ROC (binary on the positive class; multiclass one-vs-rest macro), AUC-PR (average precision; multiclass macro over one-hot), Gini coefficient and normalized Gini, Brier score (multiclass squared-error form).
+- **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
+
+Each metric is computed independently; if one fails, it falls back to zero rather than crashing the cycle.
+
+**Inference output**
+- Per sequence: a predicted class index (argmax over the class logits; sigmoid > 0.5 for a single-logit binary model). The preprocessing artifact saved during training is replayed as-is — nothing is refit on the test slice — and the full cycle-metric suite above, including the confusion matrix, is reported over the test set.
+
+</Accordion>
+
 <Accordion title="Time-to-event prediction" icon="clock">
 
 **Frameworks:** PyTorch (a neural risk model trained with the Cox partial-likelihood loss), plus lifelines and scikit-survival (classical survival estimators that fit in a single pass and skip the neural training loop).
@@ -465,7 +521,7 @@
 
 **Training step**
 
 - **PyTorch**: the model takes the feature matrix and produces a single risk score per row (higher = worse prognosis). The loss is **Cox partial log-likelihood** — a survival-specific loss that ranks each observed event against everyone who was still at risk at that event time. The loss is hardcoded for this use case; the loss function you configured in the notebook is ignored on this path because Cox is the only canonical choice. A backward pass and optimizer step follow. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — Cox loss can spike on small batches when one event dominates the risk set, but well-behaved batches see no clipping.
 - **Lifelines / scikit-survival**: a single `fit` call on the full training slice, using the estimator's own optimization. There is no separate forward / backward pass.
 
 **Validation step**
@@ -487,15 +543,15 @@
 ## Reproducing a run locally
 
 <Warning>
 **Expect small variation, even with everything matched.** Two runs of the same script on the same data on the same machine can produce slightly different metric values — that's a property of modern deep-learning stacks, not a tracebloc-specific quirk. Reproducing a tracebloc run on your own machine compounds the same effects, so plan to compare numbers within a tolerance band (typically the second or third decimal place for accuracy-style metrics, a few percent for percentage errors), not exactly.
 
 Common reasons numbers move:
 
 - **Hardware differences.** GPU vs CPU, different GPU models, and different CUDA / cuDNN versions execute the same operations through different kernels. Sums of floating-point numbers are not associative, so reductions on different hardware can produce slightly different last-decimal-place values.
 - **GPU non-determinism.** Several common operations (some convolution backward passes, some scatter/gather kernels, atomic accumulation) are not deterministic by default — running the same forward/backward twice on the same GPU can produce different gradients.
 - **Library versions.** Different versions of PyTorch, TensorFlow, scikit-learn, and torchmetrics can change defaults, fix bugs, or alter numerical paths in ways that move the final numbers a little.
 - **Data-loader worker timing.** When the data loader uses multiple worker processes, the order batches actually arrive in can depend on process scheduling — different orderings produce slightly different gradient sequences and slightly different end-of-epoch state, even with the same shuffle seed.
 - **Federated averaging.** A tracebloc run trains across multiple federated cycles in which model weights are averaged across edges between cycles. A single-machine local run cannot reproduce that averaging step exactly — for multi-cycle and multi-edge experiments, the platform's cycle-end weights and your local cycle-end weights will diverge after the first averaging round.
 - **Stateful layers.** Batch normalization's running statistics, dropout masks, and any other stochastic layer state depend on batch order and initialization, both of which are sensitive to the points above.
 - **Mixed precision.** If your local run uses different mixed-precision settings than the platform did, you'll see small differences from rounding alone.
 
@@ -506,7 +562,7 @@
 
 <Steps>
  <Step title="Take the same data slice">
- Use the same dataset and the same train/validation split ratio you configured. Match the split strategy for your use case — stratified by label for image and tabular classification, deduplicated by image for object detection, temporal (no shuffle) for timeseries, and so on.
+ Use the same dataset and the same train/validation split ratio you configured. Match the split strategy for your use case — stratified by label for image and tabular classification, deduplicated by image for object detection, temporal (no shuffle) for time-series forecasting, sequence-level and stratified by sequence label for time-series classification, and so on.
  </Step>
  <Step title="Apply the same preprocessing">
  Match the preprocessing described in the section for your use case — especially feature scaling, target scaling (for regression and time series), and categorical encoding, all of which materially shift loss values. For use cases where the preprocessing state is frozen in the first cycle (tabular, time series, time-to-event), pull the saved statistics from your experiment artifacts rather than refitting on your slice.