Neural Data Science Learning

A reproducible, Jupyter Notebook-first neural data science curriculum. 36 notebooks covering neural signal processing, classical machine learning, dynamical systems, LFADS, topological data analysis, neural decoding, CEBRA, and representational comparison.

Quick Start

The project uses Python 3.11 with dependencies managed via conda.

conda env create -f environment.yml
conda activate neuron
python -m pip install -e .
neural-ds doctor NB-00 --profile learn
jupyter lab

environment-dev.yml updates the same neuron environment with development tools; it is not a second overlay environment.

In Jupyter, select the neuron kernel, and start from notebooks/NB-00_Setup_Foundations.ipynb.

You can also execute from the command line; source notebooks are not overwritten:

neural-ds run NB-00 --profile learn --device cpu
neural-ds audit --scope source

Executed notebooks, NPZ files, figures, checkpoints, and reports are written to outputs/.

Project Structure

notebooks/                  # 36 source notebooks
src/neural_data_science/    # paths, artifacts, pipeline & validation modules
third_party/                # acquisition instructions for ignored research checkouts
tests/                      # unit and smoke tests
docs/                       # setup, curriculum, pipeline, and troubleshooting guides
outputs/                    # generated artifacts, not tracked by Git
pipeline.toml               # notebook dependencies and artifact directories
environment.yml             # conda environment specification

Common Commands

conda env update -f environment.yml       # update dependencies
neural-ds doctor NB-00 --profile learn    # notebook-specific diagnostics
neural-ds audit --scope source            # source structure and catalog
neural-ds audit --scope artifacts         # provenance and freshness
neural-ds audit --scope execution         # passed/failed/stale/not-run records
pytest                                    # unit and smoke tests
neural-ds run NB-00 NB-01 --profile learn --device cpu

NB-04C uses the official LFADS core modules from a locally fetched, pinned checkout. Prepare it once with:

python scripts/fetch_lfads_torch.py

The upstream repository is kept under third_party/lfads-torch/, ignored by Git, and is not installed as its legacy Hydra/Lightning package.

For full documentation:

• Installation & First Run
• Learning Path
• Pipeline & Artifacts
• Troubleshooting
• Development & Validation