Demos

These notebooks train SPARKS on real recordings, from the data to the figures. Each one is shown here with its outputs: click on a title to read it, or get the notebook from GitHub to run it yourself. They use sparks-ai 0.3; see the documentation for the details of each function.

Running the notebooks

• Install SPARKS with the demos extra, which adds Jupyter and matplotlib, plus the extra of the demo's data loader: pip install "sparks-ai[demos]", "sparks-ai[nlb,demos]" or "sparks-ai[allen,demos]". See the installation instructions.
• A GPU is recommended. The notebooks use one automatically if PyTorch can see it; on Apple silicon, you can try the 'mps' device.
• Each notebook says where to get its data. Set data_path to your local copy before running it.

Oscillatory sequences in the medial entorhinal cortex

Can SPARKS reveal structure in neural data without being told what to look for? This notebook trains it without labels on a calcium-imaging recording of about 500 neurons in the medial entorhinal cortex of a mouse (Gonzalo Cogno et al., 2024). The two-dimensional latents go round a ring; the position around the ring is the phase of an oscillation, and sorting the neurons by their preferred phase reveals the minutes-long sequences in which they fire.

• You will learn to: train SPARKS as a variational autoencoder (unsupervised=True), use the sequential KL, and process a long recording in chunks.
• Data: downloaded automatically from the original paper's repository. Extras: demos. Training: about 30 minutes on a GPU.

Decoding hand position from somatosensory cortex

This notebook trains SPARKS to predict a monkey's hand position from the spikes of 65 neurons in its somatosensory cortex (area 2), as it reaches toward one of eight targets, using the Area2_Bump dataset of the Neural Latents Benchmark. On held-out trials, the predictions reach an R² of about 0.95, and the two-dimensional latents, averaged over the trials of each direction, trace out the hand's trajectories.

• You will learn to: decode a behavioural variable (supervised learning), add shared attention blocks, read a window of past latents with a linear decoder, and use the recommended training recipe.
• Data: DANDI 000127. Extras: nlb, demos. Training: about 4 minutes on a GPU.

One model for several mice: decoding a natural movie

SPARKS can embed recordings from several sessions, with different neurons and different numbers of them, in a single latent space. This notebook trains one model on Neuropixels recordings from the primary visual cortex of three mice watching a 30 s natural movie, from the Allen Brain Observatory, and decodes which of the movie's 900 frames is showing. The latents of the three mice follow each other. A fourth mouse is then added to the trained model and fine-tuned.

• You will learn to: train on several sessions with a shared decoder, classify a frame at every time bin, and add a new session to a trained model with add_session.
• Data: the Allen Visual Coding Neuropixels dataset, prepared with the repository's preprocessing script (a first download takes hundreds of GB). Extras: allen, demos. Training: about 8 minutes on a GPU.

The scripts that reproduce every figure of the paper are in the sparks-examples repository (see Reproducing the paper).