unravel.voxel_stats.z_score module#

Use vstats_z_score (zs) from UNRAVEL to z-score an atlas space image using a tissue mask and/or an atlas mask.

Prereqs:

vstats_prep for inputs [& seg_brain_mask for tissue masks]

Inputs:

  • atlas_space/<askterisk>_image.nii.gz relative to sample??

  • reg_inputs/autofl_50um_brain_mask.nii.gz (optional)

  • path/to/atlas_mask.nii.gz (optional)

Outputs:

  • <path/input_img>_z.nii.gz (float32) saved in the same directory as the input image.

Note

  • z-score = (img.nii.gz - mean pixel intensity in brain)/standard deviation of intensity in brain

Next commands for voxel-wise stats:

  • Aggregate atlas space IF images with utils_agg_files.

  • If analyzing whole brains, consider using vstats_whole_to_avg to average left and right hemispheres.

  • If using side-specific z-scoring, use vstats_hemi_to_avg to average the images.

  • Prepend condition names with utils_prepend.

  • Check images in FSLeyes (e.g., with vstats_check_fsleyes) and run vstats to perform voxel-wise stats.

Usage:#

vstats_z_score -i rel_path/img.nii.gz [–suffix z] [–tissue_mask reg_inputs/autofl_50um_brain_mask.nii.gz] [-amas path/atlas_mask.nii.gz] [-fri reg_outputs/autofl_50um_masked_fixed_reg_input.nii.gz] [-a atlas/atlas_CCFv3_2020_30um.nii.gz] [-d list of paths] [-p sample??] [-v]

Usage w/ an atlas mask:#

vstats_z_score -i ‘path/<asterisk>.nii.gz’ -amas path/atlas_mask.nii.gz

Usage w/ a tissue mask:#

vstats_z_score -i ‘atlas_space/<asterisk>.nii.gz’ -tmas reg_inputs/autofl_50um_brain_mask.nii.gz -a atlas/atlas_CCFv3_2020_30um.nii.gz

Usage w/ both masks for side-specific z-scoring:#

vstats_z_score -i ‘atlas_space/<asterisk>.nii.gz’ -tmas reg_inputs/autofl_50um_brain_mask.nii.gz -amas path/RH_mask.nii.gz -s RH_z –dirs <list of paths>

unravel.voxel_stats.z_score.parse_args()[source]#
unravel.voxel_stats.z_score.z_score(input_nii_path, mask_img, suffix)[source]#

Z-score a .nii.gz using a mask ndarray and save the output as a float32 .nii.gz.

Parameters:

  • img (-) – the ndarray to be z-scored.

  • mask (-) – the brain mask ndarray

  • suffix (-) – the suffix to append to the output filename

Outputs:

  • img_z.nii.gz (float32)

Returns:

the z-scored image

Return type:

  • z_scored_img (np.ndarray)

unravel.voxel_stats.z_score.tissue_mask_to_atlas_space(sample_path, tissue_mask_path, fixed_reg_input, atlas_path, pad_percent=0.25, verbose=False)[source]#

Warp a tissue mask to atlas space (e.g., for z-scoring).

Parameters:

  • sample_path (-) – Path to the sample directory.

  • tissue_mask_path (-) – Path to the tissue mask.

  • fixed_reg_input (-) – Name of the fixed image for registration.

  • atlas_path (-) – Path to the atlas.

Returns:

the tissue mask in atlas space.

Return type:

  • tissue_mask_img (np.ndarray)

unravel.voxel_stats.z_score.z_score_mask(sample_path, input_path, fixed_reg_input, atlas_path, tissue_mask_path=None, atlas_mask_path=None, pad_percent=0.25, verbose=False)[source]#

Combine tissue and atlas masks if both are provided, otherwise use whichever is available.

Parameters:

  • sample_path (-) – Path to the sample directory.

  • input_path (-) – Path to the image to be z-scored.

  • fixed_reg_input (-) – Name of the fixed image for registration.

  • atlas_path (-) – Path to the atlas.

  • tissue_mask_path (-) – Path to the tissue mask.

  • atlas_mask_path (-) – Path to the atlas mask.

Returns:

the combined mask image.

Return type:

  • mask_img (np.ndarray)

unravel.voxel_stats.z_score.main()[source]#