Atlas module

Atlas Functions

atlas_map.get_atlas(atlas_str, atlas_dir='/home/docs/checkouts/readthedocs.org/user_builds/functional-fusion/checkouts/latest/Functional_Fusion/Atlases')

convenience function to return an atlas from a code. For this the atlas has to be standard and defined in the atlas_description.json file. For non-standard atlases (custom ROIs), use the AtlasVolumetric or AtlasSurface classes directly.

Parameters:

• atlas_str (str) – Name of the atlas

• atlas_dir (str) – Atlas Directory (defaults to Functional_Fusion/Atlases)

Returns:

• atlas (AtlasVolumetric, AtlasSurface, (or symmetric variant) object) – Atlas object

• ainf (dict) – Atlas info

atlas_map.get_deform(target_space, source_space, atlas_dir='/home/docs/checkouts/readthedocs.org/user_builds/functional-fusion/checkouts/latest/Functional_Fusion/Atlases')

Get name of group deformation map between two volumetric spaces In image mode. That is, the xfm file will be in the voxels space of the target, and contain the xyz coordinates of the source space (pull). If you want to deform points (ROI centers, surfaces) from the target to the source, you need mode-point xfm file (push). Note that: tpl-A_from_B-mode-point_xfm.nii = tpl-B_from_A-mode-image_xfm.nii

Parameters:

• target_space (str) – Target space

• source_space (str) – Source space

• atlas_dir (str) – Atlas Directory (defaults to Functional_Fusion/Atlases)

Returns:

deform (str) – Name of deformation map

atlas_map.deform_data(data, src_atlas, trg_atlas, interpolation=1)

Deforms any data from a source atlas to a target atlas Current implementation is only for volumetric atlases Source atlas has P_src locations, target space has P_trg locations

Parameters:

• data (ndarray) – N x P_src array of data

• src_atlas (Atlas) – Source atlas

• trg_atlas (Atlas) – Target atlas

• interpolation (int, optional) – Nearest Neighbour (0) or Trilinear interpolation (1). Defaults to 1.

Returns:

data_def (ndarray) – N x P_trg array of data

atlas_map.parcel_recombine(label_vector, parcels_selected, label_id=None, label_name=None)

Recombines and selects different parcels into a new label vector for ROI analysis. IMPORTANT: Note that each old parcel can only be mapped to one new parcel. That is the elements of parcels_selected must be non-overlapping.

Parameters:

• label_vector (ndarrray) – voxel array of labels

• parcels_selected (list) – list of the parcels being selected. Each element should be a) Scalar value of lable_ids, b) List/array of scalar values of label_ids c) A regexp - for example ‘D.L’ would select all labels starting with D.L

• label_id (ndarrray) – ndarray of parcel ids

• label_name (list) – List of parcel names

Returns:

• label_vector – new coded vector, with the first ROI label with 1. all others 0

• label_id – new label id

• label_name – new label name

atlas_map.get_data_nifti(fnames, atlas_maps, dtype=<class 'numpy.float32'>)

Extracts the data for a list of fnames for a list of atlas_maps. This is usually called by DataSet.extract_data() to extract the required raw data before processing it further

Parameters:

• fnames (list) – List of file names to be sampled

• atlas_maps (list) – List of K atlas-map or atlas objects

Returns:

data (list) – List of NxP_k 2-d array data matrices (np)

atlas_map.get_data_cifti(fnames, atlases)

Extracts the data for a list of fnames for a list of atlas_maps. This is usually called by DataSet.get_data() to extract the required raw data before processing it further

Parameters:

• fnames (list) – list of file names to be sampled

• atlas_maps (list) – list of K built atlas-map objects

Returns:

data (list) – List of NxP_k 2-d array data matrices (np)

Atlas Classes

class atlas_map.Atlas(name, structure='unknown', space='unknown')

The Atlas class implements the mapping from the P brain locations back to the defining Volumetric or surface space. It also allows for parcellation of these brain locations. Each Atlas is associated with a set of atlas maps

Parameters:

name (str) – Unique code for the atlas (e.g. ‘SUIT3’)

