:orphan: .. _ahelp_fat_mvm_scripter.py: ******************* fat_mvm_scripter.py ******************* .. contents:: :local: | .. code-block:: none * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ++ Jan, 2015 (ver 1.2). Written by PA Taylor. ++ Read in a data table file (likely formatted using the program fat_mvm_prep.py) and build an executable command for 3dMVM (written by G Chen) with a user-specified variable model. This should allow for useful repeated measures multivariate modeling of networks of data (such as from 3dNetCorr or 3dTrackID), as well as follow-up analysis of subconnections within the network. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + INPUTS: 1) Group data table text file (formatted as the *_MVMtbl.txt file output by fat_mvm_prep.py); contains subject network info (ROI parameter values) and individual variables. 2) Log file (formatted as the *_MVMprep.log file output by fat_mvm_prep.py) containing, among other things, a list of network ROIs and a list of parameters whose values are stored in the group data table. 3) A list of variables, whose values are also stored in the group data table, which are to be statistically modeled. The list may be provided either directly on the commandline or in a separate text file. Variable entries may now include interactions (using '*') among either a) two categorical variables, or b) one categorical and one quantitative variable. Running with the '*' symbol includes both the main effects and the interactions effects of the variables in the test. That is, A*B = A + B + A:B. Post hoc tests will now be run for both the main effects and the interactions, as well. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUTS 1a) A text file (named PREFIX_scri.tcsh) containing a script for running 3dMVM, using the prescribed variables along with each individual parameter. If N parameters are contained in the group data table and M variables selected for the model, then N network-wise ANOVAs for set of M+1 (includes the intercept) effects will be run. Additionally, if there are P ROIs comprising the network, then the generated script file is automatically set to perform PxM "post hoc" tests for the interactions of each ROI and each variable (if the variable is categorical, then there are actually more tests-- using one for each subcategory). This basic script can be run simply from the commandline: $ tcsh PREFIX_scri.tcsh after which ... 1b) ... a text file of the test results is saved in a file called "PREFIX_MVM.txt". Results in the default *MVM.txt file are grouped by variable, first producing a block of ANOVA output with three columns per variable: Chi-square value, degrees of freedom, and p-value. This is followed by a block of post hoc testing output with four columns: test value, t-statistic, degrees of freedom and p-value. See 3dMVM for more information. NB: The '1a' script is a *very basic starter/suggestion* for performing statistical tests. Feel free to modify it as you wish for your particular study. See '3dMVM -help' for more information. The ANOVA tests are performed on a network-wide level, and the posthoc tests followup with the same variables on a per-ROI level. The idea is: if there is a significant parameter-variable association on the network level (seen in the ANOVA results), it may be interesting to see if some particular ROIs are driving the effect (seen in the posthoc results). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + USAGE: $ fat_mvm_scripter.py --prefix=PREFIX \ --table=TABLE_FILE --log=LOG_FILE \ { --vars='VAR1 VAR2 VAR3 ...' | --file_vars=VAR_FILE } \ { --Pars='PAR1 PAR2 PAR3 ...' | --File_Pars=PAR_FILE } \ { --rois='ROI1 ROI2 ROI3 ...' | --file_rois=ROI_FILE } \ { --no_posthoc } { --NA_warn_off } -p, --prefix=PREFIX :output prefix for script file, which will then be called PREFIX_scri.tcsh, for ultimately creating a PREFIX_MVM.txt file of statistical results from 3dMVM. -t, --table=TABLE_FILE :text file containing columns of subject data, one subject per row, formatted as a *_MVMtbl.txt output by fat_mvm_prep.py (see that program's help for more description. -l, --log=LOG_FILE :file formatted according to fat_mvm_prep.py containing commented headings and also lists of cross-group ROIs and parameters. for which there were network matrices (potentially among other useful bits of information). See output of fat_mvm_prep.py for more info; NB: commented headings generally contain selection keywords, so pay attention to those if generating your own. -v, --vars='X Y Z ...' :one method for supplying a list of variables for the 3dMVM model. Names must be separated with whitespace. Categorical variables will be detected automatically *or* by the presence of nonnumeric characters in their columns; quantitative variables will be automatically put into a list for post hoc tests. -f, --file_vars=VAR_FILE :the second method for supplying a list of variables for 3dMVM. VAR_FILE is a text file with a single column of variable names. Using the VAR_FILE, you can specify subsets of categorical variables for GLT testing. The categories to be tested are entered on the same line as the variable, separated only by spaces. If specifying a subset for an inter- action, then put a space-separated comma between the lists of variables, if necessary (and if specifying categories only for the second of two categorical variables, then put a space-separated comma before the list). ----> ... using either variable entry format, an interaction can be specified using '*', where A*B = A + B + A:B. -P, --Pars='T S R ...' :one method for supplying a list of parameters (that is, the names of matrices) to run in distinct 3dMVM models. Names must be *or* separated with whitespace. Might be useful to get a smaller jungle of output results in cases where there are many matrices in a file, but only a few that are really cared about. -F, --File_Pars=PAR_FILE :the second method for supplying a list of parameters for 3dMVM runs. PAR_FILE is a text file with a single column of variable names. -r, --rois='A B C ...' :optional command to be able to select a subset of available network ROIs, if that's useful for some reason (NB: fat_mvm_prep.py should have already found *or* a set of ROIs with data across all the the subjects in the group, listed in the *MVMprep.log file; default would be using the entire list of ROIs in this log file as the network of ROIs). -R, --file_rois=ROI_FILE :the second method for supplying a (sub)list of ROIs for 3dMVM runs. ROI_FILE is a text file with a single column of variable names (see '--rois' for the default network selection). -s, --subnet_pref=SUBPR :if a subnetwork list of ROIs is used (see preceding two options), then one can give a name SUBPR for the new table file that is created. Otherwise, a default name from the required '--prefix=PREFIX' (or '-p PREFIX') option is used: PREFIX_SUBNET_MVMtbl.txt. -n, --no_posthoc :switch to turn off the automatic generation of per-ROI post hoc tests (default is to do them all). -N, --NA_warn_off :switch to turn off the automatic warnings as the data table is created. 3dMVM will excise subjects with NA values, so there shouldn't be NA values in columns you want to model. However, you might have NAs elsewhere in the data table that might be annoying to have flagged, so perhaps turning off warnings would then be useful. (Default is to warn.) -c, --cat_pair_off :switch to turn off the following test: by default, if a categorical variable undergoes posthoc testing, a GLT will be created for every pairwise combination of its categories, testing whether the given parameter is higher in one group than another (each category is assigned a +1 or -1, which is recorded in parentheses in the output label names). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Example: $ fat_mvm_scripter.py --file_vars=VARLIST.txt \ --log_file=study_MVMprep.log \ --table=study_MVMtbl.txt \ --prefix=study or, equivalently: $ fat_mvm_scripter.py -f VARLIST.txt -l study_MVMprep.log -t study_MVMtbl.txt -p study * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * This program is part of AFNI-FATCAT: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity. For citing the statistical approach, please use the following: Chen, G., Adleman, N.E., Saad, Z.S., Leibenluft, E., Cox, R.W. (2014). Applications of Multivariate Modeling to Neuroimaging Group Analysis: A Comprehensive Alternative to Univariate General Linear Model. NeuroImage 99:571-588. https://afni.nimh.nih.gov/pub/dist/HBM2014/Chen_in_press.pdf The first application of this network-based statistical approach is given in the following: Taylor PA, Jacobson SW, van der Kouwe AJW, Molteno C, Chen G, Wintermark P, Alhamud A, Jacobson JL, Meintjes EM (2014). A DTI-based tractography study of effects on brain structure associated with prenatal alcohol exposure in newborns. (HBM, in press) * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *