unravel.region_stats.rstats module#

Use rstats from UNRAVEL to quantify region-wise metrics in an atlas.

Supported metrics:

  • counts

  • region_volumes

  • cell_densities

  • label_volumes

  • label_densities

  • mean

  • mean_in_seg

Prereqs:

  • reg_prep, reg, and optionally seg_ilastik

Inputs:
  • For counts / cell_densities / label_volumes / label_densities:

    • rel_path/segmentation_image.nii.gz (can be glob pattern)

  • For mean / mean_in_seg:

    • rel_path/intensity_image (e.g., .nii.gz, .tif, .ome.tif, .czi, .zarr, .h5, or dir of tifs)

  • rel_path/native_atlas_split.nii.gz (use this -a if this exists from warp_to_native; otherwise, use -m to warp atlas to native space)

Outputs:

  • CSV files in ./sample??/<output_dir>/ (default: regional_stats)

  • Example CSV naming: <condition>_sample??_regional_cell_densities.csv, <condition>_sample??_regional_label_densities.csv, <condition>_sample??_regional_mean.csv, or <condition>_sample??_regional_mean_in_seg.csv

  • For mean-based metrics, CSVs include both a support column (voxel count in region or regional segmentation) and the mean intensity column (e.g., mean intensity in the region or mean intensity in the segmentation mask within the region)

Note

  • Default csv: UNRAVEL/unravel/core/csvs/CCFv3-2020__regionID_side_IDpath_region_abbr.csv

  • Columns in region info CSV: Region_ID, Side, ID_Path, Region, Abbr

  • If using serial-2 photon data, use the –stpt flag to interleave blank slices to prevent cells from fusing across slices during counting

Next steps:

  • Use utils_agg_files to aggregate the CSVs from sample directories to the current directory

  • Use rstats_summary to summarize the results

Usage if the atlas is already in native space from warp_to_native:#

rstats -s rel_path/segmentation_image.nii.gz -a rel_path/native_atlas_split.nii.gz -c Saline –dirs sample14 sample36 [-2p] [-t cell_densities] [-md parameters/metadata.txt] [-cc 6] [-ro reg_outputs] [-fri autofl_50um_masked_fixed_reg_input.nii.gz] [-r 50] [-csv CCFv3-2020__regionID_side_IDpath_region_abbr.csv] [-mi] [-d list of paths] [-p sample??] [-v]

Usage if the native atlas is not available; it is not saved (faster):#

rstats -s rel_path/segmentation_image.nii.gz -m path/atlas_split.nii.gz -c Saline –dirs sample14 sample36 [-2p] [-t cell_densities] [-md parameters/metadata.txt] [-cc 6] [-ro reg_outputs] [-fri autofl_50um_masked_fixed_reg_input.nii.gz] [-r 50] [-csv CCFv3-2020__regionID_side_IDpath_region_abbr.csv] [-mi] [-d list of paths] [-p sample??] [-v]

Usage for mean intensity only within segmented voxels in each region:#

rstats -t mean_in_seg -s iba1_seg/iba1_seg_1.nii.gz -i iba1_rb20 -m path/atlas_split.nii.gz -c Saline -d <Path to dir with Saline samples>

unravel.region_stats.rstats.parse_args()[source]#
unravel.region_stats.rstats.get_atlas_region_at_coords(atlas, x, y, z)[source]#

“Get the ndarray atlas region intensity at the given coordinates

unravel.region_stats.rstats.count_cells_in_regions(sample_path, seg_img, atlas_img, connectivity, condition, region_info_df, stpt=False, min_voxels=1, output_dir_name='regional_stats')[source]#

Count the number of cells in each region based on atlas region intensities

Parameters:#

  • sample_path (Path): Path to the sample directory.

  • seg_img (ndarray): 3D numpy array with the segmented image.

  • atlas_img (ndarray): 3D numpy array with the atlas image.

  • connectivity (int): Connectivity for connected components. Options: 6, 18, or 26.

  • condition (str): Name of the group.

  • region_info_df (DataFrame): DataFrame with region information (Region_ID, Side, ID_Path, Region, Abbr).

  • stpt (bool): Whether to account for interleaved blank slices (adjustment for serial-2 photon data).

  • min_voxels (int): Minimum voxel count per connected component to keep (default: 1 keeps all).