get_parcel(label_img)

adds a label_vec to the atlas that assigns each voxel / node of the atlas to a parcel (region). label_vec[i] = 0 means that the ith voxel / vertex is unassigned

Parameters:

label_img (str/list) - filename(s) of label image(s)

Returns:

• label_vec (list) - list of numpy array containing label values corresponding to label images (0 means no ROI)

• labels (ndarray)

get_subatlas(include)

Returns a subatlas (region) based on a label value.

Parameters:

include (np.array) – Boolean array of length P of which brain location to include

Returns:

new_atlas (Atlas) – New atlas object

class atlas_map.AtlasVolumetric(name, mask_img, structure='unknown', space='unknown')

Atlas Volumetric is an atlas for a Volumetric space / structure.

Parameters:

• name (str) – Name of atlas (atlas string)

• mask_img (str) – file name of mask image or mask image defining atlas location

data_to_cifti(data, row_axis=None)

Transforms data into a cifti image

Parameters:

• data (ndarray/list) – the input data to be mapped: shape (N,P).

• row_axis –

  label for row axis in cifti file, it can be:

  (list) - a list of row names

  (object) - a pandas framework object of the row names

  (cifti2.Axis) - a cifti2 Axis object that can be directly used to write header. (e.g. ScalarAxis, SeriesAxis, …)

  (None) - default to generate a list of row names that matches the input data

Returns:

img (Cifti2Image) – Cifti2Image object

data_to_nifti(data)

Transforms data in atlas space into 3d or 4d nifti image, depending on whether the data is a vector (1d) or a matrix (2d). Depending on the data type (float or int) the empty parts of the image will be NaNs or zeros. The nifti data type will be dictated by the data type of the input data.

Parameters:

data (np.ndarray) – P-vector or NxP matrix to be mapped into nifti

Returns:

Nifti1Image (nb.Nifti1Image) – NiftiImage object

get_brain_model_axis()

Returns brain model axis

Returns:

bm (cifti2.BrainModelAxis)

get_parcel_axis()

Returns parcel axis based on the current setting of labels

Returns:

bm (cifti2.ParcelAxis)

get_subatlas(include)

Returns a subatlas (region) based on a mask image

Parameters:

include (np.array) – Logical array of length P (or array of indices) of which brain location in the atlas.

Returns:

new_atlas (AtlasVolumetric) – New atlas object

get_subatlas_image(mask_img, label_value=None)

Returns a subatlas (region) based on a mask image Selects either any voxel > 0 (default), any voxel == label_value, or any voxel which has a value in the list of label_values.

Parameters:

• mask_img (str) – Mask or discrete segmentation image filename

• label_value (int,list) – Value(s) for the target ROI (default None)

Returns:

new_atlas (AtlasVolumetric) – New atlas object

get_subatlas_sphere(center, radius)

Returns a subatlas (region) based on a sphere around a center location within current atlas

Parameters:

• center (np.array) – 3-vector of center of the sphere in mm

• radius (float) – Radius of the sphere in mm

read_data(img, interpolation=0)

Read data from a NIFTI or CIFTI file into the volumetric atlas space

Parameters:

• img (nibabel.image) – Nifti or Cifti image or corresponding filename

• interpolation (int)) – nearest neighbour (0), trilinear (1)

Returns:

data (ndarray) – (N,P) ndarray

sample_nifti(img, interpolation)

Samples a img at the atlas locations The image needs to be in atlas space.

Parameters:

img (str or NiftiImage) – Nifti to be sampled

Returns:

data (np.array) – Data sampled at the atlas position

class atlas_map.AtlasVolumeSymmetric(name, mask_img, structure='unknown', space='unknown')

Volumetric atlas with left-right symmetry. The atlas behaves like AtlasVolumetric, but provides mapping indices from a full representation to a reduced (symmetric) representation of size Psym. The constructor generates members indx_full, indx_reduced, indx_flip.

Assume you have a

Full: N x P array

Left: N x Psym array

Right: N x Psym array

then:

Left = Full[:,index_full[0]]

Right = Full[:,index_full[1]]

