AFNI program: gen_cluster_table.py

Output of -help

Overview ~1~

This program is for making a cluster overlap table. The user inputs a
map of clusters (each defined by a set of voxels with integer values)
and a reference atlas (preferably one with region labels). Then this
program writes out a multicolumn table listing relevant overlaps that
each cluster has, relative to the atlas.

auth = PA Taylor (SSCC, NIMH, NIH, USA)

------------------------------------------------------------------------

Usage ~1~

-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_perc_clust MFC :this parameter defines the minimum percent of a
                 cluster that must be filled by a reference atlas
                 region to be included in the table.
                 That is, if MFC% or more of the cluster overlaps with
                 a given region, then that region will be listed.
                 (def: 10.0) 
                 **See Notes, below, for more about this**

-min_perc_atlas MFA :this parameter defines the minimum percent of a
                 reference atlas region that must be filled by a cluster 
                 to be included in the table.
                 That is, if MFA% or more of the atlas region overlaps
                 with a given cluster, then that region will be listed.
                 (def: 25.0) 
                 **See Notes, below, for more about this**

-olap_logic OL  :specify the logical operator that should be used to 
                 combine the cluster- and atlas-filling conditions.
                 Choices come from the following: and, or.
                 (def: OR) 

-strict_fill_clust SFC :by default, if no atlas region overlaps with
                 the '-min_perc_clust ..' threshold value, then the
                 atlas region with maximum overlap will still be
                 displayed by default; however, to strictly apply the
                 threshold, so that no ROI would be shown in that
                 case, use this option with 'No'.  (def:
                 No)

-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_col_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.  name of the
                 input dataset

-dat_col_as_sign DCAS 
                :if using '-input_dat ..', should the results be output
                 as a simple string value of 'pos', 'neg' or 'zero'?
                 If that option is not chosen, then the input_dat is 
                 reported numerically as the mean value of the data 
                 in the cluster, using scientific notation
                 (def: No) 

-sort_hdr_col SHC :for each cluster, outputs are sorted by one of these
                 columns:
                     Clust_perc, Atlas_perc, Atlas_region
                 The user can specify one of those for sorting.
                 (def: Clust_perc) 

-sort_hdr_rev SHR :when sorting the column values in the cluster table, 
                 should the sorting be reversed?  That is likely useful when
                 sorting by a column of number values, in order to have the
                 larger numbers higher up in the table
                 (def: Yes) 

-workdir WD     :working directory name, without path; the working dir
                 will be subdirectory of the output location
                 (def: name with random chars)

-do_clean DC    :state whether to clean up any intermediate files;
                 allowed values are:  Yes, 1, No, 0
                 (def: 'Yes')

-do_log         :add this opt to turn on making a text log of all the
                 shell commands that are run when this program is
                 executed.  Mainly for debugging purposes.

-help, -h       :display program help file

-hist           :display program history

-ver            :display program version number

-verb  VVV      :control verbosity (def: 1)

-show_valid_opts :show valid options for this program

------------------------------------------------------------------------

Notes ~1~

Thresholds for filling clusters and atlas regions ~2~

  Probably the biggest choice that users will have to make when using
  this programs is deciding what the cut-off value will be for "enough"
  overlap to be counted in the cluster report table.  There are two
  primary parameters for specifying this:

    '-min_perc_clust ..' : what percentage of a cluster should be filled
                           by a given atlas region to be included

    '-min_perc_atlas ..' : what percentage of an atlas region should be 
                           filled by a given cluster to be included

  Having both of these parameters available is useful particularly when
  clusters are much larger than atlas regions, or vice versa.  (An
  earlier version of this program only had the cluster-fill condition,
  and it became obvious that the atlas-based one would be necessary to
  add.)  There are default values for each (min_perc_clust = 10.0%, 
  and min_perc_atlas = 25.0%), which seem a reasonable starting point,
  but these were not chosen for deep reasons. Users should choose what 
  makes most sense for their data.

  There is an important secondary parameter related to the above options:

    '-olap_logic ..'     : should the cluster- and atlas-filling conditions
                           be applied with 'or' logic (so, only one condition
                           needs to be met) for an overlap to be included
                           in the table, or with 'and' logic (so both
                           conditions need to be met simultaneously).

  The default logic is 'OR'.  Again, users may have their own
  preferences for their study design and reporting.


