nstat-toolbox 0.6.0

Neural Spike Train Analysis Toolbox for Python

Jump to: Quickstart · Concepts learning track · Tutorials and notebooks · Paper examples · nstat.extras helpfiles · Reference · Ecosystem · Citation

📖 New here? Start with the 5-minute intro — a friendly tour of the toolbox with runnable snippets, the nstat.extras opt-in bridges, and the paper-example gallery.

🎓 Learning the science? The Concepts & Background guide teaches microelectrode recordings, the LFP, point-process GLMs, goodness-of-fit, and decoding — with figures, runnable examples, and cited literature.

🛠 Other ways in: the runnable 00_getting_started.ipynb notebook; six end-to-end tutorial scripts in examples/tutorials/; the five paper examples in examples/paper/; and the reference notebooks in notebooks/.

nSTAT-python is the Python port of the nSTAT toolbox (Cajigas, Malik & Brown 2012). It implements point-process generalized linear models (GLMs) with stimulus, history, and ensemble terms; the time-rescaling KS test for goodness-of-fit (per-neuron and population-level via population_time_rescale, Tao et al. 2018); adaptive decoding (PPAF / PPHF / Kalman / EM); and continuous-signal analysis for LFP / EEG / ECoG (multitaper spectra, spectrograms, Kalman filtering). An opt-in nstat.extras namespace adds bridges to Dynamax (EM-trained state-space models), replay_trajectory_classification (clusterless decoding), Neo / pynapple / pynwb (data I/O), and validation oracles.

Although designed for neural signal processing, nSTAT works as a generic toolkit for analyzing any discrete or continuous time series. From the lab: Neuroscience Statistics Research Laboratory and RESToRe Lab.

Quickstart

python -m pip install nstat-toolbox
nstat-install --download-example-data always   # ~150 MB figshare dataset

import numpy as np
from nstat import nspikeTrain

times = np.sort(np.random.default_rng(0).uniform(0, 1, 100))
st = nspikeTrain(times, name="neuron1", sampleRate=1000,
                 minTime=0.0, maxTime=1.0)
print(f"{st.n_spikes} spikes")

From source (development install):

git clone git@github.com:cajigaslab/nSTAT-python.git
cd nSTAT-python
python -m pip install -e .[dev]
nstat-install --download-example-data always
pytest -q && python tools/paper_examples/build_gallery.py

The example dataset is also reachable from Python:

from nstat.data_manager import ensure_example_data
data_dir = ensure_example_data(download=True)

Performance — Numba opt-in (v0.5.6+)

For the two hot per-step filter paths, an opt-in Numba JIT closes the last performance gaps vs. MATLAB:

python -m pip install nstat-toolbox[numba]

Once Numba is installed, DecodingAlgorithms.PPDecodeFilterLinear and DecodingAlgorithms.kalman_filter route through JIT'd kernels transparently — 14× and 20× faster than MATLAB respectively on the maintainer's M2 Max baseline. Default install is unchanged; the JIT path is dual-mode tested in CI to preserve bit-equivalence against the gold-fixture suite.

docs/parity/runbook.md documents the 10-path performance baseline and the workflow for re-timing after a code change.

Concepts learning track

A 15-page didactic track that teaches the neuroscience and statistics behind the API. Each page builds intuition first, then shows the matching nSTAT objects and a runnable snippet, and cites the primary literature. The concepts index hosts the full path; the table below is the direct map.

Every topical page opens with a "Glossary jumps" box that deep-links into the glossary entries it uses.

Tutorials and notebooks

Runnable, end-to-end lessons organized by depth:

Reference notebooks (MATLAB-help ports) live under notebooks/ and the "By concept" crosswalk in the Example Index maps each concepts page to the notebooks that demonstrate it.

🖼 Browse rendered notebook figures on GitHub: docs/notebook_galleries/ — every notebook's FigureTracker output, regenerated by make regen-notebook-galleries and drift-checked in CI. Each gallery links back to its source .ipynb.

Paper examples

The five canonical examples from Cajigas, Malik & Brown (2012), each reproduced as a self-contained Python script with a generated figure gallery.