Returns:#

  • region_counts_df (DataFrame): DataFrame with regional cell counts in the last column (Region_ID, Side, ID_Path, Region, Abbr, <condition>_<sample_name>).

  • region_ids (list): List of region IDs in the atlas.

Output:#

  • Saves the regional cell counts as a CSV file in the sample directory (./sample??/regional_stats/)

unravel.region_stats.rstats.calculate_regional_volumes(sample_path, atlas, region_ids, xy_res, z_res, condition, region_info_df, output_suffix='volumes', output_dir_name='regional_stats')[source]#

Calculate volumes for given regions in an atlas image.

Parameters:#

  • sample_path (Path): Path to the sample directory.

  • atlas (ndarray): 3D numpy array with the atlas image.

  • region_ids (list): List of region IDs to calculate volumes for.

  • xy_res (float): Resolution in the xy plane in microns.

  • z_res (float): Resolution in the z plane in microns.

  • condition (str): Name of the group.

  • region_info_df (DataFrame): DataFrame with region information (Region_ID, Side, ID_Path, Region, Abbr).

  • output_suffix (str): Suffix for the output CSV file name (default: ‘volumes’).

  • output_dir_name (str): Name of the subdirectory within each sample directory to save the output CSV (default: ‘regional_stats’).

Returns:#

  • regional_volumes_df (DataFrame): DataFrame with regional volumes in the last column (Region_ID, Side, ID_Path, Region, Abbr, <condition>_<sample_name>).

Output:#

  • Saves the regional volumes as a CSV file in the specified subdirectory within each sample directory.

unravel.region_stats.rstats.calculate_regional_densities(sample_path, regional_data_df, regional_volumes_df, condition, density_type='cell_densities', output_dir_name='regional_stats')[source]#

Calculate cell or label densities for each region in the atlas.

Parameters:#

  • sample_path (Path): Path to the sample directory.

  • regional_data_df (DataFrame): DataFrame with regional data (object counts or label volumes).

  • regional_volumes_df (DataFrame): DataFrame with regional volumes.

  • condition (str): Name of the group.

  • density_type (str): Type of density to calculate. Options: ‘cell_densities’ or ‘label_densities’.

Output:#

  • Saves the regional densities as a CSV file in the specified subdirectory within each sample directory.

  • Columns: Region_ID, Side, ID_path, Region, Abbr, <condition>_<sample>_numerator, <condition>_<sample>_denominator, <condition>_<sample>

  • The numerator column contains the original counts or label volumes

  • The denominator column contains the regional volumes

  • The last column contains the calculated densities (cells per mm^3 for cell_densities or % volume for label_densities).

unravel.region_stats.rstats.interleave_blank_slices(img)[source]#

Interleave blank slices in a 3D image to prevent cells from fusing across slices during counting.

Parameters:

img (-) – 3D numpy array with the image.

Returns:

3D numpy array with interleaved blank slices.

Return type:

  • img_interleaved (ndarray)

unravel.region_stats.rstats.calculate_regional_means(sample_path, intensity_img, atlas_img, condition, region_info_df, mean_type='mean', seg_img=None, output_dir_name='regional_stats')[source]#

Calculate region-wise mean intensity for each region or in segmentation mask within each region based on atlas region intensities.

Parameters:#

  • sample_path (Path): Path to the sample directory.

  • intensity_img (ndarray): 3D image used for intensity measurements.

  • atlas_img (ndarray): 3D atlas image in native space.

  • condition (str): Group name.

  • region_info_df (DataFrame): Region metadata.

  • mean_type (str): ‘mean’ or ‘mean_in_seg’

  • seg_img (ndarray or None): Segmentation mask required for mean_in_seg

  • output_dir_name (str): Name of the subdirectory within each sample directory to save the output CSV (default: ‘regional_stats’).

Returns:#

  • regional_means_df (DataFrame) with columns: Region_ID, Side, ID_path, Region, Abbr, <condition>_<sample_name>, <condition>_<sample_name>_support

  • Saves the regional means as a CSV file in the specified subdirectory within each sample directory. The CSV includes both the mean intensity values and the support (voxel counts) for each region.

unravel.region_stats.rstats.main()[source]#