ibllib.atlas.atlas

Functions

MRITorontoAtlas	Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system.
NeedlesAtlas	Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system.
cart2sph	Converts cartesian to spherical Coordinates theta: polar angle, phi: azimuth
sph2cart	Converts Spherical to Cartesian coordinates theta: polar angle, phi: azimuth

Classes

AllenAtlas	Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system
BrainAtlas	Objects that holds image, labels and coordinate transforms for a brain Atlas.
BrainCoordinates	Class for mapping and indexing a 3D array to real-world coordinates x = ml, right positive y = ap, anterior positive z = dv, dorsal positive
FlatMap
FranklinPaxinosAtlas	Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system
Insertion	Defines an ephys probe insertion in 3D coordinate.
Trajectory	3D Trajectory (usually for a linear probe). Minimally defined by a vector and a point. instantiate from a best fit from a n by 3 array containing xyz coordinates: trj = Trajectory.fit(xyz).

cart2sph(x, y, z)

Converts cartesian to spherical Coordinates theta: polar angle, phi: azimuth

sph2cart(r, theta, phi)

Converts Spherical to Cartesian coordinates theta: polar angle, phi: azimuth

class BrainCoordinates(nxyz, xyz0=[0, 0, 0], dxyz=[1, 1, 1])

Bases: object

Class for mapping and indexing a 3D array to real-world coordinates x = ml, right positive y = ap, anterior positive z = dv, dorsal positive

The layout of the Atlas dimension is done according to the most used sections so they lay contiguous on disk assuming C-ordering: V[iap, iml, idv]

nxyz: number of elements along each cartesian axis (nx, ny, nz) = (nml, nap, ndv) xyz0: coordinates of the element volume[0, 0, 0]] in the coordinate space dxyz: spatial interval of the volume along the 3 dimensions

property dxyz

property nxyz

r2ix(r)

r2iy(r)

r2iz(r)

x2i(x, round=True, mode='raise')

y2i(y, round=True, mode='raise')

z2i(z, round=True, mode='raise')

xyz2i(xyz, round=True, mode='raise')

Parameters

mode – {‘raise’, ‘clip’, ‘wrap’} determines what to do when determined index lies outside the atlas volume ‘raise’ will raise a ValueError ‘clip’ will replace the index with the closest index inside the volume ‘wrap’ will wrap around to the other side of the volume. This is only here for legacy reasons

i2x(ind)

i2y(ind)

i2z(ind)

i2xyz(iii)

property xlim

property ylim

property zlim

lim(axis)

property xscale

property yscale

property zscale

property mgrid

class BrainAtlas(image, label, dxyz, regions, iorigin=[0, 0, 0], dims2xyz=[0, 1, 2], xyz2dims=[0, 1, 2])

Bases: object

Objects that holds image, labels and coordinate transforms for a brain Atlas. Currently this is designed for the AllenCCF at several resolutions, yet this class can be used for other atlases arises.

compute_surface()

Get the volume top, bottom, left and right surfaces, and from these the outer surface of the image volume. This is needed to compute probe insertions intersections.

NOTE: In places where the top or bottom surface touch the top or bottom of the atlas volume, the surface will be set to np.nan. If you encounter issues working with these surfaces check if this might be the cause.

get_labels(xyz, mapping=None, radius_um=None, mode='raise')

Performs a 3D lookup from real world coordinates to the volume labels and return the regions ids according to the mapping

Parameters

• xyz – [n, 3] array of coordinates

• mapping – brain region mapping (defaults to original Allen mapping)

• radius_um – if not null, returns a regions ids array and an array of proportion of regions in a sphere of size radius around the coordinates.

Returns

n array of region ids

tilted_slice(xyz, axis, volume='image')

From line coordinates, extracts the tilted plane containing the line from the 3D volume

Parameters

xyz – np.array: points defining a probe trajectory in 3D space (xyz triplets)

if more than 2 points are provided will take the best fit :param axis:

