ibllib.atlas.atlas
Functions
Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system. |
|
Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system. |
|
Converts cartesian to spherical Coordinates theta: polar angle, phi: azimuth |
|
Converts Spherical to Cartesian coordinates theta: polar angle, phi: azimuth |
Classes
Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system |
|
Objects that holds image, labels and coordinate transforms for a brain Atlas. |
|
Class for mapping and indexing a 3D array to real-world coordinates x = ml, right positive y = ap, anterior positive z = dv, dorsal positive |
|
Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system |
|
Defines an ephys probe insertion in 3D coordinate. |
|
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
- xyz2i(xyz, round=True, mode='raise')[source]
- 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
- property xlim
- property ylim
- property zlim
- 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.
- compute_surface()[source]
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')[source]
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')[source]
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)[source]
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)[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=None, bc=None)[source]
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)[source]
Compute the boundaries between regions on slice
- Parameters
values –
- Returns
- plot_slices(xyz, *args, **kwargs)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[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: ndarray
- point: ndarray
- static fit(xyz)[source]
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)[source]
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)[source]
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)[source]
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)[source]
projects a point onto the trajectory line
- Parameters
point – np.array(x, y, z) coordinates
- Returns
- 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.
- Parameters
xyz – […, 3]
bounds – defaults to None. np.array [2, 3]: segment boundaries, inf line if None
- Returns
minimum distance […]
- 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
- 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
- class AllenAtlas(res_um=25, scaling=array([1, 1, 1]), mock=False, hist_path=None)[source]
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')[source]
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')[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 m, 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.
- Parameters
res_um – 10, 25 or 50 um
- Returns
atlas.BrainAtlas
- MRITorontoAtlas(*args, **kwargs)[source]
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)[source]
Bases:
AllenAtlas
- plot_flatmap(depth=0, volume='annotation', mapping='Allen', region_values=None, ax=None, **kwargs)[source]
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
- class FranklinPaxinosAtlas(res_um=array([10, 100, 10]), scaling=array([1, 1, 1]), mock=False, hist_path=None)[source]
Bases:
BrainAtlas
Instantiates an atlas.BrainAtlas corresponding to the Allen CCF at the given resolution using the IBL Bregma and coordinate system