# 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]

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