README.md

---
license: cc-by-4.0
library_name: pytorch
tags:
  - neuroscience
  - electrophysiology
  - neuropixels
  - spatial-encoding
  - international-brain-lab
---

# Ephys Atlas spatial encoder (2026_W26)

Predicts the **electrophysiological feature vector expected at a channel's position** -- from
that position plus anatomical context and the recorded features of nearby channels on other
insertions. Trained by the
[International Brain Laboratory](https://www.internationalbrainlab.com/) on the Ephys Atlas
feature release `2026_W26`.

> **The input is a position, not features.** This is the inverse of the region classifier: that
> model takes features and returns a region; this one takes a channel's `x, y, z` (Allen frame,
> metres) and returns the 41 ephys features it would expect there. Feeding it the
> feature columns instead of coordinates is the most common mistake -- `predict` raises and names
> the coordinates it needs.

## What ships in this repo, and why all of it is needed

A published encoder is not the weights alone. `predict` cannot run without every one of:

- `spatial_encoder.pt` -- the trained network.
- the context PCA volumes (`agea_vol_pca.npy`, `merfish_vol_pca.npy`) -- the anatomical context
  it samples at each position.
- `neighbor_bank.npz` -- the **neighbour bank**: the position, standardised feature vector and
  insertion id of every training channel. At inference the model gathers the nearest recorded
  channels from this bank and attends to them, so the bank *is* part of the model, the way the
  stored points are part of a k-nearest-neighbours model. It cannot be reconstructed from the
  weights, which is why it is shipped here rather than recomputed on your machine.

> **First run downloads the Allen volume.** Building the context sampler constructs an
> `AllenAtlas`, which fetches the Allen CCF volume from `download.alleninstitute.org` (public, no
> account, a few hundred MB) the first time it runs on a machine, then caches it.

## Quickstart

```python
import pandas as pd
from ephysatlas import load_pretrained

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

`load_pretrained` is the entry point for every ephysatlas model, whatever its family -- it reads
`ephysatlas_model.json` and returns the right wrapper. Use it rather than importing a concrete
class, so your code keeps working as the package evolves.

`predict` returns one row per input channel, indexed identically to the input, with a
`pred_<feature>` column per entry in `outputs.columns`. The `pred_` prefix keeps `df.join(out)`
from colliding with the ground-truth feature columns of the same names.

## Inputs

- Indexed by `(pid, channel)`, one row per recording channel.
- The coordinate columns `x, y, z` named in `ephysatlas_model.json` under `inputs.columns`, in
  the Allen atlas frame, **in metres**. The feature columns are *not* read -- they are the output.

## Neighbourhood selection

For each query position the model attends to recorded channels within **500.0 µm**, taking
the **nearest 8** (`selection: nearest`). This is deterministic: two calls on the same
input return identical predictions.

> Training used a *random* subset of the in-radius neighbours; this published `predict` takes the
> nearest instead. The two agree exactly whenever a position has at most 8 neighbours in
> radius, and differ only in dense regions where the training-time subset would itself have varied
> run to run. Deterministic output is the right contract for a published model.

## Limitations

- Trained on IBL Neuropixels 1.0 recordings in mouse. Transfer to NP2, other species or other
  rigs is untested.
- Coverage follows IBL brain-wide-map targeting; predictions far from any recorded channel fall
  back on anatomical context alone and are correspondingly weaker.

## Reproducibility

**Pin the revision.** `revision="2026_W26"` is an immutable tag. Omitting `revision` resolves to
`main`, which tracks whichever model is currently recommended and *will* change when a new feature
vintage is published -- fine for a first look, not for anything you publish or re-run.

`ephysatlas_model.json` records the training-time `environment` and `random_seed`. Verify your
install reproduces the shipped output:

```python
model.selftest()
```

## Citation

Please cite the International Brain Laboratory Ephys Atlas. Model id `ea-encoder-channel`,
feature vintage `2026_W26`.