README.md

---

license: cc-by-4.0
library_name: pytorch
tags:
  - neuroscience
  - electrophysiology
  - neuropixels
  - unit-level-encoder
  - international-brain-lab
---


# Ephys Atlas unit-level interpolation model (2026_W41)



Predicts **which kinds of neurons you expect to record at a brain position**, and their expected

waveform phenotype. Trained by the

[International Brain Laboratory](https://www.internationalbrainlab.com/) on spike-sorted units of

the Ephys Atlas release `2026_W41` (56497 training units).

The model has three stages:

1. a multimodal autoencoder embeds each unit's multi-channel **waveform**, 3D
   **autocorrelogram** and **population coupling** (waveform, acg, stpc) into a
   60-d latent -- its phenotype;
2. a **25-component Gaussian mixture** over the standardised latents, whose
   components read as putative cell types. Component shapes are global; the **mixture weights

   depend on the molecular and cellular context** (PCA volumes of the molecular and cellular
   atlases) at the unit's position;
3. a **context-local exemplar readout** maps the model back to 10 interpretable waveform features: `depolarisation_slope`, `recovery_slope`, `repolarisation_slope`, `spatial_spread_um`, `tip_val`, `spike_width_secs`, `predepolarisation_width_secs`, `spike_amplitude`, `peak_to_trough_ratio_log`, `polarity`. At a position, each component is represented by its training members whose molecular context resembles the position's (the 4096 nearest in a 3-d context key, shrunk toward all of the component's members -- the more so the farther the context lies from the training data, and entirely where there is no context). So the context sets the mixture weights **and** selects which training exemplars represent each component; the latent density depends on it only through the weights.

> **The input is a position.** `predict` takes `x, y, z` (IBL/Allen frame, metres) and returns the
> expected phenotype there: the local component weights times each component's expected features
> there. `mixture_weights` returns the local putative cell-type composition itself.



## Quickstart



```python

import pandas as pd

from ephysatlas import load_pretrained

model = load_pretrained("int-brain-lab/ea-encoder-unit", revision="2026_W41")
df = pd.read_parquet("example/positions_sample.parquet")   # positions (x, y, z)
out = model.predict(df)                                     # one pred_<feature> column each

weights = model.mixture_weights(df)                         # putative cell-type composition
draws = model.sample(df, n_samples=16)                   # training units drawn from the predictive distribution

model.selftest()                                            # reproduces the shipped outputs

```



Units you recorded yourself can be embedded with `model.encode(waveform, acg, stpc)` (arrays shaped

as in `config.json`), then assigned to a putative cell type with `model.assign(z)`.



## What ships here



- `autoencoder.pt`, `shared_latent_scaler.joblib` -- the phenotype encoder and its latent scaler.

- `global_gmm.joblib` -- the mixture's component means and covariances.
- `context_transform.joblib`, `context_weight_model_bundle.pt` -- context -> mixture weights.
- `knn_bank.npz` -- standardised latents, phenotype features, GMM components and context keys of the training units (the exemplars; part of the model, like the stored points of any nearest-neighbour model).
- `component_feature_expectations.npz` -- each component's expected features over the whole
  brain.
- `agea_vol_pca.npy`, `merfish_vol_pca.npy` -- the molecular and cellular context volumes, the same frozen
  volumes as the channel-level model `int-brain-lab/ea-encoder-channel` of this vintage.
- `split.json`, `config.json`, `preprocessing/unit_stats.npz`, `results/` -- the probe split, the
  training configuration, the training-data statistics and held-out evaluation summaries.

The recorded per-unit dataset (waveforms, ACGs, positions) is **not** here: it stays on IBL S3 and
is only needed to retrain the model or to reproduce the atlas-wide analyses.

> **First run downloads the Allen volume.** Sampling the context constructs an `AllenAtlas`, which
> fetches the Allen CCF volume (public, no account, a few hundred MB) once per machine.

## Reproducibility

**Pin the revision.** `revision="2026_W41"` is an immutable tag; omitting it resolves to `main`,
which tracks the currently recommended model. `ephysatlas_model.json` records the training-time
environment and random seed; `model.selftest()` verifies your install reproduces the shipped
output (no IBL account needed).

## Citation

Please cite the International Brain Laboratory Ephys Atlas. Model id `2026_W41_unit`, vintage
`2026_W41`.