hippie

HIPPIE: A Generative Model for Electrophysiological Analysis Across Species, Technologies, and Modalities

HIPPIE is a conditional variational autoencoder for extracellular electrophysiology. It ingests three per-unit modalities (mean waveform, inter-spike-interval distribution, autocorrelogram) and learns a joint latent representation conditioned on recording technology. The released checkpoint was pretrained on 11 publicly available electrophysiology datasets and is intended for transfer to new recordings without retraining the full model.

---

Model Details

Architecture

Each modality is independently encoded by a 1D ResNet18 backbone with channel widths [64, 128, 256, 512]. A fusion encoder concatenates the three modality representations and projects to the shared latent space. The decoder mirrors the encoder structure and is conditioned on both the latent code and (during supervised fine-tuning) a cell-type label; the encoder is class-agnostic at inference time (encoder_uses_class_embedding=False in the production config). The released checkpoint disables super-region and layer conditioning (num_super_regions=0, num_layers=0); only the recording-technology source embedding is active.

For datasets that ship without an autocorrelogram (bimodal recordings), the ACG channel is zero-filled.

Input format

Each per-unit input is a float32, batch-first array, pre-normalized to [-1, 1]:

• wave: (N, 50) mean waveform, min-max normalized.
• isi: (N, 100) log(x+1) of the ISI histogram, min-max normalized.
• acg: (N, 100) autocorrelogram, min-max normalized (zeros if unavailable).

Conditioning is a per-unit integer tech_id in {0, 1, 2} (see the Technology Conditioning Vocabulary below).

Output format

HIPPIEClassifier.get_embeddings(...) returns the joint latent code z of shape (N, 30) (10 latent dimensions per modality across the 3 modalities).

---

Intended Use

The checkpoint is intended for:

• Extracting joint latent representations from new extracellular recordings for downstream classification, clustering, or visualization.

The HIPPIE generative decoder additionally supports the following capabilities, which are demonstrated in the manuscript rather than shipped as turnkey features (they require the generative decoder and the analysis code in the HIPPIE release):

• Cross-modal imputation: reconstructing a missing modality from the remaining inputs.
• Counterfactual decoding: predicting how a unit's signal would appear under a different recording technology.

Not intended for

• Clinical diagnosis, treatment decisions, or any safety-critical application.
• Calibrated probabilistic inference. The KNN/MLP probe heads used in the paper are post-hoc and are not part of the released checkpoint.
• Human electrophysiology. Pretraining used only mouse, rat, and macaque data; transfer to human recordings has not been validated.

Limitations

• Species coverage: pretraining used mouse, rat, and macaque data. No human electrophysiological data was used; transfer to human recordings has not been validated.
• Featurization: the model takes mean waveform, ISI distribution, and ACG only. It does not consume raw spike trains, multi-channel waveforms, or local field potentials.
• Cell-type vocabulary: per-dataset cell-type labels are heterogeneous and were used during dataset-specific supervised fine-tuning, not during the pretraining that produced this checkpoint. For tasks that require species- or region-specific class predictions, fine-tune with the appropriate vocabulary using cross_dataset_script.py in the HIPPIE release.
• Cortical-layer / brain-region conditioning: the released checkpoint disables super-region and layer embeddings (num_super_regions=0, num_layers=0); only technology conditioning is active.
• Quality of input features: performance depends on upstream spike sorting and unit curation. Use the data-wrangling scripts in the HIPPIE release as a starting point.

---

Training Data

Pretrained on 11 labeled electrophysiology datasets spanning mouse, rat, and macaque. Cell-type counts and sample sizes follow the manuscript Methods.

Technology Conditioning Vocabulary

hippie.inference.TECHNOLOGY_IDS maps the three technology classes to the integer used by the source-conditioning embedding:

---

Installation

The released hippie Python package wraps the model and provides a small inference API. Install it from the HIPPIE release:

git clone https://github.com/braingeneers/HIPPIE.git
cd HIPPIE
pip install -e .
pip install huggingface-hub   # to pull the checkpoint

---

How To Use

Quick start: pretrained encoder from the Hub

from hippie.inference import HIPPIEClassifier

classifier = HIPPIEClassifier.from_pretrained(
    repo_id="Jesusgf23/hippie",
    filename="hippie_techcond_v1.ckpt",
    device="cuda",      # or "cpu"
)

Extract latent embeddings

import numpy as np
from hippie.inference import TECHNOLOGY_IDS

# Inputs (float32, batch-first), all pre-normalized to [-1, 1]:
#   wave: (N, 50)   waveform, min-max normalized
#   isi:  (N, 100)  log(x+1) of ISI histogram, min-max normalized
#   acg:  (N, 100)  autocorrelogram, min-max normalized (zeros if unavailable)

