confusius.atlas¶

Return the ancestor nodes of region, from root down (exclusive).

Parameters:

• region ¶

  (int or str) –

  Structure index or acronym.

Returns:

• list[Node] –

  Ancestor nodes ordered from root toward region, not including region itself.

Return integer region masks stacked along a mask dimension.

Each layer along mask has values in {0, region_id}; voxels belonging to the requested region (including all descendants in the hierarchy) carry the region's index, all others are zero.

Parameters:

• regions ¶

  (int or str or sequence of int or str) –

  One or more regions, each given as a structure index or acronym.

• sides ¶

  ((left, right, both), default: "left" ) –

  Hemisphere filter. Pass a scalar to apply the same side to all regions, or a sequence of the same length as regions for per-region control.

Returns:

• DataArray –

  Integer VoxelData array with dims ["mask", *annotation.dims]. The mask coordinate holds the region acronym for each layer, suffixed with _L/_R when the corresponding side is "left"/"right" (left/right requests for the same region would otherwise share an acronym).

Raises:

• TypeError –

  If ds is not a well-formed atlas Dataset.

• KeyError –

  If any requested region acronym or index is not found in the atlas.

• ValueError –

  If sides is a sequence whose length does not match regions, or if any element of sides is not "left", "right", or "both".

Examples:

>>> ds.atlas.get_masks("VISp")
>>> ds.atlas.get_masks("VISp", sides="left")
>>> ds.atlas.get_masks(["VISp", "AUDp", "MOp"])
>>> ds.atlas.get_masks(["VISp", "AUDp"], sides=["left", "both"])
>>> ds.atlas.get_masks(["VISp", "VISp"], sides=["left", "right"]).coords["mask"].values
array(['VISp_L', 'VISp_R'], dtype=object)

Return one surface mesh per requested region, keyed by acronym.

Reads each region's mesh, transforms its vertices from micron space to the DataArrays' current world space (millimetres), then optionally drops out-of-grid vertices and clips to one hemisphere. The mesh comes from the structure's mesh_filename: for a freshly fetched atlas this points into the BrainGlobe cache; for an atlas loaded with load_atlas it points at the mesh bundled inside the store.

Parameters:

• regions ¶

  (int or str or sequence of int or str) –

  One or more regions, each given as a structure index or acronym.

• sides ¶

  ((left, right, both), default: "left" ) –

  Hemisphere filter. Pass a scalar to apply the same side to all regions, or a sequence of the same length as regions for per-region control. "both" keeps the full mesh. "left" and "right" keep only vertices whose nearest hemispheres voxel carries that side's label (hemispheres.attrs["left"] / ["right"]), sampled in the current world space. Faces are kept only when all three of their vertices survive, so the cut face is not closed. Sampling the hemisphere map makes this orientation-agnostic and correct after an arbitrary resample.

• clip ¶

  (bool, default: True ) –

  Whether to clip each mesh to the current reference grid. Unclipped meshes are still transformed to the current world space but may extend past the grid's bounding box.

Returns:

• dict[str, tuple[(N, 3) numpy.ndarray, (M, 3) numpy.ndarray]] –

  One (vertices, faces) pair per requested region, keyed by the region's acronym, suffixed with _L/_R when the corresponding side is "left"/"right" (left/right requests for the same region would otherwise share a key). vertices holds coordinates in the current world space (millimetres); after a nonlinear resample, vertices warped outside the reference grid are dropped. faces holds zero-indexed triangle indices (int32).

Raises:

• TypeError –

  If ds is not a well-formed atlas Dataset.

• KeyError –

  If any requested region is not found in the atlas.

• ValueError –

  If sides is a sequence whose length does not match regions, if any element of sides is not "left", "right", or "both", or if a region has no mesh file.

• RuntimeError –

  If a region's mesh cannot be downloaded or read.

Examples:

>>> vertices, faces = ds.atlas.get_meshes("VISp")["VISp"]
>>> ds.atlas.get_meshes(["VISp", "AUDp"], sides=["left", "both"]).keys()
dict_keys(['VISp_L', 'AUDp'])

Resample the atlas onto an explicit output grid.

The atlas reference volume is resampled with interpolation; annotation and hemispheres are always resampled with nearest-neighbor interpolation to preserve integer labels. The returned Dataset stores the composed pull transform from its new world space back to the atlas base space in attrs["world_to_base"].

Parameters:

• transform ¶

  ((4, 4) numpy.ndarray or xarray.DataArray) –

  Pull transform mapping output world coordinates to current atlas world coordinates.

• output_sizes ¶

  (mapping of str to int) –

  Number of voxels along output axes, read by k/j/i keys.

• output_spacing ¶

  (mapping of str to float) –

  World distance between output positions, read by k/j/i keys.

• output_origin ¶

  (mapping of str to float) –

  World location of output position (0, 0, 0), read by z/y/x keys.

• output_direction ¶

  ((3, 3) numpy.ndarray) –

  Unit world-space direction columns for native k/j/i output axes.

• interpolation ¶

  ((linear, nearest, bspline), default: "linear" ) –

  Interpolation used for the atlas reference volume.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of SimpleITK threads.

Returns:

• Dataset –

  Resampled atlas Dataset on the requested grid. Meshes returned by get_meshes are transformed through the composed world_to_base attribute.

Resample the atlas onto reference's VoxelData grid.

Parameters:

• reference ¶

  (DataArray) –

  VoxelData array defining the target grid. Only its k/j/i grid (sizes/spacing/origin/direction) is used, so a time dimension, if present, is ignored. Must not have a pose or extra non-spatial dimension.

• transform ¶

  ((4, 4) numpy.ndarray or xarray.DataArray) –

  Pull transform mapping reference world coordinates to atlas world coordinates.

• interpolation ¶

  ((linear, nearest, bspline), default: "linear" ) –

  Interpolation used for the atlas reference volume.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of SimpleITK threads.

Returns:

• Dataset –

  Resampled atlas Dataset with exactly reference's voxel labels and voxel-to-world affine. Meshes returned by get_meshes are transformed through the composed world_to_base attribute.

Raises:

• ValueError –

  If reference has a pose or extra non-spatial dimension, or is not a VoxelData array.

Search structures by name or acronym.

Parameters:

• pattern ¶

  (str) –

  Substring or regex pattern.

• field ¶

  ((all, acronym, name), default: "all" ) –

  Which column to search.

  • "all": case-insensitive regex search on both acronym and name.
  • "acronym" / "name": case-insensitive full regex match on that column only.

Returns:

• DataFrame –

  Filtered view of lookup matching the search criteria.

Examples:

>>> ds.atlas.search("visual cortex")
>>> ds.atlas.search("VISp", field="acronym")

Print the structure hierarchy tree.

Parameters:

• **kwargs ¶

  (object, default: {} ) –

  Additional keyword arguments forwarded to [treelib.Tree.show][].

Returns:

• None –

  The tree is printed to standard output.