update statmap doc and scripts

courtois-neuromod · Jan 17, 2025 · 266bedc · 266bedc
1 parent 6bb10bd
commit 266bedc
Show file tree

Hide file tree

Showing 7 changed files with 45 additions and 45 deletions.
diff --git a/code/descriptive/README.md b/code/descriptive/README.md
@@ -36,18 +36,18 @@ python rank_img_perVox.py --data_dir="${DATADIR}" --sub="01"
 ```
 
 **Input**:
-- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stats-imageBetas_desc-zscore_statseries.h5``, the GLM single beta scores organized in groups whose key is the image name (e.g., 'camel_02s').
-- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stats-trialBetas_desc-zscore_statseries.h5``, the GLM single beta scores organized in nested groups whose key is the session number and sub-key is the run number.
+- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stat-imageBetas_desc-zscore_statseries.h5``, the GLM single beta scores organized in groups whose key is the image name (e.g., 'camel_02s').
+- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stat-trialBetas_desc-zscore_statseries.h5``, the GLM single beta scores organized in nested groups whose key is the session number and sub-key is the run number.
 - ``sub-{sub_num}_task-things_space-T1w_label-brain_desc-unionNonNaN_mask.nii``, the functional mask used to vectorize the brain beta scores.
-- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stats-noiseCeilings_statmap.nii.gz``, the subject's noise ceiling map derived from the THINGS task.
-- ``fLoc/floc.rois/sub-{sub_num}/rois/task-derived/f"sub-{sub_num}_task-floc_space-T1w_stats-tscores_contrast-*_roi-*cutoff-*_nvox-*_fwhm-5_ratio-0.3_desc-unsmooth_mask.nii.gz``, ROI masks derived from the fLoc task (``sub-06_task-floc_space-T1w_stats-noiseCeil_contrast-*_roi-*_cutoff-*_nvox-100_fwhm-3_mask.nii.gz`` for ``sub-06`` who did not complete fLoc).
+- ``sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stat-noiseCeilings_statmap.nii.gz``, the subject's noise ceiling map derived from the THINGS task.
+- ``fLoc/floc.rois/sub-{sub_num}/rois/task-derived/f"sub-{sub_num}_task-floc_space-T1w_stat-tscores_contrast-*_roi-*cutoff-*_nvox-*_fwhm-5_ratio-0.3_desc-unsmooth_mask.nii.gz``, ROI masks derived from the fLoc task (``sub-06_task-floc_space-T1w_stat-noiseCeil_contrast-*_roi-*_cutoff-*_nvox-100_fwhm-3_mask.nii.gz`` for ``sub-06`` who did not complete fLoc).
 
 
 **Output**:
-- ``sub-{sub_num}_task-things_space-T1w_stats-betas_desc-{perImage, perTrial}_statseries.npy``, an array of (image-wise or trial-wise) betas concatenated for the entire dataset.
+- ``sub-{sub_num}_task-things_space-T1w_stat-betas_desc-{perImage, perTrial}_statseries.npy``, an array of (image-wise or trial-wise) betas concatenated for the entire dataset.
 - ``sub-{sub_num}_task-things_desc-{perImage, perTrial}_labels.npy``, an array of corresponding image labels for the beta scores.
-- ``sub-{sub_num}_task-things_space-T1w_stats-ranks_desc-{perImage, perTrial}_statseries.npy``, an array of ranked indices that index image labels and beta scores. Within each column (voxel), indices are ordered according to the magnitude of their (trial-wise or image-wise) beta score, from smallest to largest. These ranks can be used to index image labels and beta scores in the ``*labels.npy`` and the ``*stats-betas_desc-{perImage, perTrial}_statseries.npy`` arrays. E.g., the last 10 ranks of the 3rd column (voxel) index the image labels with the highest beta scores within the 3rd voxel inside the brain mask.
-- For each functional ROI identified with the fLoc task: ``sub-{sub_num}_task-things_space-T1w_{roi_name}_cutoff-{noiseceil_thresh}_nvox-{voxel_count}_stats-{ranks, betas, noiseCeilings}_desc-{perTrial, perImage}_statseries.npy``, the betas, ranked indices and noise ceilings of the 50 voxels with the highest noise ceilings within each ROI mask.
+- ``sub-{sub_num}_task-things_space-T1w_stat-ranks_desc-{perImage, perTrial}_statseries.npy``, an array of ranked indices that index image labels and beta scores. Within each column (voxel), indices are ordered according to the magnitude of their (trial-wise or image-wise) beta score, from smallest to largest. These ranks can be used to index image labels and beta scores in the ``*labels.npy`` and the ``*stat-betas_desc-{perImage, perTrial}_statseries.npy`` arrays. E.g., the last 10 ranks of the 3rd column (voxel) index the image labels with the highest beta scores within the 3rd voxel inside the brain mask.
+- For each functional ROI identified with the fLoc task: ``sub-{sub_num}_task-things_space-T1w_{roi_name}_cutoff-{noiseceil_thresh}_nvox-{voxel_count}_stat-{ranks, betas, noiseCeilings}_desc-{perTrial, perImage}_statseries.npy``, the betas, ranked indices and noise ceilings of the 50 voxels with the highest noise ceilings within each ROI mask.
 
 
 ------------------
@@ -66,19 +66,19 @@ python beta_scaling.py --data_dir="${DATADIR}" --perImg --sub="01"
 ```
 
 **Input**:
