Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (93 loc) · 6.01 KB

CLAUDE.md

File metadata and controls

139 lines (93 loc) · 6.01 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

tsai is a state-of-the-art deep learning library for time series and sequential data, built on top of PyTorch and fastai. It supports classification, regression, forecasting, and imputation tasks.

Claude Code Workflow (IMPORTANT)

The source of truth for tsai is nbs/*.ipynb. Files in tsai/ that carry an # AUTOGENERATED! DO NOT EDIT! header are produced from notebooks by nbdev-export — never edit those by hand; they'll be overwritten on the next export. A handful of files in tsai/ are hand-written sources with no AUTOGENERATED header (e.g. tsai/imports.py, tsai/__init__.py) — edit those directly.

Editing notebooks

  • Prefer the NotebookEdit tool (it requires Read first).
  • For large notebooks where Read exceeds the token limit, fall back to Python JSON manipulation: load with json.load, modify the target cell's source array, write back with json.dump. Always clear outputs and reset execution_count = None on edited code cells.
  • After editing notebooks, run nbdev-export to regenerate tsai/*.py, then nbdev-clean to strip metadata before committing.

Verifying changes

nbdev-test is how you actually run a notebook: it spins up a fresh kernel for each .ipynb, executes every cell top to bottom, and surfaces any failed assertion, test_eq, or raised exception as a cell-level error with traceback. Running it is required to confirm in-notebook tests pass.

Before declaring work complete:

  • macOS (Apple Silicon): nbdev-test --n_workers 0 --do_print — runs in-process; avoids MPS-related Metal compiler crashes that hit the parallel runner under load.
  • Linux / CI: nbdev-prepare — bundles export + test + clean.

For targeted spot checks during iteration:

  • One or a few notebooks: nbdev-test --file_re '^(004_|005_|009_)' --n_workers 0
  • Slow tests: add --flags slow
  • A single symbol's behavior: importing it in a fresh Python process is often faster than running the whole notebook.

Development Setup

Requires Python 3.10 or newer.

# Clone and install with dev dependencies
git clone https://github.com/timeseriesAI/tsai
pip install -e "tsai[dev]"

# Install nbdev git hooks (required for notebook development)
nbdev-install-hooks

Build and Test Commands

# Run all tests, export notebooks to Python, and clean notebooks (Linux / CI)
nbdev-prepare

# macOS (Apple Silicon) — run individually with an in-process test runner
# to avoid MPS-related crashes in the parallel runner
nbdev-clean
nbdev-export
nbdev-test --n_workers 0 --do_print

# Run tests only
nbdev-test

# Export notebooks to Python modules
nbdev-export

# Clean notebooks (remove outputs and metadata)
nbdev-clean

# Build documentation (requires quarto; install with `nbdev-install-quarto`)
nbdev-docs

Architecture

nbdev-Based Development

This project uses nbdev for literate programming. Most source code lives in Jupyter notebooks under nbs/ and is exported to Python modules in tsai/ via nbdev-export. Generated files in tsai/ carry an # AUTOGENERATED! DO NOT EDIT! header — edit the corresponding notebook instead. A small number of files in tsai/ are hand-written sources (no AUTOGENERATED header) and are edited directly.

  • Notebooks in nbs/ are the source of truth
  • Python files in tsai/ are auto-generated (marked with # AUTOGENERATED! DO NOT EDIT!)
  • Use #|export at the top of notebook cells to export code to modules
  • Notebook naming: NNN_module.submodule.ipynb maps to tsai/module/submodule.py

Key Directories

  • nbs/ - Source notebooks (edit these)
  • tsai/ - Auto-generated Python modules
  • tsai/models/ - Deep learning model implementations
  • tsai/data/ - Data loading, preprocessing, and transforms
  • tsai/callback/ - Training callbacks
  • tutorial_nbs/ - Tutorial notebooks (not part of the library)

Import Patterns

from tsai.all import *      # Import everything
from tsai.basics import *   # Import core functionality (smaller import)

Core Classes

  • TSClassifier, TSRegressor, TSForecaster (tsai/tslearner.py) - High-level learner classes that wrap fastai's Learner
  • TSTensor, TSDatasets, TSDataLoaders (tsai/data/core.py) - Data containers
  • TSStandardize, SlidingWindow (tsai/data/preprocessing.py, tsai/data/preparation.py) - Data transforms

Input Data Format

Time series data uses 3D arrays: [samples, variables, sequence_length]

Model Architecture Pattern

Models ending in Plus (e.g., InceptionTimePlus, TSTPlus) support flexible output heads for different tasks. Base models (e.g., InceptionTime, TST) are simpler implementations.

Code Style

This project follows the fastai code style, not PEP8. Key differences:

Test Flags

Tests can use these flags (configured in pyproject.toml under [tool.nbdev] tst_flags = 'local slow extras onnx'):

  • #|local - Skip in CI, run locally only
  • #|slow - Skip slow tests by default; opt in with nbdev-test --flags slow
  • #|extras - Requires extra dependencies (sktime, tsfresh, etc.)
  • #|onnx - ONNX-related tests

Configuration

Project configuration lives in pyproject.toml (PEP 621). Key sections:

  • [project] - name, version (dynamic from tsai.__version__), Python requirement (>=3.10), authors, description.
  • [project.dependencies] - Hard runtime dependencies.
  • [project.optional-dependencies]:
    • dev - Development tooling (nbdev, ipykernel).
    • extras - Optional runtime dependencies (sktime, tsfresh, PyWavelets, nbformat).
  • [tool.nbdev] - nbdev-specific settings (test flags, jupyter hooks, custom sidebar).

Note: settings.ini and setup.py were removed in tsai 1.0.0 — pyproject.toml is now the single source for both Python packaging and nbdev configuration.