axonforge

A small Python toolkit for analysing extracellular electrophysiology recordings: threshold detection, waveform alignment, feature-based sorting, cluster quality metrics and interspike interval statistics.

axonforge is built for the situation most laboratories are actually in - 16 to 64 channels, recordings of minutes to an hour, stored as plain binary or HDF5, and an analysis that has to be explainable to a reviewer. Every default is written down on the methods page, every parameter is a keyword argument, and nothing is estimated behind your back.

It is not a replacement for the large sorting frameworks used on high-density probes with hundreds of channels. Those solve a harder problem - drift, dense spatial overlap, template matching - and they solve it better. What axonforge offers instead is a short, readable path from a file to a spike table you can defend line by line.

Minimal example#

Thirty-two channels of int16 at 30 kHz, from raw file to sorted units:

import axonforge as af

rec = af.io.read("session12.dat", fs=30_000, n_channels=32, dtype="int16")
rec = af.filt.common_median(rec)                  # reference across channels
rec = af.filt.bandpass(rec)                       # 300-6000 Hz, order 4

spikes = af.detect.threshold(rec, k=4.5, polarity="neg", dead_time_ms=1.0)
wf = af.waveform.extract(rec, spikes, pre_ms=0.5, post_ms=1.5)
wf = af.waveform.align(wf, mode="peak", interp=True)

feat  = af.sort.features(wf, n_components=3)
units = af.sort.cluster(feat, max_k=8, criterion="bic")

print(units.n_units)                              # 7
print(units.quality("isi_violations", refractory_ms=1.5))

The same sequence is available as a command, which is what most people use for a first look at a session:

axonforge detect session12.dat --fs 30000 --channels 32 \
    --bandpass 300:6000 --k 4.5 --out session12.afz
axonforge report session12.afz --raster --isi

The tutorial walks through this with the intermediate results shown at each step, including the raster plot it ends with.

What it does#

• Reads interleaved binary, HDF5 datasets, NumPy arrays and its own compressed container - the full list with limitations is on the formats page.
• Filters: zero-phase Butterworth bandpass, common median referencing by channel group.
• Detection: robust threshold at k times a median-based noise estimate, with an enforced dead time.
• Waveforms: extraction windows in milliseconds, alignment on peak or on steepest slope, with optional sub-sample parabolic interpolation.
• Sorting: principal components of aligned waveforms, Gaussian mixture clustering with model order chosen by an information criterion.
• Quality: interspike interval violations, L-ratio, isolation distance, presence ratio.
• Statistics: interval histograms, coefficient of variation, local variation, Fano factor, autocorrelograms, interval-threshold burst detection.

What it does not do#

• No drift correction. If your units move across the probe over the session, the clusters will smear and axonforge will not notice.
• No template matching, so overlapping spikes closer than roughly 0.3 ms are missed rather than resolved. This is measured, not assumed - see validation.
• No graphical interface for manual curation. Cluster merging is a function call on a spike table, and curation decisions are yours to record.
• No real-time or closed-loop operation; the file is read from disk.
• No support for acquisition-system native formats. Convert to one of the supported layouts first.

Where to go next#

• Installation - versions, extras, and how to check that the install works.
• Methods - the arithmetic behind the threshold and the alignment, and where each one fails.
• Validation - precision and recall against synthetic ground truth at five noise levels.
• Citing axonforge - what to put in a paper, and the licence.