ibl_alignment_gui.core.ephys_alignment

Geometric alignment between electrophysiology features and a histology track.

An EphysAlignment maps positions along a probe (the electrophysiology “feature” space the user sees) onto 3D brain coordinates, warping between the two using a set of user-placed reference lines.

Two 1D spaces are used throughout:

• feature space: depth along the ephys plots the user annotates (metres).

• track space: depth along the reconstructed histology track (metres).

EphysAlignment.feature2track() and EphysAlignment.track2feature() interpolate between these spaces using the reference lines, and points in track space are turned into 3D coordinates by interpolating along xyz_track.

Coordinate convention

All xyz coordinates are in the atlas RAS frame – (x, y, z) = (Right, Anterior, Superior) – expressed in metres.

Functions

_cumulative_distance	Cumulative Euclidean distance along a sequence of points.
interpolate_along_track	Get the xyz coordinates of points a given distance along a track.

Classes

EphysAlignment

Align electrophysiology features to a reconstructed histology track.

class ibl_alignment_gui.core.ephys_alignment.EphysAlignment(xyz_picks, chn_depths=None, track_prev=None, feature_prev=None, brain_atlas=None, speedy=False, track_margin_m=0.006)

Bases: object

Align electrophysiology features to a reconstructed histology track.

See the module docstring for the feature-space / track-space convention. All xyz coordinates refer to RAS convention (metres).

__init__(xyz_picks, chn_depths=None, track_prev=None, feature_prev=None, brain_atlas=None, speedy=False, track_margin_m=0.006)

Set up the alignment from the user-picked trajectory.

Builds the full insertion track from the picks, initialises the feature/track reference points (either from a previous alignment or as an identity mapping sized to the probe), samples the track through the atlas, and precomputes the histology regions the track passes through.

Parameters:

• xyz_picks (np.ndarray) – User-picked xyz coordinates defining the probe trajectory.

• chn_depths (np.ndarray or None) – Channel depths along the probe (um). Used to size the initial track range.

• track_prev (np.ndarray or None) – Track reference points from a previous alignment, if resuming one.

• feature_prev (np.ndarray or None) – Feature reference points from a previous alignment, if resuming one.

• brain_atlas (BrainAtlas or None) – Atlas used for coordinate and region lookups. Defaults to AllenAtlas(25).

• speedy (bool) – If True, estimate the brain exit from the atlas z-limits instead of the (slower) brain-surface intersection.

• track_margin_m (float) – Default half-range (m) for the initial track when no channel or previous alignment information is available.

adjust_extremes_linear(feature, track, extend_feature=1)

Adjust the outermost reference points with a linear fit.

Extends the first and last feature points by extend_feature and sets the matching track points from a linear fit, so coordinates outside the user-picked span are scaled linearly rather than left unchanged.

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

• extend_feature (float) – Amount to extend the extreme feature coordinates before fitting.

Return type:

tuple[ndarray, ndarray]

Returns:

• feature (np.ndarray) – Feature reference points with the first and last values adjusted.

• track (np.ndarray) – Track reference points with the first and last values adjusted.

static adjust_extremes_uniform(feature, track)

Adjust the outermost (non user-chosen) track points with a uniform shift.

Shifts the first and last track points so that coordinates outside the user-picked span keep the same feature-to-track offset (no scaling).

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

Track reference points with the first and last values adjusted.

Return type:

np.ndarray

static arrange_into_regions(depth_coords, region_ids, distance, region_colours)

Reshape get_nearest_boundary output for plotting with pyqtgraph or matplotlib.

Groups consecutive samples of the same region into per-region polylines of depth vs distance, padded so each region draws as a closed shape.

Parameters:

• depth_coords (np.ndarray) – Depth along the probe or track for each point.

• region_ids (np.ndarray) – Brain region id at each depth.

• distance (np.ndarray) – Distance to the nearest boundary at each point.

• region_colours (list of str) – Allen atlas hex colour for each point’s region.

Return type:

tuple[list[ndarray], list[ndarray], list[str]]

Returns:

