aind_ephys_utils.helpers.ccf module

Allen CCF (Common Coordinate Framework) structure-tree utilities.

Ontology helpers over the Allen 2017 structure tree: expand a region to all of its descendants, and order regions so anatomical neighbours are adjacent. A copy of the structure tree ships with the package (the same CSV used by aind_ephys_utils.plots.get_color_for_region()), so the ccf_df argument is optional; pass a DataFrame or CSV path to use a different tree.

For region colours, use aind_ephys_utils.plots.get_color_for_region().

class aind_ephys_utils.helpers.ccf.RegionMatch(query: str, structure_id: int | None, matched_on: str | None)

Bases: object

Result of resolving a region string against the CCF ontology.

matched_on: str | None
query: str
structure_id: int | None
aind_ephys_utils.helpers.ccf.get_descendant_acronyms(region_acronyms: list[str] | str, ccf_df: DataFrame | str | Path | None = None) → set[str]

Get all descendant region acronyms for given acronym(s).

Expands each acronym to its whole subtree — e.g. "BLA" pulls in BLAa/BLAp/BLAv.

Parameters:

  • region_acronyms – CCF region acronym(s) to find descendants for.

  • ccf_df – CCF structure tree DataFrame or CSV path. None uses the bundled Allen 2017 tree.

Returns:

Acronyms of the requested regions and all their descendants.

Return type:

set[str]

aind_ephys_utils.helpers.ccf.get_descendant_ids(structure_id: int, ccf_df: DataFrame | str | Path | None = None) → set[int]

Get all descendant structure IDs (including structure_id).

Parameters:

  • structure_id – The CCF structure ID to find descendants for.

  • ccf_df – CCF structure tree DataFrame or CSV path. None uses the bundled Allen 2017 tree.

Returns:

structure_id and every structure beneath it in the ontology.

Return type:

set[int]

aind_ephys_utils.helpers.ccf.order_regions_by_ccf(regions: Iterable[str], ccf_df: DataFrame | str | Path | None = None, group_depth: int | None = None) → tuple[list[str], dict[str, int], list[RegionMatch]]

Order region strings by CCF ontology (neighbours adjacent).

Parameters:

  • regions – Region identifiers (acronyms preferred; names OK, case-insensitive).

  • ccf_df – CCF structure tree DataFrame or CSV path. None uses the bundled Allen 2017 tree.

  • group_depth – If set, strengthen grouping by the ontology node at/above this depth.

Returns:

  • ordered – Input regions reordered for plotting.

  • index_map – Mapping from region string to its index in ordered.

  • matches – Match metadata per input (unresolved items have structure_id=None and sort last).

aind_ephys_utils.helpers.ccf.resolve_regions(regions: Iterable[str], ccf_df: DataFrame | str | Path | None = None) → DataFrame

Resolve region strings to CCF structure metadata.

Each input is resolved to a structure id (acronym first, then name, case-insensitive) and reported with its canonical id, acronym, and name. Schema-free: returns one tidy row per input so the caller can join/map the result however they like — e.g. attach to a units table, or add colours via aind_ephys_utils.plots.get_color_for_region().

Parameters:

  • regions – Region identifiers (acronyms preferred; names OK, case-insensitive).

  • ccf_df – CCF structure tree DataFrame or CSV path. None uses the bundled Allen 2017 tree.

Returns:

One row per input, in input order, with columns query, structure_id (nullable Int64), acronym, name, and matched_on. Unresolved inputs have <NA>/None.

Return type:

pandas.DataFrame