Sovereign 8s.is mirror of standardgalactic/brainwide-RRR-encoding-model
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-04-10 14:42:27 +02:00
data Update contents 2026-04-10 11:35:25 +02:00
Fig2_globally_structured_brain Update contents 2026-04-10 11:35:25 +02:00
trained_RRR_model Update contents 2026-04-10 11:35:25 +02:00
utils Apply gitignore 2026-04-10 11:47:08 +02:00
.gitattributes Update contents 2026-04-10 11:35:25 +02:00
.gitignore Apply gitignore 2026-04-10 11:47:08 +02:00
LICENSE Add MIT License to the project 2026-04-10 13:24:17 +02:00
README.md update readme 2026-04-10 14:41:23 +02:00
step1_IBL_downloaddata.py Update contents 2026-04-10 11:35:25 +02:00
step2_train_RRR.py Update contents 2026-04-10 11:35:25 +02:00
step3_save_trainedRRR_2_df.py Update contents 2026-04-10 11:35:25 +02:00

Brain-Wide RRR Encoding Model — IBL Example

A complete example of fitting a reduced-rank regression (RRR) model to multiple sessions of the IBL brain-wide-map dataset, as used in the paper:

"Rarely categorical, highly separable representations along the cortical hierarchy" L. Posani*, S. Wang*, S. Muscinelli, L. Paninski$, and S. Fusi$ (2026)

*Equal contribution $Co-senior authors

Overview

This subfolder walks through the full pipeline for training and exporting the RRR model:

  1. Download sessions using the IBL public API
  2. Train the RRR model
  3. Export the trained model to a DataFrame
  4. Examine the trained model (figure scripts)

Steps 1–3 can take a long time (~3 days) to complete end-to-end. To save effort, we provide a pre-trained model in ./trained_RRR_model/ — you can skip directly to step 4 if you only want to reproduce the analyses.

The notation and parameter names follow the conventions established in the main text and Methods section of the paper. Please refer to the paper for detailed definitions and further context.

Related resources:

Note: The pre-trained model is large and thus we used Git LFS. Install it (git lfs install) before cloning, or run git lfs pull after cloning to fetch it.

Getting Started

This repository uses Git LFS to track the pre-trained RRR model, which is large. Install Git LFS before cloning:

git lfs install
git clone <repository-url>

If you have already cloned the repository without Git LFS, run git lfs pull to fetch the model file.

Dependencies

Python >= 3.10 is required. Install all dependencies before running any script:

# IBL data access
pip install ONE-api ibllib

# Core scientific stack
pip install torch numpy scipy pandas scikit-learn tqdm

# Plotting
pip install matplotlib seaborn

Pipeline

Step 1 — Download sessions from the IBL public API

python step1_IBL_downloaddata.py

Downloaded data will be saved in ./data/downloaded/.

Step 2 — Train the RRR model

python step2_train_RRR.py

This script first pre-processes the downloaded data (see Methods of the paper for details) and constructs two matrices:

  • Xall — trial-aligned, time-varying input variables, shape [n_trials, n_timesteps, n_vars]
  • yall — trial-aligned, time-varying neural activity, shape [n_trials, n_timesteps, n_neurons]

It then fits an RRR model to these matrices. The optimal rank and L2 regularization penalty are selected via 3-fold cross-validation across trials. The trained model is saved to ./trained_RRR_model/RRRGD/.

Step 3 — Export the trained model to a DataFrame

python step3_save_trainedRRR_2_df.py

This produces a DataFrame version of the trained model, saved as ./trained_RRR_model/RRR_selectivity.json. Each row corresponds to a neuron, with the following columns:

  • uuids — unique neuron identifier
  • eid — session identifier
  • acronym — brain region of the neuron
  • RRR_r2 — average 3-fold cross-validated R² of the RRR model
  • RRR_beta — time-varying coefficients of the neuron, shape (n_vars+1, n_timesteps). The first n_vars rows are the input-variable coefficients; the last row is the bias term.
  • RRR_U — per-neuron loadings of the temporal basis vectors, shape (n_vars, n_components), where n_components is the rank of the RRR model.
  • RRR_V — shared temporal basis vectors (same across all neurons), shape (n_components, n_timesteps).
  • RRR_b — per-neuron time-varying biases, shape (n_timesteps,). These should be close to zero if the input variables are normalized.
  • null_r2 — average 3-fold cross-validated R² of a baseline null model that is agnostic to input variables (only time in trial).

Step 4 — Examine the trained model

Figure scripts for further analyses of the model coefficients live in Fig2_globally_structured_brain/. Run them from within that directory:

cd Fig2_globally_structured_brain/
python <figure_script>.py

Contact

For questions, please contact shuqi.wang@epfl.ch.