Skip to main content

Lite vs full install

ibleatools has two install variants. Lite, the default, is the one ibl-alignment-gui depends on: it leaves out DARTsort and the spike-sorting stack, which make the full install much longer.

Which do you need?

pip install -e .            # lite — the default
pip install -e ".[full]"    # full
You want to Install
Run a published model on existing features lite
Compute lf / csd / ap features lite
Aggregate and denoise features lite
Download the IBL atlas aggregates lite
Run the encoders and the probe transformer lite
Compute waveforms (spike) features full
Read NWB or SpikeInterface-Zarr recordings full
Run the SDSC supercomputing pipeline full

If in doubt, start lite. It covers the whole tutorial and every published model.

pip install ibleatools[lite] also works — lite is an explicit empty alias, so that dependency line is valid, but it adds nothing over the base install. It exists because ibl-alignment-gui depends on ibleatools[lite] and wanted to name its intent.

Both variants require Python 3.12 or newer.

What lite includes

Lite installs:

package for
ibllib, ibl-neuropixel ≥ 1.14 ONE API, ibldsp destriping and waveform measures, spikeglx readers
iblatlas ≥ 1.2 Brain regions, atlas volumes, genomics (the denoised MERFISH context)
xgboost The region classifier
torch The encoders and the probe transformer
specparam Spectral-parameterisation features
scikit-image Total-variation denoising
scikit-learn Feature preprocessing steps (per-feature transforms, denoising), scaling and PCA
pandera, pydantic Schema validation and typed parameters
huggingface_hub Model download
lfpack ≥ 1.0 Reading compressed LFP archives (release v04)

What full adds

package for
dartsort ≥ 0.5.25, hdbscan, linear-operator, opt-einsum, h5py ≥ 3.15.1 Spike detection and waveform features
spikeinterface The NWB and Zarr calculators
pynwb, hdmf-zarr, remfile, fsspec, aiohttp, dandi Reading NWB, locally or streamed
luigi, iblscripts The SDSC supercomputing pipeline
ipykernel A Jupyter kernel for the environment

Why the split exists

There are three reasons:

DARTsort is a heavy tree. Spike detection needs dartsort, which pulls spikeinterface, hdbscan, linear-operator, dredge-ephys and a recent h5py. Most users of the region decoder never compute waveform features themselves — they consume published features or compute the cheap LF families — and should not pay that install cost.

Version floors are contagious. The full extra needs h5py>=3.15.1 to avoid a DARTsort failure in the unit tests, and DARTsort’s own floors move with each release. Every such constraint narrows what else the environment can hold, so confining them to an opt-in extra keeps the base install resolvable alongside other packages.

The GUI depends on lite. ibl-alignment-gui requires ibleatools for model inference and LF feature computation. Making the base install lite is what lets the GUI depend on it without dragging in a spike-sorting stack.

Lazy imports make the split work

The optional dependencies are imported inside the functions that need them, not at module scope. So import ephysatlas.feature_calculators succeeds on a lite install even though NwbFeatureCalculator cannot open a recording there — the failure arrives only when you try to use it, and says exactly what to install:

NWB feature computation needs the optional NWB/streaming dependencies
(spikeinterface, pynwb, hdmf-zarr, remfile, dandi).
Install them with `pip install ibleatools[full]`.

The same applies to specparam in features.lf(), lfpack in read_lfp_features, and DARTsort in the spike path.

The xgboost / torch segfault

The order in which torch is imported matters, both inside the package and in your own scripts.

On macOS arm64, loading torch in a process that has already imported xgboost can segfault. ephysatlas.regionclassifier imports xgboost at module scope, so import ephysatlas loads neither library, and the torch models are only imported inside the functions that load them (see model families).

If you hit a SEGFAULT during feature computation, it is likely the same kind of clash: pytorch#132372 reports it on macOS arm64 when scikit-learn is imported before torch, which is the order in the feature code. Two workarounds — import torch first, before anything else:

import torch  # noqa: F401  — must come before the ephysatlas imports

or point the dynamic loader at your environment’s torch libraries:

export DYLD_LIBRARY_PATH=/path/to/venv/lib/python3.12/site-packages/torch/lib

Development installs

The repository uses uv with three dependency groups:

uv sync                                  # lite
uv sync --extra full --group test        # what CI runs
uv sync --group docs                     # to build this site
uv sync --group lint                     # ruff

CI runs uv sync --extra full --group test --group lint on Python 3.12, then ruff check, ruff format --check and the unittest suite with coverage.

See also