-- ``sub-{sub_num}_task-things_space-T1w_stats-betas_desc-{perImage, perTrial}_statseries.npy``, an array of (image-wise or trial-wise) betas concatenated for the entire dataset (generated in Step 2 above).
+- ``sub-{sub_num}_task-things_space-T1w_stat-betas_desc-{perImage, perTrial}_statseries.npy``, an array of (image-wise or trial-wise) betas concatenated for the entire dataset (generated in Step 2 above).
 - ``sub-{sub_num}_task-things_desc-{perImage, perTrial}_labels.npy``, the betas' corresponding image labels (generated in Step 2 above).
 - ``THINGS/glmsingle/sub-{sub_num}/glmsingle/input/sub-{sub_num}_task-things_space-T1w_label-brain_desc-unionNonNaN_mask.nii``, the functional brain mask used to generate the beta arrays.
-- ``fLoc/rois/sub-{sub_num}/rois/task-derived/sub-{sub_num}_task-floc_space-T1w_stats-tscores_contrast-{face_roi-FFA, face_roi-OFA, scene_roi-MPA, scene_roi-OPA, scene_roi-PPA}_cutoff-*_desc-unsmooth_mask.nii.gz``, masks of above-threshold voxels (based on fLoc contrasts) contained within ROI masks from the Kanwisher group.
-- ``fLoc/rois/sub-{sub_num}/rois/task-derived/sub-{sub_num}_task-floc_space-T1w_stats-tscores_contrast-{faces, bodies, places}_cutoff-3.72_desc-unsmooth_mask.nii.g``, masks of above-threshold voxels (t > 3.72) on fLoc contrasts (faces, bodies and places) contained within their respective set of Kanwisher parcels (face, body or scene).
-- ``fLoc/rois/sub-{sub_num}/glm/sub-{sub_num}_task-floc_space-T1w_model-GLM_stats-tscores_contrast-{faces, bodies, places}_desc-unsmooth_statseries.nii.gz``, t-scores for the faces, bodies and places contrasts derived from the fLoc task (NSD-style contrasts).
+- ``fLoc/rois/sub-{sub_num}/rois/task-derived/sub-{sub_num}_task-floc_space-T1w_stat-tscores_contrast-{face_roi-FFA, face_roi-OFA, scene_roi-MPA, scene_roi-OPA, scene_roi-PPA}_cutoff-*_desc-unsmooth_mask.nii.gz``, masks of above-threshold voxels (based on fLoc contrasts) contained within ROI masks from the Kanwisher group.
+- ``fLoc/rois/sub-{sub_num}/rois/task-derived/sub-{sub_num}_task-floc_space-T1w_stat-tscores_contrast-{faces, bodies, places}_cutoff-3.72_desc-unsmooth_mask.nii.g``, masks of above-threshold voxels (t > 3.72) on fLoc contrasts (faces, bodies and places) contained within their respective set of Kanwisher parcels (face, body or scene).
+- ``fLoc/rois/sub-{sub_num}/glm/sub-{sub_num}_task-floc_space-T1w_model-GLM_stat-tscores_contrast-{faces, bodies, places}_desc-unsmooth_statmap.nii.gz``, t-scores for the faces, bodies and places contrasts derived from the fLoc task (NSD-style contrasts).
 - ``fLoc/rois/sub-{sub_num}/rois/from_atlas/sub-{sub_num}_parcel-kanwisher_space-T1w_contrast-{c[0]}_mask.nii``, group-derived parcels from the Kanwisher group warped to single-subject space.
 - ``retinotopy/prf/sub-{sub_num}/rois/sub-{sub_num}_task-retinotopy_space-T1w_res-func_model-npythy_label-{V1, V2, V3}_desc-nn_mask.nii.gz``, masks of visual areas V1, V2 and V3 derived from retinotopy data and group priors with NeuroPythy.
