| ---
|
| 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_W42)
|
|
|
| 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 four 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 **hierarchical Gaussian mixture** over the standardised latents: 30 putative cell
|
| types, each split into at most 10 sub-types (300 in all). Assignment is
|
| top-down -- the most likely type, then the most likely of its sub-types -- so a unit's
|
| sub-type always lies inside its type. The types and sub-types are global;
|
| 3. the **sub-type weights depend on the molecular and cellular context** (PCA volumes of the
|
| molecular and cellular atlases) at the position: one network predicts the type weights, a
|
| second the shares of the sub-types within each type;
|
| 4. a **members 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`. Each sub-type is represented by its training units, from anywhere in the brain,
|
| weighted by their posterior of the sub-type.
|
|
|
| > **The input is a position.** `predict` takes `x, y, z` (IBL/Allen frame, metres) and returns the
|
| > expected phenotype there: the local sub-type weights times each sub-type's expected features.
|
| > `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_W42")
|
| df = pd.read_parquet("example/positions_sample.parquet") # positions (x, y, z)
|
| out = model.predict(df) # one pred_<feature> column each
|
| types = model.mixture_weights(df, level="type") # putative cell-type composition
|
| subtypes = model.mixture_weights(df) # ... and of the sub-types
|
| draws = model.sample(df, n_samples=16) # training units drawn at each position
|
| 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 and sub-type with `model.assign(z)`.
|
|
|
| ## What ships here
|
|
|
| - `autoencoder.pt`, `shared_latent_scaler.joblib` -- the phenotype encoder and its latent scaler.
|
| - `types_gmm.joblib`, `subtypes_gmm.joblib`, `subtype_parent.npy` -- the types, the sub-types and
|
| the type of each sub-type.
|
| - `context_transform.joblib`, `context_weights_types.pt`, `context_weights_subtypes.pt` -- context
|
| -> type and sub-type weights.
|
| - `members.npz` -- the phenotype features of the training units and their sub-type posteriors
|
| (the readout; part of the model, like the stored points of any nearest-neighbour model).
|
| - `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 release `2026_W41`.
|
| - `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_W42"` 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_W42_unit`, vintage
|
| `2026_W42`.
|
| |
