:orphan: .. _ahelp_gen_cluster_table.py: ******************** gen_cluster_table.py ******************** .. contents:: :local: | Overview ======== .. code-block:: none 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 ===== .. code-block:: none -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 ===== Thresholds for filling clusters and atlas regions +++++++++++++++++++++++++++++++++++++++++++++++++ .. code-block:: none 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 +++++++++++++++++++++++++++++ .. code-block:: none 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 ++++++++++++++++++++++++++++++ .. code-block:: none 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 ======== .. code-block:: none 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