-- ``THINGS/glmsingle/sub-{sub_num}/glmsingle/output/sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stats-noiseCeilings_statmap.nii.gz``, maps of voxelwise noise ceilings derived from the THINGS task.
+- ``THINGS/glmsingle/sub-{sub_num}/glmsingle/output/sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_stat-noiseCeilings_statmap.nii.gz``, maps of voxelwise noise ceilings derived from the THINGS task.
 
 
 **Output**:
-``sub-{sub_num}_task-things_space-T1w_stats-tSNE_label-visualROIs_desc-{perImage, perTrial}_statseries.npz``, a collection of numpy arrays that contain t-SNE components (and their corresponding labels) derived from voxel beta scores (per trial or per image) contained within the following visual ROIs:
+``sub-{sub_num}_task-things_space-T1w_stat-tSNE_label-visualROIs_desc-{perImage, perTrial}_statseries.npz``, a collection of numpy arrays that contain t-SNE components (and their corresponding labels) derived from voxel beta scores (per trial or per image) contained within the following visual ROIs:
 - face-sensitive regions FFA and OFA
 - scene-sensitive regions PPA, MPA and OPA
 - low-level visual areas V1, V2 and V3

diff --git a/code/descriptive/beta_scaling.py b/code/descriptive/beta_scaling.py
@@ -102,7 +102,7 @@ def get_betas(args):
     )
     desc = "perImage" if args.perImg else "perTrial"
     betas = np.load(
-        f"{beta_path}/sub-{sub_num}_task-things_space-T1w_stats-betas_"
+        f"{beta_path}/sub-{sub_num}_task-things_space-T1w_stat-betas_"
         f"desc-{desc}_statseries.npy",
         allow_pickle=True,
     )
@@ -144,7 +144,7 @@ def get_floc_masks(args, things_mask):
     floc_roi_masks = []
     for rname in floc_rois:
         rpath = glob.glob(
-            f"{floc_masks_path}/sub-{sub_num}_task-floc_space-T1w_stats-"
+            f"{floc_masks_path}/sub-{sub_num}_task-floc_space-T1w_stat-"
             f"tscores_contrast-{rname}_cutoff-*_desc-unsmooth_mask.nii.gz"
         )
         assert len(rpath) == 1
@@ -155,7 +155,7 @@ def get_floc_masks(args, things_mask):
     floc_contrasts = ["faces", "places", "bodies"]
     floc_contrast_masks = [
         apply_mask(nib.load(
-            f"{floc_masks_path}/sub-{sub_num}_task-floc_space-T1w_stats-"
+            f"{floc_masks_path}/sub-{sub_num}_task-floc_space-T1w_stat-"
             f"tscores_contrast-{cname}_cutoff-3.72_desc-unsmooth_mask.nii.gz",
         ), things_mask).astype(bool) for cname in floc_contrasts
     ]
