unravel.coordinates.points_to_labeled_voxel_img module#

Use coords_points_to_labeled_voxel_img or points_to_labeled_voxel_img from UNRAVEL to convert point coordinates into a labeled unique-voxel image.

This is useful when many units/channels occupy the same voxel. Instead of creating one image per unit, this script groups rows by voxel coordinate and assigns one unique integer label per occupied voxel.

Input:

  • CSV with voxel coordinates, usually x, y, z from coords_physical_points_add_regions

  • Reference image for output shape/header

Outputs:

  • labeled image where img[x, y, z] = voxel_label

  • mapping CSV linking voxel_label back to all rows/units/channels in that voxel

  • row-level mapping CSV preserving one row per original unit/channel

Notes

  • Input coordinates must already be voxel/index coordinates.

  • If coordinates are physical coordinates, run coords_physical_points_add_regions or coords_physical_points_to_img-style conversion first.

  • Use nearest-neighbor/multiLabel interpolation when reorienting, resampling, or warping the output labeled image.

  • Aggregated columns in the mapping CSV (from -c) are stored as sorted unique values and are NOT guaranteed to preserve row-wise alignment across columns (e.g., unit_id ↔ channel_id). Use the row-level mapping CSV for analyses requiring exact correspondence between columns.

Usage:#

points_to_labeled_voxel_img

-i units_with_regions.csv -ri samples/downsampled_standard_NP09_488_Ch0.nii.gz -x x -y y -z z [-c recording_name unit_id channel_id shank_id abbreviation full_structure_name lowered_ID] -o unique_voxels -v

unravel.coordinates.points_to_labeled_voxel_img.parse_args()[source]#
unravel.coordinates.points_to_labeled_voxel_img.aggregate_values(series)[source]#

Return sorted unique non-null values joined by semicolons.

unravel.coordinates.points_to_labeled_voxel_img.choose_dtype(max_label)[source]#

Choose a reasonable integer dtype for the labeled image.

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