unravel.coordinates.refine_catchall_regions module#

Use coords_refine_catchall_regions or refine_catchall from UNRAVEL to refine catch-all atlas labels for points/units/channels using nearby descendant regions.

This script is intended to run after coords_physical_points_add_regions. It keeps the original atlas lookup columns and adds refined region columns.

For points assigned to broad/catch-all regions, e.g. STR, TH, HY, MB, etc., the script:

  1. Finds descendants of the catch-all region using structure_id_path.

  2. Converts descendant structure_IDs to lowered_IDs.

  3. Searches outward from the point voxel until a valid descendant atlas ID is found.

  4. Assigns the nearest descendant ID.

  5. If multiple descendant IDs are found at the same nearest distance, uses the mode.

Input:

  • CSV with voxel coordinate columns, e.g. x, y, z

  • Region metadata columns from coords_physical_points_add_regions

  • Atlas image in the same array orientation as the voxel coordinates

  • Region info CSV, e.g. CCFv3-2020_info.csv

Output:
  • CSV with original metadata plus:

    refined_lowered_ID refined_abbreviation refined_region_name refined_structure_ID refined_structure_id_path refinement_status refinement_radius_vox refinement_distance_vox refinement_distance_um

Note

  • This script assumes the atlas values are lowered_IDs.

  • structure_id_path contains structure_IDs, not lowered_IDs.

  • Descendants are identified using structure_ID in structure_id_path, then converted back to lowered_IDs for atlas lookup.

  • The original direct atlas lookup columns are preserved.

Usage:#

coords_refine_catchall_regions

-i ISOTRP_all_recordings_units_CCFcoordinates__w_CCFv3-2020_regions.csv -a atlas_CCFv3_2020_25um_LIP_applied.nii.gz -rc CCFv3-2020_info.csv -s 25 -o ISOTRP_all_recordings_units_CCFcoordinates__w_refined_regions.csv

unravel.coordinates.refine_catchall_regions.parse_args()[source]#
unravel.coordinates.refine_catchall_regions.load_region_info(args)[source]#

Load required region info columns.

unravel.coordinates.refine_catchall_regions.parse_id_path(path)[source]#

Parse Allen-style structure_id_path into a list of integer structure_IDs.

unravel.coordinates.refine_catchall_regions.build_region_lookup(region_info_df, args)[source]#

Build dictionaries for lowered_ID/structure_ID/abbr/name lookups.

unravel.coordinates.refine_catchall_regions.get_descendant_lowered_ids(region_info_df, catchall_structure_id, catchall_lowered_id, args)[source]#

Return lowered_IDs whose structure_id_path contains catchall_structure_id.

unravel.coordinates.refine_catchall_regions.choose_catchall_row(catchall_abbr, abbr_to_rows, args)[source]#

Choose the row corresponding to a catch-all abbreviation.

unravel.coordinates.refine_catchall_regions.build_catchall_candidate_map(region_info_df, args)[source]#

Map catch-all abbreviation to valid descendant lowered_ID candidates.

unravel.coordinates.refine_catchall_regions.nearest_descendant_region_id(atlas_img, coord, valid_ids, max_radius=10)[source]#

Search outward from coord and return nearest valid atlas ID.

unravel.coordinates.refine_catchall_regions.add_region_metadata_for_refined_ids(out_df, region_info_df, args)[source]#

Merge metadata for refined lowered_IDs.

unravel.coordinates.refine_catchall_regions.main()[source]#