0: along ml = sagittal-slice 1: along ap = coronal-slice 2: along dv = horizontal-slice

Parameters

volume – ‘image’ or ‘annotation’

Returns

np.array, abscissa extent (width), ordinate extent (height),

squeezed axis extent (depth)

plot_tilted_slice(xyz, axis, volume='image', cmap=None, ax=None, sec_ax=False, **kwargs)

From line coordinates, extracts the tilted plane containing the line from the 3D volume

Parameters

xyz – np.array: points defining a probe trajectory in 3D space (xyz triplets)

if more than 2 points are provided will take the best fit :param axis:

0: along ml = sagittal-slice 1: along ap = coronal-slice 2: along dv = horizontal-slice

Parameters

volume – ‘image’ or ‘annotation’

Returns

matplotlib axis

extent(axis)

Parameters

axis – direction along which the volume is stacked: (2 = z for horizontal slice) (1 = y for coronal slice) (0 = x for sagittal slice)

Returns

slice(coordinate, axis, volume='image', mode='raise', region_values=None, mapping=None, bc=None)

Get slice through atlas

Parameters

• coordinate – coordinate to slice in metres, float

• axis – xyz convention: 0 for ml, 1 for ap, 2 for dv - 0: sagittal slice (along ml axis) - 1: coronal slice (along ap axis) - 2: horizontal slice (along dv axis)

• volume –

  • ‘image’ - allen image volume

  • ’annotation’ - allen annotation volume

  • ’surface’ - outer surface of mesh

  • ’boundary’ - outline of boundaries between all regions

  • ’volume’ - custom volume, must pass in volume of shape ba.image.shape as regions_value argument

  • ’value’ - custom value per allen region, must pass in array of shape ba.regions.id as regions_value argument

• mode – error mode for out of bounds coordinates - ‘raise’ raise an error - ‘clip’ gets the first or last index

• region_values – custom values to plot - if volume=’volume’, region_values must have shape ba.image.shape - if volume=’value’, region_values must have shape ba.regions.id

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

Returns

2d array or 3d RGB numpy int8 array

compute_boundaries(values)

Compute the boundaries between regions on slice

Parameters

values –

Returns

plot_slices(xyz, *args, **kwargs)

From a single coordinate, plots the 3 slices that intersect at this point in a single matplotlib figure

Parameters

• xyz – mlapdv coordinate in m

• args – arguments to be forwarded to plot slices

• kwargs – keyword arguments to be forwarded to plot slices

Returns

2 by 2 array of axes

plot_cslice(ap_coordinate, volume='image', mapping=None, region_values=None, **kwargs)

Plot coronal slice through atlas at given ap_coordinate

Param

ap_coordinate (m)

Parameters

• volume –

  • ‘image’ - allen image volume

  • ’annotation’ - allen annotation volume

  • ’surface’ - outer surface of mesh

  • ’boundary’ - outline of boundaries between all regions

  • ’volume’ - custom volume, must pass in volume of shape ba.image.shape as regions_value argument

  • ’value’ - custom value per allen region, must pass in array of shape ba.regions.id as regions_value argument

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• region_values – custom values to plot - if volume=’volume’, region_values must have shape ba.image.shape - if volume=’value’, region_values must have shape ba.regions.id

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• **kwargs –

  matplotlib.pyplot.imshow kwarg arguments

Returns

matplotlib ax object

plot_hslice(dv_coordinate, volume='image', mapping=None, region_values=None, **kwargs)

Plot horizontal slice through atlas at given dv_coordinate

Param

dv_coordinate (m)

Parameters

• volume –

  • ‘image’ - allen image volume

  • ’annotation’ - allen annotation volume

  • ’surface’ - outer surface of mesh

  • ’boundary’ - outline of boundaries between all regions

  • ’volume’ - custom volume, must pass in volume of shape ba.image.shape as regions_value argument

  • ’value’ - custom value per allen region, must pass in array of shape ba.regions.id as regions_value argument

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• region_values – custom values to plot - if volume=’volume’, region_values must have shape ba.image.shape - if volume=’value’, region_values must have shape ba.regions.id

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• **kwargs –

  matplotlib.pyplot.imshow kwarg arguments