Regenerate the gallery metadata after editing any paper-example script:

python tools/paper_examples/build_gallery.py

Example	Thumbnail	What question it answers	Run command	Links
Example 01		Do mEPSCs follow constant vs piecewise Poisson firing under Mg2+ washout?	python examples/paper/example01_mepsc_poisson.py	Script · Figures
Example 02		How do explicit whisker stimulus and spike history improve thalamic GLM fits?	python examples/paper/example02_whisker_stimulus_thalamus.py	Script · Figures
Example 03		How do PSTH and SSGLM capture within-trial and across-trial dynamics?	python examples/paper/example03_psth_and_ssglm.py	Script · Figures
Example 04		Which receptive-field basis (Gaussian vs Zernike) better fits place cells?	python examples/paper/example04_place_cells_continuous_stimulus.py	Script · Figures
Example 05		How well do adaptive/hybrid point-process filters decode stimulus and reach state?	python examples/paper/example05_decoding_ppaf_pphf.py	Script · Figures
Example 06		How does a tensor-product B-spline Poisson GLM recover a known 2-D place field, and how do its rate and second-order diagnostics compare to an LGCP?	python examples/paper/example06_place_fields_glm_basis.py	Script · Figures
Example 07		Can the Bartlett spectrum and wave-peak detector recover the speed and direction of a known planar wave embedded in a multivariate Hawkes triggering matrix?	python examples/paper/example07_spatiotemporal_hawkes_waves.py	Script · Figures
Example 08		Does a B-spline Poisson GLM trained on real hippocampal place cells produce a held-out spatial pair-correlation inside the inhomogeneous global-rank envelope, and a population rescaled-time ACF inside the Bartlett band?	python examples/paper/example08_real_place_cells.py	Script · Figures

Expanded paper-example index and figure gallery: docs/paper_examples.md.

The figshare paper dataset is distributed separately from the Git repository: DOI 10.6084/m9.figshare.4834640.v3 (nstat-install --download-example-data always fetches it; NSTAT_OFFLINE=1 forces offline mode).

Plot-style policy (modern readability vs strict-reproduction legacy):

from nstat.plot_style import set_plot_style
set_plot_style('modern')   # default
set_plot_style('legacy')   # strict paper reproduction

nstat.extras helpfiles

Opt-in bridges (nstat.extras.*) to libraries in the modern Python systems-neuroscience stack. Each has a dedicated narrative helpfile under docs/extras/ covering install, intended use, gotchas, and runnable snippets. Install via the optional-dep group; install the lightweight groups at once with pip install nstat-toolbox[all-extras] (this is not every group: latents, numba, clusterless, spatial-gp, hawkes, dpp and dynamax are excluded by design — install them individually).

The interactive extras_summary.html landing page has the same content as bigger cards with code snippets.

Reference

Full rendered documentation is on GitHub Pages:

Ecosystem

The MATLAB reference toolbox lives in a separate repository: github.com/cajigaslab/nSTAT. It retains the original MATLAB classes, the helpfiles/helptoc.xml index, and the .mlx example workflows.

For ecosystem peers nSTAT does not wrap (spike sorting, calcium imaging, deep-learning decoders), recommended alternatives — with rationale in parity/integration_opportunities.md:

• SpikeInterface — spike sorting (nSTAT consumes pre-sorted data).
• Elephant — overlapping spike-train statistics; Neo-typed.
• ssqueezepy — wavelet synchrosqueezing; planned nstat.extras.spectral.

nSTAT will benefit from your involvement. Open issues / PRs at github.com/cajigaslab/nSTAT-python.

Citation

If you use nSTAT in your work, please cite the toolbox paper:

Cajigas I, Malik WQ, Brown EN. nSTAT: Open-source neural spike train analysis toolbox for Matlab. Journal of Neuroscience Methods 211: 245–264, Nov. 2012. doi:10.1016/j.jneumeth.2012.08.009 · PMID 22981419

Method references for every page in the concepts track are in the annotated bibliography. The paper-example dataset has its own figshare DOI. nSTAT-python is distributed under the GPL-2.0 license.