Spatial neuroscience tutorials¶

These nine notebooks work through questions about occupancy, spatial firing, maze behavior, position decoding, and responses to cues. They are written for spatial neuroscientists who work with spike times and tracking data and know basic Python and NumPy.

Choose the question that matches your analysis. Each notebook provides its own recording, explains the analysis choices, and shows how to read the resulting figures. A final section describes how to use your own recording. Start a fresh kernel and run the cells in order; the notebooks do not share variables or require files produced by another notebook.

Start here¶

From a repository checkout:

uv sync --extra notebooks
uv run jupyter lab examples/

To run the complete collection, including video and NWB:

uv sync --extra dev --extra notebooks --extra video --extra nwb
uv run jupyter lab examples/

If you are new to neurospatial, start with occupancy and firing-rate maps. The background links in the table introduce package concepts used later; each notebook can run on its own.

Notebook	Estimated time	Useful background
01. Where did the animal spend time?	15-20 minutes	None
02. Where does this neuron fire after accounting for occupancy?	20-25 minutes	01
03. When was the animal running, and which traversals were fully observed?	20-25 minutes	01
04. Where do hippocampal neurons fire along this maze?	25-30 minutes	02, 03
05. Can we recover a known place field from simulated spikes?	15-20 minutes	02
06. How accurately can population activity predict position?	20-25 minutes	02, 05
07. How does firing change around a cue?	15-20 minutes	02
08. Inspect spatial maps alongside behavior and video	15-20 minutes	02
09. Analyze an NWB recording and save the results	15-20 minutes	02

Analyze recorded hippocampal activity¶

The real-data tutorial downloads the 75 MB J16 Zenodo recording, verifies its SHA-256 and reuses the cache on subsequent runs. It combines neural rate maps and maze behavior in one analysis. To prepare for offline work, first run:

uv run python data/load_bandit_data.py

The data guide describes units, preprocessing, attribution and the CC BY 4.0 license.

Explore focused recipes¶

The core tutorials teach complete analyses. More specialized choices have focused recipes and explanations in the user guide:

Alternative layouts, morphology and composite environments.
Coordinate alignment, differential operators and spatial signal processing.
Specialized tuning recipes for boundary, grid, directional, head-direction, object-vector and spatial-view analyses.
Animation backends and large recordings and video calibration.
Interactive annotation launcher: try CPU or optional SAM 2 outlines on a sample arena, image, or video. See the setup and controls.

Reading and adapting the analyses¶

Positions and distances use the environment's declared units. Times are seconds and angles are radians. Allocentric angles use zero East and positive angles toward North; egocentric angles use zero ahead and positive angles left.
Blank rate-map locations have too little recorded occupancy. A measured rate of zero means the animal spent time there while spikes were recorded.
A place-field outline depends on the rate and area thresholds used to draw it. A claim about spatial tuning needs an appropriate statistical test.
Decode position in a different part of the recording from the one used to estimate place fields. Choose parameters before examining test performance.
Position can identify visits to maze arms. Use task logs to identify trials, reward delivery, and the choices available to the animal.

Optional viewers and exports¶

Static figures and small HTML examples run by default. Desktop viewers, interactive widgets and longer video exports require explicit opt-in flags where provided (RUN_NAPARI, RUN_WIDGET, RUN_VIDEO_EXPORT). The visualization tutorial creates its own short video; no private behavioral video is needed.

Edit and verify¶

The .py companions are Jupytext sources. Edit the source, synchronize the notebook, execute it to refresh figures, then update the documentation mirror:

uv run jupytext --sync examples/02_spatial_rate_maps.py
uv run jupyter nbconvert --to notebook --execute --inplace \
    --ExecutePreprocessor.timeout=600 examples/02_spatial_rate_maps.ipynb
uv run python docs/sync_notebooks.py
uv run pytest tests/docs/test_notebook_collection.py -n 0

The documentation includes this catalog and mirrors the notebooks. Edit examples/, not generated files under docs/examples/. CI checks source parity, metadata, links and prerequisites, and executes all nine notebooks in fresh kernels with optional desktop viewers disabled.