Returns

matplotlib ax object

plot_sslice(ml_coordinate, volume='image', mapping=None, region_values=None, **kwargs)

Plot sagittal slice through atlas at given ml_coordinate

Param

ml_coordinate (m)

Parameters

• volume –

  • ‘image’ - allen image volume

  • ’annotation’ - allen annotation volume

  • ’surface’ - outer surface of mesh

  • ’boundary’ - outline of boundaries between all regions

  • ’volume’ - custom volume, must pass in volume of shape ba.image.shape as regions_value argument

  • ’value’ - custom value per allen region, must pass in array of shape ba.regions.id as regions_value argument

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• region_values – custom values to plot - if volume=’volume’, region_values must have shape ba.image.shape - if volume=’value’, region_values must have shape ba.regions.id

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• **kwargs –

  matplotlib.pyplot.imshow kwarg arguments

Returns

matplotlib ax object

plot_top(volume='annotation', mapping=None, region_values=None, ax=None, **kwargs)

Plot top view of atlas

Parameters

• volume –

  • ‘image’ - allen image volume

  • ’annotation’ - allen annotation volume

  • ’boundary’ - outline of boundaries between all regions

  • ’volume’ - custom volume, must pass in volume of shape ba.image.shape as regions_value argument

  • ’value’ - custom value per allen region, must pass in array of shape ba.regions.id as regions_value argument

• mapping – mapping to use. Options can be found using ba.regions.mappings.keys()

• region_values –

• ax –

• kwargs –

Returns

class Trajectory(vector: ndarray, point: ndarray)

Bases: object

3D Trajectory (usually for a linear probe). Minimally defined by a vector and a point. instantiate from a best fit from a n by 3 array containing xyz coordinates:

trj = Trajectory.fit(xyz)

vector: ndarray

point: ndarray

static fit(xyz)

fits a line to a 3D cloud of points, returns a Trajectory object

Parameters

xyz – n by 3 numpy array containing cloud of points

Returns

a Trajectory object

eval_x(x)

given an array of x coordinates, returns the xyz array of coordinates along the insertion

Parameters

x – n by 1 or numpy array containing x-coordinates

Returns

n by 3 numpy array containing xyz-coordinates

eval_y(y)

given an array of y coordinates, returns the xyz array of coordinates along the insertion

Parameters

y – n by 1 or numpy array containing y-coordinates

Returns

n by 3 numpy array containing xyz-coordinates

eval_z(z)

given an array of z coordinates, returns the xyz array of coordinates along the insertion

Parameters

z – n by 1 or numpy array containing z-coordinates

Returns

n by 3 numpy array containing xyz-coordinates

project(point)

projects a point onto the trajectory line

Parameters

point – np.array(x, y, z) coordinates

Returns

mindist(xyz, bounds=None)

Computes the minimum distance to the trajectory line for one or a set of points. If bounds are provided, computes the minimum distance to the segment instead of an infinite line.

Parameters

• xyz – […, 3]

• bounds – defaults to None. np.array [2, 3]: segment boundaries, inf line if None

Returns

minimum distance […]

exit_points(bc)

Given a Trajectory and a BrainCoordinates object, computes the intersection of the trajectory with the brain coordinates bounding box

Parameters

bc – BrainCoordinate objects

Returns

np.ndarray 2 y 3 corresponding to exit points xyz coordinates

class Insertion(x: float, y: float, z: float, phi: float, theta: float, depth: float, label: str = '', beta: float = 0)

Bases: object

Defines an ephys probe insertion in 3D coordinate. IBL conventions. To instantiate, use the static methods: Insertion.from_track Insertion.from_dict

x: float

y: float

z: float

phi: float

theta: float

depth: float

label: str = ''

beta: float = 0

