File size: 4,150 Bytes
66dc5d1 489067b 66dc5d1 489067b 66dc5d1 489067b 66dc5d1 489067b 66dc5d1 489067b 66dc5d1 489067b 66dc5d1 489067b 66dc5d1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | ---
license: cc-by-4.0
library_name: xgboost
tags:
- neuroscience
- electrophysiology
- neuropixels
- brain-region-classification
- international-brain-lab
---
# Ephys Atlas region classifier (2026_W32, Cosmos)
Predicts the **brain region of each Neuropixels recording channel** from electrophysiological
features alone -- no histology required. Trained by the
[International Brain Laboratory](https://www.internationalbrainlab.com/) on the Ephys Atlas
feature release `2026_W32`.
> **What you can and cannot do without IBL access.** The *model* runs for anyone. Computing
> the *input features* from raw Neuropixels data needs `ibllib` / `ibl-neuropixel`, and the
> raw data itself is IBL-hosted. To try the model immediately, use the bundled sample under
> `example/` -- no account, no raw data, no S3.
## Quickstart
```python
import pandas as pd
from ephysatlas import load_pretrained
model = load_pretrained("int-brain-lab/ea-decoder-channel-xgboost", revision="2026_W32")
df = pd.read_parquet("example/features_sample.parquet") # or your own features
out = model.predict(df)
print(out[["predicted_acronym", "prediction_probability", "fold_agreement"]].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:
`predicted_acronym`, its Allen `predicted_atlas_id`, the fold-averaged
`prediction_probability`, a `fold_agreement` column (fraction of the 5 folds voting
for the winner -- the natural uncertainty signal), and a `p_<acronym>` column per class.
The prediction columns are namespaced so that `df.join(out)` works: the feature table already
carries histology-derived `acronym` / `atlas_id` columns, and predictions must not shadow them.
## Inputs
- **50 features**, listed in `ephysatlas_model.json` under `inputs.features`. Every
one must be present; `predict` raises and names anything missing.
- Indexed by `(pid, channel)`, one row per recording channel.
- **Must be the denoised aggregated features of vintage `2026_W32`** -- that is, the
`raw_ephys_features_denoised.pqt` table produced by the Ephys Atlas aggregation pipeline,
as loaded by `ephysatlas.data.read_features_from_disk`. Units are baked into that table by
the pipeline (RMS features in dB, `spike_count` in log2), so feeding raw features, or
features from a vintage whose units differ, produces confident nonsense. Run
`model.selftest()` to confirm your install reproduces the shipped output before trusting it.
## Performance
Pooled out-of-fold accuracy: **0.5962** over 13 Cosmos regions,
765 insertions. Splits are by insertion (`pid`), so no channel from a test
insertion appears in training. See `confusion_matrix.png`.
## 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; rare regions are under-represented.
- `Cosmos` is a coarse parcellation. Predictions are per-channel and spatially
unregularised -- neighbouring channels can disagree.
- Known-misaligned insertions were excluded from training.
## Reproducibility
**Pin the revision.** `revision="2026_W32"` 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` (xgboost, scikit-learn, numpy,
ephysatlas, python) and `random_seed`. Verify your install reproduces the shipped output:
```python
model.selftest()
```
Note `scikit-learn<1.9` is required (1.9 broke `OneToOneFeatureMixin.get_feature_names_out`,
which the feature transformer relies on).
## Citation
Please cite the International Brain Laboratory Ephys Atlas. Model id `2026_W32_Cosmos_guiltless-orange-mallard`,
feature vintage `2026_W32`.
|