Source code for brainglobe_atlasapi.manifest

"""Convert atlas manifests into the metadata shape ``core.Atlas`` consumes.

BrainGlobe manifests already have that shape. atlas-assets manifests are
reshaped, with missing fields derived from zarr metadata and the asset name.
"""

from pathlib import Path
from typing import Optional, Tuple

import numpy as np
import zarr

from brainglobe_atlasapi.descriptors import V3_ANNOTATION_NAME

SPECIES_BY_NAME_SEGMENT = {
    "mouse": "Mus musculus",
    "human": "Homo sapiens",
    "marmoset": "Callithrix jacchus",
    "rhesusmacaque": "Macaca mulatta",
    "cynomolgusmacaque": "Macaca fascicularis",
}

# brainglobe-space origin letters, keyed by OME anatomical axis direction.
_ORIGIN_BY_AXIS_DIRECTION = {
    "anterior-to-posterior": "a",
    "posterior-to-anterior": "p",
    "superior-to-inferior": "s",
    "inferior-to-superior": "i",
    "dorsal-to-ventral": "s",
    "ventral-to-dorsal": "i",
    "left-to-right": "l",
    "right-to-left": "r",
    "caudal-to-rostral": "p",
    "rostral-to-caudal": "a",
}


def _species_from_name(atlas_name: str) -> Optional[str]:
    """Derive a binomial species name from an asset name.

    The specification's name grammar is explicitly non-normative and is
    not unambiguously parseable by position, so every segment is matched
    against a fixed vocabulary instead.

    Parameters
    ----------
    atlas_name : str
        Asset name, e.g. ``"allen-adult-mouse-ccf-atlas"``.

    Returns
    -------
    str or None
        Binomial name, or None when no segment matches the vocabulary.
    """
    for segment in atlas_name.split("-"):
        species = SPECIES_BY_NAME_SEGMENT.get(segment.lower())
        if species is not None:
            return species
    return None


def _intrinsic_axes(multiscale: dict) -> list:
    """Return the axes of the space the array indices live in.

    OME-Zarr 0.5 (the BrainGlobe bucket) declares one set of axes on the
    multiscale. 0.6 (atlas-assets) declares several coordinate systems
    and names, on each dataset, the one its indices map into; that
    intrinsic system is the one describing storage order, as opposed to
    any anatomical space derived from it.

    Parameters
    ----------
    multiscale : dict
        One entry of the ``multiscales`` list.

    Returns
    -------
    list
        The axis dictionaries, in storage order.

    Raises
    ------
    KeyError
        If neither shape declares axes.
    """
    axes = multiscale.get("axes")
    if axes is not None:
        return axes

    outputs = {
        transform["output"]["name"]
        for transform in multiscale["datasets"][0]["coordinateTransformations"]
        if "name" in transform.get("output", {})
    }
    for system in multiscale.get("coordinateSystems", []):
        if system["name"] in outputs:
            return system["axes"]

    raise KeyError(
        "Multiscale declares no axes and no coordinate system matching "
        f"the output(s) {sorted(outputs)} of its datasets."
    )


def _orientation_from_axes(ome_attrs: dict) -> str:
    """Derive a brainglobe-space origin from OME axis metadata.

    Parameters
    ----------
    ome_attrs : dict
        The ``attributes.ome`` block of a zarr group.

    Returns
    -------
    str
        Three-letter origin, e.g. ``"asl"``.

    Raises
    ------
    KeyError
        If an axis carries no recognised anatomical orientation.
    """
    axes = _intrinsic_axes(ome_attrs["multiscales"][0])[-3:]
    letters = []
    for axis in axes:
        direction = axis.get("orientation", {}).get("value")
        try:
            letters.append(_ORIGIN_BY_AXIS_DIRECTION[direction])
        except KeyError as e:
            raise KeyError(
                f"Axis {axis.get('name')!r} has unrecognised anatomical "
                f"orientation {direction!r}."
            ) from e
    return "".join(letters)


def _voxel_sizes(ome_attrs: dict) -> list:
    """Return the voxel size of each pyramid level, in micrometres.

    Parameters
    ----------
    ome_attrs : dict
        The ``attributes.ome`` block of a zarr group.

    Returns
    -------
    list of list of float
        One ``[z, y, x]`` entry per level, in storage order.
    """
    return [
        [
            round(float(scale) * 1000, 6)
            for scale in _scale_from_transforms(
                dataset["coordinateTransformations"]
            )[-3:]
        ]
        for dataset in ome_attrs["multiscales"][0]["datasets"]
    ]


def _pyramid_level_from_attrs(
    ome_attrs: dict, resolution: float
) -> Tuple[int, str]:
    """Find the pyramid level matching a resolution in micrometres.

    As on BrainGlobe atlases, a level's resolution is its first axis: a
    16 x 16 x 20 um level is the 16 um one.

    Parameters
    ----------
    ome_attrs : dict
        The ``attributes.ome`` block of a zarr group.
    resolution : float
        Requested resolution, in micrometres.

    Returns
    -------
    tuple
        The ``(index, dataset_path)`` of the matching level.

    Raises
    ------
    ValueError
        If no level matches the requested resolution.
    """
    datasets = ome_attrs["multiscales"][0]["datasets"]
    first_axes = [voxel_size[0] for voxel_size in _voxel_sizes(ome_attrs)]
    for index, first_axis in enumerate(first_axes):
        if np.isclose(resolution, first_axis):
            return index, datasets[index]["path"]

    raise ValueError(
        f"Requested resolution {resolution} um is invalid for this atlas. "
        f"Available resolutions: {first_axes}."
    )


