gen_cluster_table

Overview

This is a program to take a cluster dataset and make a table of
overlaps with respect to a given atlas.

This would be useful for reporting more information about cluster
results than, say, peak voxel or middle-voxel tables.  For usage
example, see:

  Highlight Results, Don't Hide Them: Enhance interpretation, reduce
  biases and improve reproducibility.
  Taylor PA, Reynolds RC, Calhoun V, Gonzalez-Castillo J, Handwerker
  DA, Bandettini PA, Mejia AF, Chen G (2023). Neuroimage 274:120138.
  https://pubmed.ncbi.nlm.nih.gov/37116766/

This program basically wraps around the useful 'whereami_afni' program.

auth    : PA Taylor (SSCC, NIMH, NIH, USA)
ver     : 1.3
revdate : Dec 1, 2025

Options

-input_clust IC    :(req) input dataset: the map of clusters, of which you
                    want to list out overlaps. Should be a single 3D volume.

-input_atlas IA    :(req) input dataset: the reference atlas, to be used
                    to identify/list overlaps from the cluster input

-prefix      PPP   :(req) output name for the table, so likely should end
                    with ".txt" or ".dat", for clarity

-min_olap_perc MOP :minimum overlap (as a percentage value) of cluster with
                    a given reference atlas region to be displayed in the
                    table. That is, if MOP% or more of the cluster overlaps
                    with a given region, then list that region.
                    (def: 10)
                    **See Notes, below, for more about this**

-strict            :by default, if no atlas region overlaps with the
                    '-min_olap_perc ..' threshold value, then the atlas
                    region with maximum overlap will be displayed still;
                    use this option, however, to strictly apply the threshold,
                    so no ROI would be shown.

-input_dat  ID     :by default, there is no info about the mean or sign of
                    a given cluster. With this option, users provide an extra
                    input dataset for that info. The ID dataset must be
                    on the same grid as the '-input_clust ..' dset.
                    Using this opt will add a column of mean values of the ID
                    data per cluster written using scientific notation
                    (see '-dat_column_as_sign' for alternative reporting).
                    NB: there is no check that the sign of values are
                    constant across each cluster, though that likely
                    should be the case.

-dat_column_as_sign :when adding an '-input_dat ..' dset, the added column
                    has signed mean values of the extra dataset within each
                    each cluster. This option changes the reporting to merely
                    be a text string reporting whether the cluster is positive
                    ('pos'), negative ('neg') or zero ('zero', which shouldn't
                    actually happen, typically).

-workdir     WWW   :specify the name of the temporary working directory
                    (which is created as a new subdirectory of the output
                    file location---do not include path info here, just a
                    simple name)

-no_clean          :do not remove working directory (def: remove it)

-echo              :very verbose output when running (for troubleshooting)

-help, -h          :display this meager help info

-ver               :display this program version

Notes

Note that the '-min_olap_perc ..' value specifies the fraction of the
*cluster* for displaying in the table. If your cluster is inherently
much, much larger than your atlas regions, this can mean that you
won't see many overlaps reported in the table.  In such a case, you
might want to lower the '-min_olap_perc ..' significantly.

Future work might be to have a different thresholding criterion,
perhaps based on the fraction of the *atlas* region overlap with the
cluster, for reporting.

Examples

1) Basic usage to create a table:
   gen_cluster_table                                  \
        -input_clust  Clust_mask+tlrc.HEAD            \
        -input_atlas  MNI_Glasser_HCP_v1.0.nii.gz     \
        -prefix       table_cluster_olap_glasser.txt

2) Basic usage to create a table, using a lower overlap fraction cut-off:
   gen_cluster_table                                  \
        -input_clust   Clust_mask+tlrc.HEAD           \
        -input_atlas   MNI_Glasser_HCP_v1.0.nii.gz    \
        -min_olap_perc 5                              \
        -prefix        table_cluster_olap _glasser.txt

3) Add in a supplementary dataset of data values, and report the values of
   its voxels within each cluster
   gen_cluster_table                                   \
        -input_clust   Clust_mask+tlrc.HEAD            \
        -input_atlas   MNI_Glasser_HCP_v1.0.nii.gz     \
        -min_olap_perc 5                               \
        -prefix        table_cluster_olap _glasser.txt \
        -input_dat     EffectEstimateData.nii.gz

4) Same as #3, but report just the sign of the extra data's mean values within
   each cluster:
   gen_cluster_table                                   \
        -input_clust   Clust_mask+tlrc.HEAD            \
        -input_atlas   MNI_Glasser_HCP_v1.0.nii.gz     \
        -min_olap_perc 5                               \
        -prefix        table_cluster_olap _glasser.txt \
        -input_dat     EffectEstimateData.nii.gz       \
        -dat_column_as_sign