abagen.AtlasTree

class abagen.AtlasTree(atlas, coords=None, *, triangles=None, atlas_info=None, group_atlas=True)[source]

Representation of a parcellation as a cKDtree for NN lookups

Parameters

  • atlas ((N,) niimg-like object or array_like) – Volumetric (niimg-like) or array of parcellation labels. If providing an array you must provide coords as well

  • coords ((N, D) array_like, optional) – Coordinates representing points in atlas. If provided it is assumed that atlas is a surface representation (i.e., if atlas is volumetric simply provide a niimg-like object and the coordinates will be derived from the data). Default: None

  • triangles ((F, 3) array_like, optional) – If coords are derived from a surface mesh, this array contains the indices of the nodes comprising the mesh triangles. Default: None

  • atlas_info ({os.PathLike, pandas.DataFrame, None}, optional) – Filepath or dataframe containing information about atlas. Must have at least columns [‘id’, ‘hemisphere’, ‘structure’] containing information mapping atlas IDs to hemisphere (i.e., “L” or “R”) and broad structural class (i.e.., “cortex”, “subcortex/brainstem”, “cerebellum”, “white matter”, or “other”). Default: None

  • group_atlas (bool, optional) – Whether the provided atlas is a group atlas (in MNI space) or a donor-level atlas (in native space). This will have an impact on how provided sample coordinates are handled. Default: True

property atlas

Returns values of provided atlas

property atlas_info

Returns atlas info dataframe, if it exists

property centroids

Return centroids of parcels in self.atlas

property coords

Returns coordinates of underlying cKDTree

fill_label(annotation, label, return_dist=False)[source]

Assigns a sample in annotation to every node of label in atlas

Parameters

  • annotation ((S, 3) array_like) – At a minimum, an array of XYZ coordinates must be provided. If a full annotation dataframe is provided, then information from the data frame (i.e., on hemisphere + structural assignments of tissue samples) is used to constrain matching of samples (if self.atlas_info is not None).

  • label (int) – Which label in self.atlas should be filled

  • return_dist (bool, optional) – Whether to also return distance to mapped samples

Returns

  • samples ((L,) np.ndarray) – ID of sample mapped to all L nodes in label of atlas

  • distance ((L,) np.ndarray) – Distances of matched samples to nodes in label. Only returned if return_dist=True

property graph

Returns graph of underlying parcellation

label_samples(annotation, tolerance=2)[source]

Matches all samples in annotation to parcels in self.atlas

Attempts to place each sample provided in annotation into a parcel in self.atlas. If self.volumetric is True, this function tries to best match samples in annotation to parcels in self.atlas by:

  1. Determining if the sample falls directly within a parcel,

  2. Checking to see if there are nearby parcels by slowly expanding the search space to include nearby voxels, up to a specified distance (specified via the tolerance parameter),

  3. Assigning the sample to the closest parcel if there are multiple nearby parcels, where closest is determined by the parcel centroid.

If at any step a sample can be assigned to a parcel the matching process is terminated. If there is still no parcel for a given sample after this process the sample is provided a label of 0.

On the other hand, if self.volumetric is False, then samples are simply matched to the nearest coordinate in self.atlas. Once matched, tolerance is treated as a standard deviation threshold. That is, all samples are matched to the nearest vertex, and then samples whose distance to the nearest vertex are more than tolerance s.d. above the mean distance for all samples are assigned a label of 0.

Parameters

  • annotation ((S, 3) array_like) – At a minimum, an array of XYZ coordinates must be provided. If a full annotation dataframe is provided, then information from the data frame (i.e., on hemisphere + structural assignments of tissue samples) is used to constrain matching of regions.

  • tolerance (float, optional) – Threshold for assigning samples to parcels. Default: 2

Returns

labels – Dataframe with parcel labels for each of S samples

Return type

(S, 1) pandas.DataFrame

property labels

Returns unique labels in atlas

match_closest_centroids(annotation, return_dist=False)[source]

Matches samples in annotation to closest centroids in self.atlas

Parameters

  • annotation ((S, 3) array_like) – At a minimum, an array of XYZ coordinates must be provided. If a full annotation dataframe is provided, then information from the data frame (i.e., on hemisphere + structural assignments of tissue samples) is used to constrain matching of regions (if self.atlas_info is not None).

  • return_dist (bool, optional) – Whether to also return distance to matched centroids

Returns

  • labels ((S,) np.ndarray) – ID of parcel with closest centroid to samples in annotation

  • distance ((S,) np.ndarray) – Distances of matched centroid to samples in annotation. Only returned if return_dist=True

property tree

Returns cKDTree constructed from provided atlas and coordinates

property triangles

Returns triangles of underlying graph (if applicable)

property volumetric

Return whether self.atlas is derived from a volumetric image