def _scale_from_transforms(transforms):
    """Return the scale factors from a coordinate transformation list.

    OME-Zarr 0.5 stores a flat ``[{scale}, {translation}]`` list, while 0.6
    wraps them as ``[{"type": "sequence", "transformations": [...]}]``. Both
    shapes are accepted, as raw dictionaries read from ``zarr.json``.

    Parameters
    ----------
    transforms : sequence
        Coordinate transformations for one multiscale dataset.

    Returns
    -------
    sequence of float
        The scale factors, one per axis.

    Raises
    ------
    ValueError
        If no scale transformation is present.
    """
    for transform in transforms:
        scale = transform.get("scale")
        if scale is not None:
            return scale
        for inner in transform.get("transformations", ()):
            scale = inner.get("scale")
            if scale is not None:
                return scale

    raise ValueError(
        "No scale transformation found in coordinateTransformations."
    )


[docs] def normalize_manifest(raw: dict, resolution, root_dir: Path) -> dict: """Return manifest metadata in the shape ``core.Atlas`` consumes. BrainGlobe manifests are returned unchanged. atlas-assets manifests are reshaped by ``_normalize_atlas_assets``. Parameters ---------- raw : dict Parsed atlas ``manifest.json``. resolution : float or None Requested resolution, in micrometres: the first axis of a non-isotropic atlas, e.g. 16 for 16 x 16 x 20 um. Defaults to the finest available, with a printed note when there is more than one to choose from; if the manifest has a single fixed resolution instead (a BrainGlobe manifest), a mismatching value raises. root_dir : Path Local cache namespace directory holding the downloaded assets. Returns ------- dict Metadata in BrainGlobe's shape. Raises ------ ValueError If ``resolution`` matches no available pyramid level. """ if isinstance(raw.get("templates"), list): return _normalize_atlas_assets(raw, resolution, root_dir) if resolution is not None and not np.isclose( resolution, raw["resolution"][0] ): raise ValueError( f"Atlas {raw['name']} has a fixed resolution of " f"{raw['resolution'][0]} um; {resolution} um was " f"requested." ) return raw
def _normalize_atlas_assets(raw: dict, resolution, root_dir: Path) -> dict: """Reshape an atlas-assets manifest into BrainGlobe's metadata shape. The first template and annotation set are promoted to singular keys, terminology is hoisted to the top level, and the fields the specification does not carry are derived from the zarr metadata and the asset name, or set to None. The result is tagged ``"format": "atlas-assets"`` so its meshes are dequantized. Parameters ---------- raw : dict Parsed atlas ``manifest.json``. resolution : float or None Requested resolution, in micrometres, or None for the finest available. Compared against the first axis of each pyramid level. root_dir : Path Local cache namespace directory holding the downloaded assets. Returns ------- dict Metadata in BrainGlobe's shape. Raises ------ ValueError If ``resolution`` matches no available pyramid level. """ annotation_set = raw["annotation_sets"][0] annotation_location = annotation_set["location"][1:] annotation_path = root_dir / annotation_location / V3_ANNOTATION_NAME annotation_group = zarr.open_group(str(annotation_path), mode="r") ome_attrs = annotation_group.attrs["ome"] voxel_sizes = _voxel_sizes(ome_attrs) if resolution is None: first_axes = [voxel_size[0] for voxel_size in voxel_sizes] resolution = min(first_axes) if len(first_axes) > 1: print( f"Atlas {raw['name']} provides resolutions {first_axes} um " f"and none was requested, so using the finest, " f"{resolution:g} um. Pass resolution= to choose another." ) level, dataset_path = _pyramid_level_from_attrs(ome_attrs, resolution) shape = annotation_group[dataset_path].shape return { "format": "atlas-assets", "name": raw["name"], "version": raw["version"], "location": raw["location"], "citation": None, "atlas_link": None, "species": _species_from_name(raw["name"]), "symmetric": True, "resolution": voxel_sizes[level], "orientation": _orientation_from_axes(ome_attrs), "shape": list(shape[-3:]), "additional_references": [], "coordinate_space": raw["coordinate_space"], "terminology": annotation_set["terminology"], "annotation_set": annotation_set, "template": raw["templates"][0], }
[docs] def get_annotation_set(manifest: dict) -> dict: """Return the annotation set entry from either manifest shape. Both shapes nest the annotation set's ``terminology`` and ``template`` inside it, which is where ``core.Atlas`` reads them from. Parameters ---------- manifest : dict Parsed atlas manifest, in either shape. Returns ------- dict The annotation set entry. """ annotation_sets = manifest.get("annotation_sets") if isinstance(annotation_sets, list): return annotation_sets[0] return manifest["annotation_set"]