Data Preparation

This section describes how to prepare your data for use with the IBL Alignment GUI.

The GUI requires:

• Spike-sorted electrophysiology data in the phylib format

• Extracted raw electrophysiology features

• Probe trajectory coordinates in the brain atlas

Preparing Electrophysiology Data

The IBL Alignment GUI requires spike-sorted data in the phylib format, along with extracted raw electrophysiology features computed from the AP and LFP data.

Using SpikeGLX and Kilosort

If you recorded data using SpikeGLX and spike-sorted using Kilosort or pykilosort, use the following code to convert your data and extract the necessary features:

from pathlib import Path
from ibl_alignment_gui.convertors import extract_ephys

# Path to Kilosort output
ks_path = Path('/path/to/kilosort/output')

# Path to raw ephys data
ephys_path = Path('/path/to/raw/ephys/data')

# Output path
out_path = Path('/path/to/output')

extract_ephys(ks_path, ephys_path, out_path)

Warning

Ensure the output path is not the same as the Kilosort path to avoid overwriting existing files.

Using Other Recording or Spike Sorting Software

If you recorded data using OpenEphys or spike-sorted using other software, we recommend using SpikeInterface to convert your data to the phylib format.

SpikeInterface provides a specific converter to export a SpikeSortingAnalyzer to the format required by the IBL Alignment GUI:

• SpikeInterface documentation

• IBL exporter module

Preparing Trajectory Data

The IBL Alignment GUI requires the location of the probe trajectory in the brain atlas. This is typically obtained via probe track reconstruction from histology images.

Available Tools

There are several tools available for probe track reconstruction:

• BrainRegister

• Lasagna

• SHARP-Track

• Herbs

Probe Tracing Using brainreg-segment

brainreg and brainreg-segment are tools for registering histology image stacks and tracing probe locations in the brain.

Tutorial: See the brainreg-segment tutorial for detailed instructions.

Important notes:

Aspect	Details
Tracing space	Must be done in registered atlas space (not original sample space)
Spline points	Reduce to < 100 when fitting the track
Export	Click Export to brainrender to output the .npy coordinate file

Converting brainreg output to GUI format:

import numpy as np
from pathlib import Path
import json
from iblatlas.atlas import AllenAtlas

atlas = AllenAtlas(25)

# Path to brainreg track output
brainreg_path = Path('/path/to/brainreg/output/tracks/track_1.npy')

# Load coordinates in CCF space (order: apdvml, origin: top-left-front voxel)
xyz_apdvml = np.load(brainreg_path)

# Convert to IBL space (order: mlapdv, origin: bregma)
xyz_mlapdv = atlas.ccf2xyz(xyz_apdvml, ccf_order='apdvml') * 1e6

xyz_picks = {'xyz_picks': xyz_mlapdv.tolist()}

# Save to output directory
output_path = Path('/path/to/output')
with open(output_path / 'xyz_picks.json', 'w') as f:
    json.dump(xyz_picks, f, indent=2)

Probe Tracing Using Lasagna

Lasagna is another tool for tracing probe tracks in histology images registered to the Allen atlas.

Tutorial: See the Lasagna probe tracing guide for instructions.

Important notes:

Aspect	Details
Image transformations	Do not apply rotations, flips, or mirrors when tracing
Tracing space	Trace in histology already registered to Allen atlas, or apply registration transform if tracing in original space
Output line	Save the _pts line, not the _fit line

Converting Lasagna output to GUI format:

from ibllib.pipes.histology import load_track_csv
from pathlib import Path
import json

# Path to Lasagna tracing output
file_track = '/path/to/lasagna/tracing_pts.csv'

# Load and convert coordinates
xyz = load_track_csv(file_track) * 1e6
xyz_picks = {'xyz_picks': xyz.tolist()}

# Save to output directory
output_path = Path('/path/to/output')
with open(output_path / 'xyz_picks.json', 'w') as f:
    json.dump(xyz_picks, f, indent=2)

Coordinate Systems

The IBL Alignment GUI uses coordinates relative to bregma with the following convention:

Axis	Description
x	Medial-lateral (ML)
y	Anterior-posterior (AP)
z	Dorsal-ventral (DV)

Bregma is defined at:

• ML = 5739 μm

• AP = 5400 μm

• DV = 332 μm

from the front-top-left corner (from the mouse’s point of view) of the Allen CCF data volume.

Coordinate Transformations

If you have probe tracks in the Allen CCF coordinate framework, use the following code to transform between coordinate systems:

CCF to Bregma (mlapdv order):

from iblatlas.atlas import AllenAtlas
import numpy as np

# Initialize atlas (25 μm resolution)
brain_atlas = AllenAtlas(25)

# Example coordinates in μm with CCF origin
ccf_mlapdv = np.array([[3000, 4000, 3000], [6000, 6000, 500]], dtype=float)

# Transform to Bregma origin
bregma_mlapdv = brain_atlas.ccf2xyz(ccf_mlapdv, ccf_order='mlapdv')

CCF to Bregma (apdvml order):

# Example coordinates in μm with CCF origin (apdvml order)
ccf_apdvml = np.array([[3000, 4000, 3000], [6000, 6000, 500]], dtype=float)

# Transform to Bregma origin (output in mlapdv order)
bregma_mlapdv = brain_atlas.ccf2xyz(ccf_apdvml, ccf_order='apdvml')

Bregma to CCF (mlapdv order):

# Example coordinates in m with Bregma origin
bregma_mlapdv = np.array([[2000, 4000, 0], [4000, -1000, -4000]]) / 1e6

# Transform to CCF origin
ccf_mlapdv = brain_atlas.xyz2ccf(bregma_mlapdv, ccf_order='mlapdv')

Bregma to CCF (apdvml order):

# Example coordinates in m with Bregma origin
bregma_mlapdv = np.array([[2000, 4000, 0], [4000, -1000, -4000]]) / 1e6

# Transform to CCF origin (apdvml order)
ccf_apdvml = brain_atlas.xyz2ccf(bregma_mlapdv, ccf_order='apdvml')