• all_x (list of np.ndarray) – Distance values for each region along the track.

• all_y (list of np.ndarray) – Depth values for each region along the track.

• all_colour (list of str) – Colour assigned to each region along the track.

static feature2track(feature_new, feature_ref, track_ref)

Convert feature-space points to track space via the reference-line fit.

Builds a linear interpolant from the (feature_ref, track_ref) reference pairs and evaluates it, extrapolating beyond the outermost reference lines.

Parameters:

• feature_new (np.ndarray) – Points in feature space to convert to track space.

• feature_ref (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track_ref (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

Corresponding values in track space.

Return type:

np.ndarray

static feature2track_lin(feature_new, feature_ref, track_ref)

Linear-fit version of feature2track, used for the extreme reference points.

Fits a straight line to the interior (user-chosen) reference points and evaluates it. Only applied when there are at least three user reference lines (feature_ref.size >= 5, i.e. 3 lines plus the 2 extreme points); otherwise returns 0.

Parameters:

• feature_new (np.ndarray) – Points in feature space to convert to track space.

• feature_ref (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track_ref (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

Linear-fit values of feature_new, or 0 if there are too few reference points.

Return type:

np.ndarray or int

get_brain_locations(xyz_channels)

Find the brain regions at a set of 3D electrode locations.

Parameters:

xyz_channels (np.ndarray) – xyz coordinates of the electrodes.

Returns:

Brain region information for each electrode.

Return type:

Bunch

get_channel_locations(feature, track, depths=None)

Get the 3D xyz coordinates of points along the ephys feature axis.

Two interpolation steps:

1. feature space -> track space, using the reference-line fit.

2. track space -> 3D xyz (RAS) coordinates, by interpolating along xyz_track.

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

• depths (np.ndarray or None) – Feature-space depths to locate (m). Defaults to the channel depths.

Returns:

xyz coordinates for each depth.

Return type:

np.ndarray

static get_histology_regions(xyz_coords, depth_coords, brain_atlas=None, mapping=None)

Find the brain regions and their boundaries along the depth of a probe or track.

Looks up the atlas label at each sampled coordinate and groups consecutive samples with the same region id into contiguous boundaries.

Parameters:

• xyz_coords (np.ndarray) – xyz coordinates of points along the probe or track.

• depth_coords (np.ndarray) – Depth along the probe or track for each xyz coordinate.

• brain_atlas (BrainAtlas or None) – Atlas used for the label lookup. Defaults to AllenAtlas(25).

• mapping (str or None) – Optional region mapping passed to the atlas label lookup.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

• region (np.ndarray) – Depth coordinates bounding each brain region.

• region_label (np.ndarray) – Label position (depth) and acronym for each region.

• region_colour (np.ndarray) – Allen atlas RGB colour for each region.

• region_id (np.ndarray) – Allen atlas id for each region.

Raises:

ValueError – If xyz_coords is empty, not an (n, 3) array, or contains non-finite values.

get_insertion_track(xyz_picks, speedy=False)

Extend the probe trajectory from the bottom of the brain to the top of the atlas.

Fits a line to the first and last portions of the picks and extrapolates to the brain exit (bottom) and the top of the atlas (entry), so the track spans the full atlas even when channels sit above the brain surface.

Parameters:

• xyz_picks (np.ndarray) – xyz coordinates defining the probe trajectory.

• speedy (bool) – If True, estimate the brain exit from the atlas z-limits instead of the (slower) brain-surface intersection.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

• xyz_track (np.ndarray) – xyz coordinates of the extended trajectory, sorted so the most ventral (deepest) point is first.

• track_extent (np.ndarray) – Distance to the deepest and shallowest points of the track, offset so that 0 is at the first electrode.

• cumulative_dist (np.ndarray) – Cumulative distance along xyz_track from the deepest point.

static get_nearest_boundary(xyz_coords, allen, extent=100, steps=8, parent=True, brain_atlas=None)

Find the distance to the closest neighbouring brain region along the trajectory.

For each point in xyz_coords, samples a plane through the point perpendicular to the trajectory and finds the nearest sampled point that lies in a different region, giving the distance to the nearest region boundary. Optionally repeats the calculation for the parent regions.

Parameters:

• xyz_coords (np.ndarray) – xyz coordinates of points along the probe or track.

• allen (pd.DataFrame) – Allen structure tree, loaded from allen_structure_tree in iblatlas.

• extent (float) – Half-extent of the sampling plane in each direction from the point (um).

• steps (int) – Number of steps used to discretise the plane.

• parent (bool) – If True, also compute the nearest-boundary distance between parent regions.

• brain_atlas (BrainAtlas or None) – Atlas used for the label lookup. Defaults to AllenAtlas(25).

Returns:

Nearest-boundary results, with keys dist, id and col (and the parent_* equivalents when parent is True).

Return type:

dict

get_perp_vector(feature, track)

Find the lines perpendicular to the trajectory at each reference line.

For each user reference line, computes a short segment perpendicular to the local trajectory direction, used to draw the slice location.

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

Array of endpoint xyz coordinates per reference line.

Return type:

list of np.ndarray

get_scale_factor(region, region_orig=None)

Find how much each brain region has been scaled by the alignment.

Compares the scaled region boundaries against the original ones and groups consecutive regions that share the same scale factor.

Parameters:

• region (np.ndarray) – Scaled histology boundaries.

• region_orig (np.ndarray or None) – Original histology boundaries. Defaults to self.region.

Return type:

tuple[ndarray, ndarray]

Returns:

• scaled_region (np.ndarray) – Regions that share a common scale factor.

• scale_factor (np.ndarray) – Scale factor applied to each region.

get_tip_location(feature, track)

Get the 3D xyz coordinates of the probe tip.

The tip is TIP_SIZE_UM below the first electrode. Uses the same feature-to-track transform as the channels, so the tip position updates dynamically as the alignment is adjusted.

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

xyz coordinates of the tip.

Return type:

np.ndarray

get_track_and_feature()

Return the current feature, track and xyz_track arrays.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

• feature_init (np.ndarray) – Initial feature-space reference points.

• track_init (np.ndarray) – Initial track-space reference points.

• xyz_track (np.ndarray) – xyz coordinates of the extended trajectory.

scale_histology_regions(feature, track, region=None, region_label=None)

Recompute histology region boundaries in feature space from the reference fit.

Maps the stored track-space region boundaries (and their label positions) into feature space so they can be displayed against the ephys plots.

Parameters:

• feature (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track (np.ndarray) – Reference coordinates in track space (histology track).

• region (np.ndarray or None) – Region boundaries to scale. Defaults to self.region.

• region_label (np.ndarray or None) – Label positions and acronyms to scale. Defaults to self.region_label.

Return type:

tuple[ndarray, ndarray]

Returns:

• region (np.ndarray) – Region boundaries in feature space (um).

• region_label (np.ndarray) – Label positions (um) and acronyms.

static track2feature(track_new, feature_ref, track_ref)

Convert track-space points to feature space via the reference-line fit.

Builds a linear interpolant from the (track_ref, feature_ref) reference pairs and evaluates it, extrapolating beyond the outermost reference lines.

Parameters:

• track_new (np.ndarray) – Points in track space to convert to feature space.

• feature_ref (np.ndarray) – Reference coordinates in feature space (ephys plots).

• track_ref (np.ndarray) – Reference coordinates in track space (histology track).

Returns:

Corresponding values in feature space.

Return type:

np.ndarray

ibl_alignment_gui.core.ephys_alignment.interpolate_along_track(xyz_track, depths)

Get the xyz coordinates of points a given distance along a track.

Walks along the piecewise-linear track and linearly interpolates a 3D position for each requested distance, measured from the first (usually deepest) point.

Parameters:

• xyz_track (np.ndarray) – xyz coordinates defining the track; the first point is usually the deepest.

• depths (np.ndarray) – (n_depths,) distances from the first point of the track, by convention 0 at the deepest point and increasing towards the surface.

Returns:

Interpolated xyz coordinates.

Return type:

np.ndarray