Temporal Models Skill

Overview

temporal-models trains sequence encoders on ordered neuroimaging or clinical measurements. It supports variable sequence lengths and estimates normalization statistics from training subjects only.

Supported models

Model	Encoder	Typical use
lstm	long short-term memory	longitudinal visits
gru	gated recurrent unit	compact recurrent baseline
tcn	temporal convolutional network	local temporal patterns
transformer	masked temporal self-attention	longer dependencies

Both classification and regression are supported.

---

Installation

pip install numpy torch scikit-learn pandas

Verify:

python -c "import torch; print('CUDA:', torch.cuda.is_available())"

---

Workflows

1. Prepare an NPZ sequence bundle

X:          float array [subjects, time, features]
y:          array [subjects]
lengths:    integer array [subjects] (optional)
subject_id: string array [subjects] (optional)

Padded frames must occur after each valid sequence. If lengths is absent, every sequence is treated as fully valid.

import numpy as np

np.savez(
    "sequences.npz",
    X=X.astype("float32"),
    y=y,
    lengths=lengths,
    subject_id=subject_ids,
)

2. Classification with GRU

python skills/temporal-models/scripts/train_reference.py \
  --input sequences.npz \
  --model gru \
  --task classification \
  --hidden-dim 64 \
  --layers 2 \
  --epochs 100 \
  --batch-size 32 \
  --folds 5 \
  --device cuda \
  --output-dir run_models_output/gru

3. Regression with temporal Transformer

python skills/temporal-models/scripts/train_reference.py \
  --input sequences.npz \
  --model transformer \
  --task regression \
  --hidden-dim 128 \
  --layers 3 \
  --dropout 0.2 \
  --lr 0.001 \
  --weight-decay 0.0001 \
  --output-dir run_models_output/temporal_transformer

Use subject-level folds; never split frames or visits from one subject across training and test sets.

---

Input / Output Summary

Item	Format
Input	.npz with X, y, optional lengths, subject_id
Predictions	predictions.csv
Fold membership	fold_assignments.csv
Metrics	metrics.json
Fold checkpoints	checkpoint.pt
Provenance	config.json, run_manifest.json

Each fold checkpoint stores the model state plus fold-local feature mean and standard deviation.

---

Testing

pytest models/tests/test_extended_models.py -q
python skills/temporal-models/scripts/train_reference.py --help

---

Directory Reference

models/temporal_models/
├── net.py              LSTM, GRU, TCN, and Transformer encoders
└── train.py            cross-validated sequence trainer

skills/temporal-models/
├── SKILL.md
└── scripts/train_reference.py

---

Reference

• Sequence masking is driven by the optional lengths array.
• Scaling is fitted from valid training frames and padding is restored to zero.

---

Created At: 2026-07-26 HKT Last Updated At: 2026-07-29 HKT Author: chengwang96