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 the atlas physical space (millimetres).

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 (millimetres).

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 original atlas micron 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 the current physical space (millimetres).

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

Parameters:

• reference ¶

  (DataArray) –

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

• transform ¶

  ((N+1, N+1) numpy.ndarray) –

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

• reference_interpolation ¶

  ((linear, 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][].