You can deploy this model and start earning money today!

Jesusgf23/
hippie

Name: hippie
Availability: InStock

neuroscience

electrophysiology

cell-type-classification

variational-autoencoder

Views

No views yet

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

Property	Value
Architecture	Conditional VAE (1D ResNet18 encoders, MLP fusion, per-modality decoders)
Latent dimension	30 (10 per modality across 3 modalities)
KL weight (β)	1.0
Input modalities	Waveform (50 samples), ISI (100 bins), ACG (100 bins)
Conditioning	3-class recording-technology embedding (dim=5)
Pretraining datasets	11 (see below)
Framework	PyTorch + PyTorch Lightning
Checkpoint format	PyTorch `.ckpt` (Lightning state dict)
Checkpoint file	`hippie_techcond_v1.ckpt`
Version	`hippie_techcond_v1`
License	Apache-2.0

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.

Dataset	Identifier	Species / Region	Technology	Sample size
Hausser (Beau et al. 2024, C4)	`hausser_cell_type`	Mouse cerebellar cortex	Neuropixels 1.0	1,998 total / 113 labeled (6 types)
Hull (Beau et al. 2024, C4)	`hull_cell_type`	Mouse cerebellar cortex	Neuropixels 1.0	103 labeled (5 types)
Lisberger (Beau et al. 2024, C4)	`lisberger_labeled_cell_type`	Macaque cerebellar floccular complex	16-ch Plexon silicon s-Probe	1,152 total / 668 labeled (5 types)
CellExplorer (Petersen et al. 2021)	`cellexplorer_cell_type`	Mouse visual cortex / hippocampus	Neuropixels 1.0	430 neurons (7 classes)
IBL Brainwide Map	`ibl_brainwide_good`	Mouse whole-brain (10 Cosmos regions)	Neuropixels	62,993 neurons / 139 subjects
Allen Visual Coding	`allen_scope_neuropixel_area_subset`	Mouse cortex / hippocampus / thalamus (19 CCF regions)	Neuropixels	61,781 neurons / 47 mice
Watson (DANDI 000041)	`dandi_000041_cell_type`	Rat frontal cortex	64-site silicon probe	221 neurons (2 classes)
Calvigioni (DANDI 000473)	`dandi_000473_cell_type`	Mouse prefrontal cortex	Neuropixels	9,213 neurons (2 classes)
Ramachandran (DANDI 000955)	`dandi_000955_cell_type`	Rat somatosensory cortex	32-ch NeuroNexus electrode	134 neurons (2 classes)
A1 (Lakunina et al. 2020)	`a1data_remove_undef`	Mouse auditory cortex	Silicon probe	285 neurons (3 classes)
Juxtacellular S1 (Yu et al. 2019)	`juxtacellular_mouse_s1_area`	Mouse barrel cortex	Juxtasomal glass micropipette	224 neurons (5 classes)

Technology Conditioning Vocabulary

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

ID	Label	Datasets that used this slot during pretraining
0	`neuropixels`	Hausser, Hull, CellExplorer, IBL, Allen, Calvigioni (DANDI 000473)
1	`silicon_probe`	Lisberger, Watson (DANDI 000041), Ramachandran (DANDI 000955), A1
2	`juxtacellular`	Juxtacellular Mouse S1

Installation

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

bash

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

python

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

python

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

python

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:

bash

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:

python

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

bash

# 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

File	Description
`hippie_techcond_v1.ckpt`	PyTorch Lightning checkpoint (technology-conditioned)
`embeddings.npz`	Precomputed 30-D embeddings for all 11 labeled datasets
`umap_coords.npz`	2-D UMAP projection of the embeddings
`umap_by_dataset.png`	UMAP scatter colored by dataset
`extract_embeddings.py`	Script that reproduces `embeddings.npz` from the checkpoint

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

python

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:

bibtex

@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): mmostajo@ucsc.edu
Jesus Gonzalez-Ferrer (maintainer): jgonz373@ucsc.edu

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