ibllib.atlas.atlas

Functions

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

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)[source]

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

sph2cart(r, theta, phi)[source]

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

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

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)[source]
r2iy(r)[source]
r2iz(r)[source]
x2i(x, round=True)[source]
y2i(y, round=True)[source]
z2i(z, round=True)[source]
xyz2i(xyz, round=True)[source]
i2x(ind)[source]
i2y(ind)[source]
i2z(ind)[source]
i2xyz(iii)[source]
property xlim
property ylim
property zlim
lim(axis)[source]
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])[source]

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.

bc

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

get_labels(xyz, mapping='Allen')[source]

Performs a 3D lookup from real world coordinates to the volume labels and return the regions ids according to the mapping :param xyz: [n, 3] array of coordinates :param mapping: brain region mapping (defaults to original Allen mapping) :return: n array of region ids

tilted_slice(xyz, axis, volume='image')[source]

From line coordinates, extracts the tilted plane containing the line from the 3D volume :param 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, **kwargs)[source]

From line coordinates, extracts the tilted plane containing the line from the 3D volume :param 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)[source]
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='Allen', bc=None)[source]
Parameters
  • coordinate – 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’ or ‘annotation’

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

:param region_values :return: 2d array or 3d RGB numpy int8 array

plot_cslice(ap_coordinate, volume='image', mapping='Allen', **kwargs)[source]

Imshow a coronal slice :param: ap_coordinate (m) :param volume: ‘image’ or ‘annotation’ :return: ax

plot_hslice(dv_coordinate, volume='image', mapping='Allen', **kwargs)[source]

Imshow a horizontal slice :param: dv_coordinate (m) :param volume: ‘image’ or ‘annotation’ :return: ax

plot_sslice(ml_coordinate, volume='image', mapping='Allen', **kwargs)[source]

Imshow a sagittal slice :param: ml_coordinate (m) :param volume: ‘image’ or ‘annotation’ :return: ax

plot_top(ax=None)[source]
class Trajectory(vector: numpy.ndarray, point: numpy.ndarray)[source]

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: numpy.ndarray
point: numpy.ndarray
static fit(xyz)[source]

fits a line to a 3D cloud of points, returns a Trajectory object :param xyz: n by 3 numpy array containing cloud of points :returns: a Trajectory object

eval_x(x)[source]

given an array of x coordinates, returns the xyz array of coordinates along the insertion :param x: n by 1 or numpy array containing x-coordinates :return: n by 3 numpy array containing xyz-coordinates

eval_y(y)[source]

given an array of y coordinates, returns the xyz array of coordinates along the insertion :param y: n by 1 or numpy array containing y-coordinates :return: n by 3 numpy array containing xyz-coordinates

eval_z(z)[source]

given an array of z coordinates, returns the xyz array of coordinates along the insertion :param z: n by 1 or numpy array containing z-coordinates :return: n by 3 numpy array containing xyz-coordinates

project(point)[source]

projects a point onto the trajectory line :param point: np.array(x, y, z) coordinates :return:

mindist(xyz, bounds=None)[source]

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. :param xyz: […, 3] :param bounds: defaults to None. np.array [2, 3]: segment boundaries, inf line if None :return: minimum distance […]

exit_points(bc)[source]

Given a Trajectory and a BrainCoordinates object, computes the intersection of the trajectory with the brain coordinates bounding box :param bc: BrainCoordinate objects :return: 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)[source]

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)[source]
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)[source]

Constructs an Insertion object from the json information stored in probes.description file :param 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 }

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

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)[source]

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) :param brain_atlas: :return: 3 element array x,y,z

static get_brain_entry(traj, brain_atlas)[source]

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) :param brain_atlas: :return: 3 element array x,y,z

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

Bases: ibllib.atlas.atlas.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')[source]

Converts coordinates to the CCF coordinates, which is assumed to be the cube indices times the spacing. :param xyz: mlapdv coordinates in um, origin Bregma :param ccf_order: order that you want values returned ‘mlapdv’ (ibl) or ‘apdvml’ (Allen mcc vertices) :return: 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')[source]

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 um, origin Bregma

NeedlesAtlas(*args, **kwargs)[source]

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. :param res_um: 10, 25 or 50 um :return: atlas.BrainAtlas