@@ -191,8 +191,8 @@ def get_floc_lowthesh(args, things_mask):
         # threshold subject contrast from fLoc task (NSD contrast)
         dmap = nib.load(
             f"{args.data_dir}/fLoc/rois/sub-{sub_num}/glm/"
-            f"sub-{sub_num}_task-floc_space-T1w_model-GLM_stats-tscores_"
-            f"contrast-{c[1]}_desc-unsmooth_statseries.nii.gz"
+            f"sub-{sub_num}_task-floc_space-T1w_model-GLM_stat-tscores_"
+            f"contrast-{c[1]}_desc-unsmooth_statmap.nii.gz"
         )
         thresh_dmap = nib.nifti1.Nifti1Image(
             (dmap.get_fdata() > 2.5).astype("int32"),
@@ -252,7 +252,7 @@ def get_noiseCeil_mask(args, things_mask):
     flat_noiseceil = apply_mask(nib.load(
         f"{args.data_dir}/THINGS/glmsingle/sub-{sub_num}/glmsingle/output/"
         f"sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_"
-        "stats-noiseCeilings_statmap.nii.gz",
+        "stat-noiseCeilings_statmap.nii.gz",
     ), things_mask)
 
     nc_thresh = np.sort(flat_noiseceil)[-args.nc_cutoff]
@@ -340,7 +340,7 @@ def save_tsne(args, img_idx, mask_list, tsne_results, nvox_list):
     desc = "perImage" if args.perImg else "perTrial"
     out_path = Path(
         f"{args.data_dir}/THINGS/glmsingle/sub-{args.sub_num}/descriptive/"
-        f"sub-{args.sub_num}_task-things_space-T1w_stats-tSNE_label-visualROIs_"
+        f"sub-{args.sub_num}_task-things_space-T1w_stat-tSNE_label-visualROIs_"
         f"desc-{desc}_statseries.npz"
     )
 

diff --git a/code/descriptive/rank_img_perVox.py b/code/descriptive/rank_img_perVox.py
@@ -64,14 +64,14 @@ def rank_roi_betas(
     flat_noiseceil = apply_mask(nib.load(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/glmsingle/output/"
         f"sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_"
-        "stats-noiseCeilings_statmap.nii.gz",
+        "stat-noiseCeilings_statmap.nii.gz",
     ), things_mask)
 
     # list ROI masks from fLoc
     roi_mask_list = sorted(
         glob.glob(
             f"{data_dir}/fLoc/rois/sub-{sub_num}/rois/task-derived/"
-            f"sub-{sub_num}_task-floc_space-T1w_stats-tscores_contrast-*_roi-*_"
+            f"sub-{sub_num}_task-floc_space-T1w_stat-tscores_contrast-*_roi-*_"
             "cutoff-*_nvox-*_fwhm-5_ratio-0.3_desc-unsmooth_mask.nii.gz",
         )
     )
@@ -80,7 +80,7 @@ def rank_roi_betas(
         roi_mask_list = sorted(
             glob.glob(
                 f"{data_dir}/fLoc/rois/sub-{sub_num}/rois/task-derived/"
-                f"sub-{sub_num}_task-floc_space-T1w_stats-noiseCeil_contrast-*"
+                f"sub-{sub_num}_task-floc_space-T1w_stat-noiseCeil_contrast-*"
                 f"_roi-*_cutoff-*_nvox-100_fwhm-3_mask.nii.gz",
             )
         )
@@ -109,19 +109,19 @@ def rank_roi_betas(
         np.save(
             f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
             f"sub-{sub_num}_task-things_space-T1w_{roi_name}_cutoff-{tval}_"
-            f"nvox-{roi_cutoff}_stats-ranks_{desc}_statseries.npy",
+            f"nvox-{roi_cutoff}_stat-ranks_{desc}_statseries.npy",
             roi_idx,
         )
         np.save(
             f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
             f"sub-{sub_num}_task-things_space-T1w_{roi_name}_cutoff-{tval}_"
-            f"nvox-{roi_cutoff}_stats-betas_{desc}_statseries.npy",
+            f"nvox-{roi_cutoff}_stat-betas_{desc}_statseries.npy",
             roi_bloc,
         )
         np.save(
             f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
             f"sub-{sub_num}_task-things_space-T1w_{roi_name}_cutoff-{tval}_"
-            f"nvox-{roi_cutoff}_stats-noiseCeilings_{desc}_statseries.npy",
+            f"nvox-{roi_cutoff}_stat-noiseCeilings_{desc}_statseries.npy",
             roi_NCs,
         )
 
@@ -142,7 +142,7 @@ def rank_imgs_per_vox(
     subj_h5file = h5py.File(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/glmsingle/output/"
         f"sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_"
-        "stats-imageBetas_desc-zscore_statseries.h5",
+        "stat-imageBetas_desc-zscore_statseries.h5",
         "r",
     )
 
@@ -173,7 +173,7 @@ def rank_imgs_per_vox(
     )
     np.save(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
-        f"sub-{sub_num}_task-things_space-T1w_stats-betas_desc-perImage_"
+        f"sub-{sub_num}_task-things_space-T1w_stat-betas_desc-perImage_"
         "statseries.npy",
         beta_block,
     )
@@ -198,7 +198,7 @@ def rank_imgs_per_vox(
 
     np.save(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
-        f"sub-{sub_num}_task-things_space-T1w_stats-ranks_desc-perImage_"
+        f"sub-{sub_num}_task-things_space-T1w_stat-ranks_desc-perImage_"
         "statseries.npy",
         beta_idx,
     )
@@ -283,7 +283,7 @@ def rank_imgs_per_vox_perTrial(
     subj_h5file = h5py.File(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/glmsingle/output/"
         f"sub-{sub_num}_task-things_space-T1w_model-fitHrfGLMdenoiseRR_"
-        "stats-trialBetas_desc-zscore_statseries.h5",
+        "stat-trialBetas_desc-zscore_statseries.h5",
         "r",
     )
 
@@ -301,7 +301,7 @@ def rank_imgs_per_vox_perTrial(
     )
     np.save(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
-        f"sub-{sub_num}_task-things_space-T1w_stats-betas_desc-perTrial_"
+        f"sub-{sub_num}_task-things_space-T1w_stat-betas_desc-perTrial_"
         "statseries.npy",
         beta_block,
     )
@@ -315,7 +315,7 @@ def rank_imgs_per_vox_perTrial(
 
     np.save(
         f"{data_dir}/THINGS/glmsingle/sub-{sub_num}/descriptive/"
-        f"sub-{sub_num}_task-things_space-T1w_stats-ranks_desc-perTrial_"
+        f"sub-{sub_num}_task-things_space-T1w_stat-ranks_desc-perTrial_"
         "statseries.npy",
         beta_idx,
     )

diff --git a/code/glmsingle/GLMsingle_betasPerImg.py b/code/glmsingle/GLMsingle_betasPerImg.py
@@ -253,7 +253,7 @@ def average_betas_perImg(data_dir, sub_num, rm_blanks=False, zbetas=False):
     zname = 'desc-zscore_' if zbetas else ''
     subj_h5file = h5py.File(
         f"{data_dir}/glmsingle/sub-{sub_num}/glmsingle/output/sub-{sub_num}_"
-        f"task-things_space-T1w_model-fitHrfGLMdenoiseRR_stats-imageBetas_{zname}statseries.h5",
+        f"task-things_space-T1w_model-fitHrfGLMdenoiseRR_stat-imageBetas_{zname}statseries.h5",
         'w',
     )
     subj_h5file = avg_beta(

diff --git a/code/glmsingle/GLMsingle_betasPerTrial.py b/code/glmsingle/GLMsingle_betasPerTrial.py
@@ -79,7 +79,7 @@ def compile_betas_hdf5(data_dir, sub_num, zbetas=False):
     zname = 'desc-zscore_' if zbetas else ''
     subj_h5file = h5py.File(
         f"{data_dir}/sub-{sub_num}/glmsingle/output/sub-{sub_num}_task-things_"
-        f"space-T1w_model-fitHrfGLMdenoiseRR_stats-trialBetas_{zname}statseries.h5",
+        f"space-T1w_model-fitHrfGLMdenoiseRR_stat-trialBetas_{zname}statseries.h5",
         'w',
     )
 

diff --git a/code/glmsingle/GLMsingle_noiseceilings.py b/code/glmsingle/GLMsingle_noiseceilings.py
@@ -269,6 +269,6 @@ def compute_noise_ceiling_nsd(things_dir, mat_file, sub_num, n=3, rm_blanks=Fals
     nc_nii = unmask(nc_arr, clean_mask)  # remove NaN voxels
     outpath_nii = Path(
         f"{data_path}/output/sub-{sub_num}_task-things_"
-        "space-T1w_model-fitHrfGLMdenoiseRR_stats-noiseCeilings_statmap.nii.gz"
+        "space-T1w_model-fitHrfGLMdenoiseRR_stat-noiseCeilings_statmap.nii.gz"
     )
     nib.save(nc_nii, outpath_nii)