Specifying individual volumes ~2~

  Sometimes one of the input datasets will have more than one
  volume. For example, the CHARM atlas has 6 volumes in it.  In such
  cases, the user must specify individual volumes using subbrick
  selectors.  

  The subbrick selector syntax is used/allowed throughout the AFNI
  codebase, putting the desired index of the volume within square
  brackets at the end of the filename. Note that index counting starts
  at 0, like in C and Python. Importantly, in many cases of scripting,
  the square brackets must themselves be wrapped in quotation
  marks. For example, this is how one would specify the first volume
  in the dset:
   
    DSET"[0]"

  In some cases, datasets have labels attached to each subbrick. This
  is particularly common in statistics volumes output by AFNI.  These
  can also be used within the square brackets to select a particular
  volume, in place of the integer index.  For example, if you want to
  specify the Full_Fstat or 'vis#0_Coef' beta coefficient from a
  model, you could use these, respectively:

    DSET"[Full_Fstat]"
    DSET"[vis#0_Coef]"

  To know how many volumes are in a dset, you can run:
   
    3dinfo -nv DSET

  To know what the labels are within a dset, you can run:

    3dinfo -label DSET

  Note that labels by default are separately by the '|' symbol.
  Additionally, you can just run one of these:

    3dinfo DSET
    3dinfo -verb DSET

  ... and you will see the per-volume information (if it was a dset
  created by AFNI), including subbrick labels per volume.


Column labels and runtime text ~2~

  As the program runs, it displays the 'olap count', which is how many
  atlas regions were found to overlap each cluster, applying the given
  thresholds/criteria.

  The default columns are:

    Clust         : the cluster ID (int value)
    Clust_vol     : the cluster's volume in units of mm**3 (as calculated
                    on its original dset grid)
    Clust_perc    : percentage of the cluster filled by the overlapping
                    atlas region (as calculated on the atlas dset grid)
    Atlas_perc    : percentage of the atlas region filled by the overlapping
                    cluster (as calculated on the atlas dset grid)
    Atlas_region  : string label for the atlas region (if the atlas dset
                    had a labeltable and/or atlas points list); otherwise,
                    the integer value of the atlas region
  
  Additionally, the user can use the '-input_dat' option to input
  another dset, whose mean value is calculated within the cluster.
  This input_dat dset must have the same grid as input_clust, and the
  mean is calculated on that grid.  If this option has been used, then
  an additional column of output is provided:

    Clust_dat     : either the mean value of the input_dat dset within
                    the cluster, or if the '-dat_col_as_sign ..' option
                    is used, then a text string describing the sign of the
                    mean input_dat value: 'pos', 'neg' or 'zero'.

------------------------------------------------------------------------

Examples ~1~

 1. Make cluster overlap table using basic/default parameters:

    gen_cluster_table.py                                \
        -input_clust      Clust+tlrc.HEAD               \
        -input_atlas      MNI_Glasser_HCP_v1.0.nii.gz   \
        -prefix           Clust_01_report.dat

 2. Make cluster overlap table using different cluster and altas
    region fill thresholds:

    gen_cluster_table.py                                \
        -input_clust      Clust+tlrc.HEAD               \
        -input_atlas      MNI_Glasser_HCP_v1.0.nii.gz   \
        -min_perc_clust   20.0                          \
        -min_perc_atlas   50.0                          \
        -prefix           Clust_02_report.dat

 3. Include another dataset, to report the sign of the cluster
    (as a string):

    gen_cluster_table.py                                \
        -input_clust      Clust+tlrc.HEAD               \
        -input_atlas      MNI_Glasser_HCP_v1.0.nii.gz   \
        -input_dat        stats.beta_values.nii.gz      \
        -dat_col_as_sign  Yes                           \
        -prefix           Clust_03_report.dat

 4. User sub-brick selectors for various datasets:

    gen_cluster_table.py                                         \
        -input_clust      Clust+tlrc.HEAD"[3]"                   \
        -input_atlas      CHARM_in_NMT_v2.1_sym_05mm.nii.gz"[4]" \
        -input_dat        stats.beta_values.nii.gz"[2]"          \
        -prefix           Clust_04_report.dat
This page auto-generated on Tue Jun 2 02:42:01 PM EDT 2026