Avrg = (Left + Right)/2

Full = Avrg[:,index_reduced]

To Flip:

flippedFull = Full[:,index_flip]

Parameters:

• name (str) – Name of the atlas (e.g. ‘SUIT3’)

• mask_img (str) – file name of mask image defining atlas location

calculate_symmetry()

Calculates the symmetry indices (left-right correspondence) of the atlas. Stores the results in the object itself.

class atlas_map.AtlasSurface(name, mask_img, structure=['cortex_left', 'cortex_right'], space='fs32k')

Surface-based altas space

Atlas Surface class constructor

Parameters:

• name (str) – Name of atlas (cortex_left, cortex_right, cerebellum)

• mask_gii (list) – list of gifti files of mask image defining atlas locations

• structure (list) – [cortex_left, cortex_right] - CIFTI brain structure names

cifti_to_data(cifti)

Gets the data from a CIFTI file, checking the structure name

and vertex information in the cifti file. If it doesn’t match the vertex information in the atlas object, it gives a warning, but corrects for it by extracting the available data.

Parameters:

cifti (ciftiimage or filename) – Cifti file to be used

Returns:

data (np.ndarray) – NxP np-array

data_to_cifti(data, row_axis=None)

Maps data back into a cifti image

Parameters:

• data –

  the input data to be mapped

  (ndarray) - Numpy array of the size (K,P)

  (list) - list of ndarray

• row_axis –

  label for row axis in cifti file, it can be

  (list) - a list of colum names

  (object) - a pandas framework object of the colum names

  (cifti2.Axis) - a cifti2 Axis object that can be directly used to write header. (e.g. ScalarAxis, SeriesAxis, …)

  None - default to generate a list of column names that matches the input data

Returns:

img (Cifti2Image) – Cifti2Image object

get_brain_model_axis()

Returns brain model axis

Returns:

bm (cifti2.BrainModelAxis)

get_hemisphere(hem)

Returns a new atlas object that only contains one hemisphere specified

Parameters:

hem (int) – Hemisphere index (0: left, 1: right)

Returns:

new_atlas (AtlasSurface) – New atlas object

get_parcel(label_img, unite_struct=False)

adds a label_vec to the atlas that assigns each voxel / node of the atlas label_vec[i] = 0 mean that the ith voxel / node is unassigned

Parameters:

• label_img (str/list) - filename(s) of label image(s)

• unite_struct (bool) – False

Returns:

• label_vec (list)

• labels (ndarray)

get_parcel_axis()

Returns parcel axis based on the current setting of labels

Returns:

bm (cifti2.ParcelAxis)

get_subatlas(include)

Returns a subatlas (region) based on a logical mask.

Parameters:

include (np.array) – Logical array of length P of which brain location to include

Returns:

new_atlas (AtlasSurface) – New atlas

get_subatlas_circle(center, radius)

Gets a subatlas (region) based on a circle around a center location within current atlas

Parameters:

• hem (int) – Hemisphere index (0: left, 1: right)

• center (np.array) – 3-vector of center of the sphere in mm

• radius (float) – Radius of the sphere in mm

Returns:

new_atlas (AtlasSurface) – New atlas object

get_subatlas_image(mask_img, value=None)

Returns a subatlas (region) based on a mask image

Usages:

get_subatlas_image(‘label.gii’,hem=0):

Takes a single lable gifti and applies it to the left hemisphere

subatlas only contains that hemisphere

get_subatlas_image(‘dlabel.nii’):

Uses a bihemispheric CIFTI file, potentiall define structure of both hemispheres

get_subatlas_image([‘label_left.gii’,’label_right.gii’]):

Parameters:

• mask_img (str) – Mask image filename

• value (int) – Specific Value of mask imahe to included in the subatlas (default >0)

Returns:

new_atlas (AtlasSurface) – New atlas object

read_data(img, interpolation=0)

Reads data for surface-based atlas from list of gifti [left,right] or single cifti file. Adjusts automatically for node masks.

Parameters:

• img (nibabel.image) – Cifti or its filename or list of gifti images

• interpolation (int) – nearest neighbour (0), trilinear (1)

