Examples¶
Real-world examples demonstrating neurospatial's capabilities through
interactive Jupyter notebooks. Notebooks are paired with .py
(jupytext, percent format) and .ipynb files; either can be edited
and the pair syncs via docs/sync_notebooks.py.
This index mirrors examples/README.md in the repo.
Goal → Notebook¶
If you have a specific neuroscience question, jump straight to the relevant notebook.
| Goal | Notebook(s) |
|---|---|
| Build an environment from position data | 01, 03 |
| Pick the right layout (grid / hex / polygon / graph) | 02, 05 |
| Define spatial regions / zones of interest | 04 |
| Compute occupancy and a spatial firing-rate map | 08, 11 |
| Detect place fields and compute place-cell metrics | 11 |
| Direction-conditioned place fields | 21 |
| Boundary / border cells | 12 |
| Spatial view cells | 22 |
| Object-vector cells | 24 |
| Head-direction tuning | 25 |
| Peri-event histograms (PSTH) | 26 |
| Load data from an NWB file | 27 |
| Trajectory metrics (step length, MSD, curvature) | 13 |
| Detect laps, trials, and region crossings | 14 |
| Bayesian decoding from population spikes | 20 |
| Animate fields (napari / video / HTML / widget) | 16, 17 |
| Composite raw video with spatial fields | 18 |
| Simulate trajectories and spike trains | 15 |
| Differential operators, signal processing on graphs | 09, 10 |
| Multi-room / composite environments | 06, 07 |
| Real-data end-to-end pipeline | 19 |
Foundations (01-07)¶
01. Introduction & Basics¶
Time: 15-20 min · Prerequisites: none
Spatial discretization, creating an environment from position data,
bin_size and active bins, basic spatial queries (bin_at,
contains, neighbors), visualization, common pitfalls. Start
here.
02. Layout Engines¶
Time: 20-25 min · Prerequisites: 01
Regular grids vs hexagonal tessellations, polygon-bounded environments, connectivity patterns, side-by-side comparison.
03. Morphological Operations¶
Time: 15-20 min · Prerequisites: 01
Active bin inference, dilate / fill_holes / close_gaps,
bin_count_threshold, fixing fragmented environments.
04. Regions of Interest¶
Time: 15-20 min · Prerequisites: 01
Creating point and polygon regions, region operations, using regions in analysis, serialization.
05. Track Linearization¶
Time: 20-25 min · Prerequisites: 01, 02
Building 1D environments from track graphs, mapping 2D position to linear coordinates, T-maze / W-maze / plus-maze examples.
06. Composite Environments¶
Time: 25-30 min · Prerequisites: 01, 02
Multi-room arenas, automatic bridge edges via mutual nearest neighbors, querying across rooms, plus-maze with separate compartments.
07. Advanced Operations¶
Time: 20-30 min · Prerequisites: 01, 06
Subsetting, applying transforms, custom layouts via from_layout.
Spatial Coding (08-12)¶
08. Spike-Field Basics¶
Time: 25-35 min · Prerequisites: 01
Mapping spike times to bin indices, computing occupancy and rate maps from scratch, smoothing methods (diffusion KDE, gaussian KDE, binned).
09. Differential Operators¶
Time: 25-35 min · Prerequisites: 02
Edge-oriented differential operator, gradient and divergence on graphs, laplacian, signal-processing primitives.
10. Signal Processing Primitives¶
Time: 25-35 min · Prerequisites: 09
Graph kernels, spatial basis functions (geodesic RBF, heat kernel,
Chebyshev), smoothing with compute_kernel and apply_kernel.
11. Place Field Analysis¶
Time: 30-40 min · Prerequisites: 08
Build place fields from spike trains, detect place fields with
detect_place_fields, compute spatial information / sparsity /
selectivity, analyze field sizes and centroids.
12. Boundary Cell Analysis¶
Time: 25-35 min · Prerequisites: 11
Distance-to-boundary fields, border score, classifying boundary cells.
Behavior (13-15)¶
13. Trajectory Analysis¶
Time: 25-35 min · Prerequisites: 01
Step lengths, turn angles, MSD, curvature, home range, persistence.
14. Behavioral Segmentation¶
Time: 25-35 min · Prerequisites: 04, 13
Lap detection, trial segmentation, region crossings, velocity-based movement / rest segmentation.
15. Simulation Workflows¶
Time: 30-40 min · Prerequisites: 11
Generate synthetic trajectories and spike trains, ground-truth
validation, simulate_session API, pre-configured examples.
Animation & Visualization (16-18)¶
16. Field Animation¶
Time: 20-30 min · Prerequisites: 08
Animate spatial fields over time using napari / HTML / widget / video backends.
17. Animation with Overlays¶
Time: 25-35 min · Prerequisites: 16
Position, pose, head-direction, event, and spike overlays composed on field animations.
18. Video Overlay¶
Time: 25-35 min · Prerequisites: 17
Composite raw behavioral video with spatial-field overlays for publication / talks.
Advanced Neural Coding (19-27)¶
19. Real-Data Bandit Task¶
Time: 40-60 min · Prerequisites: 05, 11, 13
End-to-end pipeline on a hippocampal recording from a plus-maze
bandit task. Loads the J16 dataset (see data/README.md for download
instructions); the notebook prints the download URL and exits cleanly
if the data files are missing.
20. Bayesian Decoding¶
Time: 35-45 min · Prerequisites: 11, 15
Decode position from population spike counts, MAP / posterior-mean estimates, decoding-error metrics, sequential decoders.
21. Directional Place Fields¶
Time: 25-35 min · Prerequisites: 11
Direction-conditioned place fields on linear tracks; building rate maps separately per running direction.
22. Spatial View Cells¶
Time: 30-40 min · Prerequisites: 11
Build firing-rate fields indexed by gaze direction rather than
position. Three gaze models (fixed-distance, ray-cast, boundary).
Classification via is_spatial_view_cell.
23. Path Progression¶
Time: 25-35 min · Prerequisites: 05, 14
Path progression along linearized tracks; per-trial alignment for sequential analyses.
24. Object-Vector Cells¶
Time: 30-40 min · Prerequisites: 11
Object-vector cells: firing tuned to (distance, egocentric direction)
to external landmarks. Uses compute_egocentric_rate and
is_object_vector_cell classification.
25. Head-Direction Tuning¶
Time: 25-35 min · Prerequisites: 08
Build a circular tuning curve over head direction, Rayleigh test for
significant directionality, is_head_direction_cell classification,
polar plotting.
26. Peri-Event PSTH¶
Time: 25-35 min · Prerequisites: 11
Align spikes to discrete event times (reward arrivals, lap starts). Compute peri-event histograms, plot rasters, build GLM regressors.
27. Loading from NWB¶
Time: 25-35 min · Prerequisites: 01, 11
Read position, spikes, and environment metadata from a synthetic in-memory
NWB file. Build a neurospatial environment, recover place fields, write
derived results back into the NWB; the same API applies to downloaded DANDI
files.
Editing notebooks
The notebooks displayed here are automatically synced from the
examples/ directory.
To update notebooks in the documentation:
- Edit notebooks in the
examples/directory (repository root) - Run
uv run python docs/sync_notebooks.pybefore building docs - The GitHub Actions workflow automatically syncs notebooks on deployment
Do not edit generated files directly in docs/examples/ - they
will be overwritten.