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.

Construct an Atlas from a BrainGlobe atlas name or instance.

Parameters:

• atlas ¶

  (str or BrainGlobeAtlas) –

  Either a BrainGlobe atlas name string (e.g. "allen_mouse_25um") or an already-loaded BrainGlobeAtlas instance.

• **kwargs ¶

  (object, default: {} ) –

  Additional keyword arguments forwarded to BrainGlobeAtlas when atlas is a string. Common options include brainglobe_dir (override the atlas cache directory) and check_latest (disable the latest-version check). Ignored when atlas is already a BrainGlobeAtlas instance.

Returns:

• Atlas –

  Atlas with DataArrays in atlas physical space. BrainGlobe metadata and meshes are currently converted from microns to millimeters.

Examples:

>>> atlas = Atlas.from_brainglobe("allen_mouse_25um")
>>> atlas = Atlas.from_brainglobe("allen_mouse_25um", check_latest=False)
>>> atlas = Atlas.from_brainglobe(bg_atlas_instance)

Return integer region masks stacked along a masks 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 DataArray with dims ["mask", "z", "y", "x"]. The mask coordinate holds the region acronym for each layer.

Raises:

• 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:

>>> atlas.get_masks("VISp")
>>> atlas.get_masks("VISp", sides="left")
>>> atlas.get_masks(["VISp", "AUDp", "MOp"])
>>> atlas.get_masks(["VISp", "AUDp"], sides=["left", "both"])

Return vertex coordinates and face indices for a region's mesh.

Reads the OBJ file bundled with the BrainGlobe atlas, optionally clips to one hemisphere, then transforms vertices from micron space to the DataArrays' current physical space.

Parameters:

• region ¶

  (int or str) –

  Structure index or acronym.

• side ¶

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

  Hemisphere to include. "both" keeps the full mesh. "left" and "right" clip in the base atlas physical space along the RL axis at the volume midline. Only triangles whose three vertices all fall on the requested side are retained; the cut face is not closed.

  Note

  Generalising axis detection from the orientation attribute for non-asr atlases is not yet implemented.

Returns:

• vertices ( (ndarray, shape(N, 3)) ) –

  Vertex coordinates in millimeters.

• faces ( (ndarray, shape(M, 3)) ) –

  Zero-indexed triangle face indices (int32).

Raises:

• KeyError –

  If the requested region is not found in the atlas.

• ValueError –

  If the atlas does not have mesh files.

Resample the atlas onto an explicit output grid.

Mirrors confusius.registration.resample_volume for atlas objects by constructing a temporary reference grid and delegating to resample_like.

Parameters:

• transform ¶

  ((N+1, N+1) numpy.ndarray or xarray.DataArray) –

  Pull transform mapping output physical coordinates to the current atlas physical coordinates.

• shape ¶

  (sequence of int) –

  Number of voxels along each output axis, in dims order.

• spacing ¶

  (sequence of float) –

  Voxel spacing along each output axis, in dims order.

• origin ¶

  (sequence of float) –

  Physical origin along each output axis, in dims order.

• dims ¶

  (sequence of str) –

  Dimension names of the output atlas grid.

• reference_interpolation ¶

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

  Interpolation used for the reference volume.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of SimpleITK threads.

Returns:

• Atlas –

  Resampled atlas on the requested grid.

Resample the atlas onto the grid of reference.

Mirrors confusius.registration.resample_like. Returns a new Atlas whose DataArrays live on reference's grid.

• reference: resampled with reference_interpolation.
• annotation and hemispheres: resampled with nearest-neighbour to preserve integer labels.
• Meshes returned by get_mesh will also be in the new physical space.

moving, reference, and any DataArray transform must use the same physical coordinate units when such metadata is defined.

Parameters:

• reference ¶

  (DataArray) –

  Target grid. Must be 2D or 3D and must not have a time dimension.

• transform ¶

  ((N+1, N+1) numpy.ndarray or xarray.DataArray) –

  Pull/inverse transform returned by register_volume, mapping reference physical coordinates to atlas physical coordinates.

  • Affine (numpy.ndarray): homogeneous matrix.
  • B-spline (xarray.DataArray): control-point DataArray.
  • Displacement field (xarray.DataArray): dense field with attrs["type"] == "displacement_field_transform".

• reference_interpolation ¶

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

  Interpolation used for the reference variable.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of SimpleITK threads. Negative values use max(1, cpu_count + 1 + sitk_threads).

Returns:

• Atlas –

  New Atlas with DataArrays on reference's grid.

Examples:

>>> _, affine = atlas.reference.fusi.register.to_volume(
...     fusi_mean, metric="mattes_mi", transform="affine"
... )
>>> atlas_fusi = atlas.resample_like(fusi_mean, affine)

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 substring match on both acronym and name.
  • "acronym" / "name": full regex match on that column only.

Returns:

• DataFrame –

  Filtered view of lookup matching the search criteria.

Examples:

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

Print the structure hierarchy tree.

Parameters:

• **kwargs ¶

  –

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