z = classifier.get_embeddings(
    wave=wave,
    isi=isi,
    acg=acg,
    tech_id=TECHNOLOGY_IDS["neuropixels"],   # or 0, 1, 2
    batch_size=256,
)
# z shape: (N, 30)

UMAP and HDBSCAN on the embeddings

coords = HIPPIEClassifier.umap_reduce(z, n_components=2, n_neighbors=30, metric="cosine")
clusters = HIPPIEClassifier.hdbscan_cluster(z, min_cluster_size=5)

Loading from a local checkpoint

classifier = HIPPIEClassifier.from_checkpoint("./hippie_techcond_v1.ckpt", device="cuda")

End-to-end script

A runnable CLI version of the snippets above ships in this repo as extract_embeddings.py (mirrored in the HIPPIE GitHub release). It loads the checkpoint (Hub by default, --checkpoint for local), iterates a directory of per-dataset CSVs in the canonical HIPPIE layout, and writes the concatenated embeddings to a single .npz:

python extract_embeddings.py \
  --datasets-root ./datasets_hippie \
  --output ./embeddings.npz

The GitHub copy in the HIPPIE release is the source of truth; keep the two in sync when making changes.

Preprocessing reference

The model expects each modality to be min-max normalized to [-1, 1] and resampled to the canonical lengths (waveform: 50, ISI: 100, ACG: 100). ISI is additionally log(x+1)-transformed before normalization. The MultiModalEphysDataset in hippie/dataloading.py is the canonical implementation; the snippet below reproduces it for the waveform case:

import numpy as np
import torch
import torch.nn.functional as F

def preprocess_waveform(raw: np.ndarray, wave_len: int = 50) -> np.ndarray:
    t = torch.as_tensor(raw, dtype=torch.float32)
    if t.dim() == 1:
        t = t.unsqueeze(0)
    if t.shape[-1] != wave_len:
        t = F.interpolate(t.unsqueeze(1), size=(wave_len,),
                          mode="linear", align_corners=False).squeeze(1)
    mn = t.amin(dim=-1, keepdim=True)
    mx = t.amax(dim=-1, keepdim=True)
    return ((t - mn) / (mx - mn + 1e-8) * 2.0 - 1.0).numpy().astype(np.float32)

Fine-tune on a new dataset

# Requires the HIPPIE release (cross_dataset_script.py)
python cross_dataset_script.py \
  --training-dataset YOUR_DATASET \
  --pretrain-checkpoint ./hippie_techcond_v1.ckpt \
  --config class_decoder_source_bn_aug_reg \
  --z_dim 30 --beta 1.0

---

Artifacts in this repo

To download just the checkpoint programmatically, use the HuggingFace Hub:

from huggingface_hub import hf_hub_download

ckpt_path = hf_hub_download(repo_id="Jesusgf23/hippie", filename="hippie_techcond_v1.ckpt")

extract_embeddings.py already does this automatically when no local --checkpoint is supplied.

---

Evaluation

Headline benchmark results (balanced accuracy, KNN probe on the latent embeddings) are reported in the manuscript. The exact commands and configurations that produced each figure are bundled with the benchmarking release at https://github.com/JesusGF1/HIPPIE-benchmarking-release.

---

Citation

If you use this model, please cite:

@article{gonzalez-ferrer2025hippie,
  title   = {HIPPIE: A Generative Model for Electrophysiological Analysis
             Across Species, Technologies, and Modalities},
  author  = {Gonzalez-Ferrer, Jesus and Lehrer, Julian and
             Alvarez-Esteban, Bruno and Schweiger, Hunter E. and
             Geng, Jinghui and Eugenio dos Santos, Luiz F. S. and
             Moreno-Ochando, Avelina and Hernandez, Sebastian and
             Reyes, Francisco and Sevetson, Jess L. and
             Schneider, Aidan and Salama, Sofie R. and
             Teodorescu, Mircea and Haussler, David and
             Mostajo-Radji, Mohammed A.},
  year    = {2025},
  note    = {Under revision at Nature Communications}
}

---

License

Apache 2.0. See LICENSE for details.

The released hippie Python package source code is maintained separately in the user-facing GitHub repository (https://github.com/braingeneers/HIPPIE).

---

Contact

• Mohammed A. Mostajo-Radji (corresponding author): [email protected]
• Jesus Gonzalez-Ferrer (maintainer): [email protected]

For code, issues, and the reproduction pipeline, see:

• User-facing repository: https://github.com/braingeneers/HIPPIE
• Benchmarking / reproduction: https://github.com/JesusGF1/HIPPIE-benchmarking-release