Returns:

data (ndarray) – (N,P) ndarray

class atlas_map.AtlasSurfaceSymmetric(name, mask_gii, structure=['cortex_left', 'cortex_right'], space='fs32k')

Surface atlas with left-right symmetry The atlas behaves like AtlasSurface, but provides a reduced (symmetric) representation of size Psym.AtlasSurfaceSymmeytric Constructor: Generates members indx_full, indx_reduced, indx_flip. mapping indices from a full representation to

Assume you have a

Full: N x P array

Left: N x Psym array

Right: N x Psym array

then:

Left = Full[:,index_full[0]]

Right = Full[:,index_full[1]]

Avrg = (Left + Right)/2

Full = Avrg[:,index_reduced]

To Flip:

flippedFull = Full[:,index_flip]

Parameters:

• name (str) – Name of the brain structure (cortex_left, cortex_right, cerebellum)

• mask_gii (list) – gifti file name of mask image defining atlas locations

• structure (list) – [cortex_left, cortex_right] - CIFTI brain structure names

calculate_symmetry()

Calculate the symmetry of the surface atlas

Atlasmap Classes

class atlas_map.AtlasMap

AtlasMap is a class that stores the mapping rules betwween a set of locations in atlas space and an individual space

extract_data_group(images)

Extracts the desired atlas locations from a set of images, applied mapping rules and returns the data in group space

Parameters:

images (list) – List of N image filenames

Returns:

data_group (ndarray) – (N,P) ndarray

extract_data_native(images)

Extracts the voxels required for the desired atlas locations from a set of images

Parameters:

images (list) – List of N image filenames

Returns:

data_group (ndarray) – (N,V) array, were V are the number of unique voxels that map to the P atlas locations

map_native_to_group(data)

Maps the data from native space to group space

Parameters:

data (ndarray) – (N,V) array, were V are the number of unique voxels that map to the P atlas locations

Returns:

data_group (ndarray) – (N,P) ndarray

save_as_image(fname=None)

Save a mask of the voxel in native space that are involved in the ROI. This function is mostly to check the ROI after building it.

Parameters:

fname (str) – file name for the nifti-file (use *.nii.gz for compression). If None, no file is saved.

Returns:

mask_img (Nift1Image) – Image for the mask

class atlas_map.AtlasMapDeform(world, deform_img, mask_img=None)

AtlasMapDeform stores the mapping rules for a non-linear deformation to the desired atlas space in form of a voxel list from source space

Parameters:

• worlds (ndarray) – 3xP ND array of world locations

• deform_img (str/list) – Name of deformation map image(s). If None, no deformation is applied.

• mask_img (str) – Name of masking image that defines the voxels in functional space that are available for mapping.

build(interpolation=1, smooth=None, additional_mask=None)

Using the dataset, builds a list of voxel indices of For each of the locations. It creates: vox_list: List of voxels to sample for each atlas location vox_weight: Weight of each of these voxels to determine the atlas location

Parameters:

• interpolation (int) – nearest neighbour (0), trilinear (1), smooth (2)

• smooth (double) – SD of smoothing kernel (mm) (only used if interpolation=2)

• additional_mask – Additional Mask image (not necessarily in functional space - only voxels with elements > 0 in that image

• ) (will be used for the altas)

class atlas_map.AtlasMapSurf(vertex, white_surf, pial_surf, mask_img)

AtlasMapSurf stores the mapping rules for a freesurfer-style surface (pial + white surface pair)

Parameters:

• vertex (ndarray) – Array of vertices included in the atlas map

• white_surf (str) – Name for white matter surface

• pial_surf (str) – Name for pial surface

• mask_img (str) – Name of masking image that defines the functional data space.

build(depths=[0, 0.2, 0.4, 0.6, 0.8, 1.0])

Using the dataset, builds a list of voxel indices of each of the nodes

vox_list: List of voxels to sample for each atlas location

vox_weight: Weight of each of these voxels to determine the atlas location

Parameters:

• depths (iterable) – List of depth between pial (1) and white (0) surface that

• sampled (will be)