static from_track(xyzs, brain_atlas=None)

Parameters

brain_atlas – None. If provided, disregards the z coordinate and locks the insertion

point to the z of the brain surface :return: Trajectory object

static from_dict(d, brain_atlas=None)

Constructs an Insertion object from the json information stored in probes.description file

Parameters

• trj –

  dictionary containing at least the following keys, in um {

  ’x’: 544.0, ‘y’: 1285.0, ‘z’: 0.0, ‘phi’: 0.0, ‘theta’: 5.0, ‘depth’: 4501.0 }

• brain_atlas – None. If provided, disregards the z coordinate and locks the insertion

point to the z of the brain surface :return: Trajectory object

property trajectory

Gets the trajectory object matching insertion coordinates :return: atlas.Trajectory

property xyz

property entry

property tip

static get_brain_exit(traj, brain_atlas)

Given a Trajectory and a BrainAtlas object, computes the brain exit coordinate as the intersection of the trajectory and the brain surface (brain_atlas.surface)

Parameters

brain_atlas –

Returns

3 element array x,y,z

static get_brain_entry(traj, brain_atlas)

Given a Trajectory and a BrainAtlas object, computes the brain entry coordinate as the intersection of the trajectory and the brain surface (brain_atlas.surface)

Parameters

brain_atlas –

Returns

3 element array x,y,z

class AllenAtlas(res_um=25, scaling=array([1, 1, 1]), mock=False, hist_path=None)

Bases: BrainAtlas

Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system

xyz2ccf(xyz, ccf_order='mlapdv', mode='raise')

Converts coordinates to the CCF coordinates, which is assumed to be the cube indices times the spacing.

Parameters

• xyz – mlapdv coordinates in meters, origin Bregma

• ccf_order – order that you want values returned ‘mlapdv’ (ibl) or ‘apdvml’

(Allen mcc vertices) :param mode: {‘raise’, ‘clip’, ‘wrap’} determines what to do when determined index lies outside the atlas volume

‘raise’ will raise a ValueError ‘clip’ will replace the index with the closest index inside the volume ‘wrap’ will wrap around to the other side of the volume. This is only here for legacy reasons

Returns

coordinates in CCF space um, origin is the front left top corner of the data

volume, order determined by ccf_order

ccf2xyz(ccf, ccf_order='mlapdv')

Converts coordinates from the CCF coordinates, which is assumed to be the cube indices times the spacing.

:param ccf coordinates in CCF space in um, origin is the front left top corner of the data volume :param ccf_order: order of ccf coordinates given ‘mlapdv’ (ibl) or ‘apdvml’ (Allen mcc vertices) :return: xyz: mlapdv coordinates in m, origin Bregma

NeedlesAtlas(*args, **kwargs)

Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system. The Needles atlas defines a stretch along AP axis and a sqeeze along the DV axis.

Parameters

res_um – 10, 25 or 50 um

Returns

atlas.BrainAtlas

MRITorontoAtlas(*args, **kwargs)

Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system. The MRI Toronto atlas defines a stretch along AP a squeeze along DV and a squeeze along ML. These are based on 12 p65 mice MRIs averaged. See: https://www.nature.com/articles/s41467-018-04921-2 DB has access to the dataset.

Parameters

res_um – 10, 25 or 50 um

Returns

atlas.BrainAtlas

class FlatMap(flatmap='dorsal_cortex', res_um=25)

Bases: AllenAtlas

plot_flatmap(depth=0, volume='annotation', mapping='Allen', region_values=None, ax=None, **kwargs)

Displays the 2D image corresponding to the flatmap. If there are several depths, by default it will display the first one

Parameters

• depth – index of the depth to display in the flatmap volume (the last dimension)

• volume –

• mapping –

• region_values –

• ax –

• kwargs –

Returns

extent_flmap()

class FranklinPaxinosAtlas(res_um=array([10, 100, 10]), scaling=array([1, 1, 1]), mock=False, hist_path=None)

Bases: BrainAtlas

Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system