AFNI program: PTA

Output of -help


             ================== Welcome to PTA ==================
               Program for Profile Tracking Analysis (PTA)
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Version 0.0.5, Oct 11, 2023
Author: Gang Chen (gangchen@mail.nih.gov)
Website - https://afni.nimh.nih.gov/gangchen_homepage
SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Introduction
------

 Profile Tracking Analysis (PTA) estimates nonlinear trajectories or profiles
 through smoothing splines. Currently the program PTA only works through a
 command-line scripting mode. Check the examples below: find one close to your
 specific scenario and use it as a template. The underlying theory is covered in
 the following paper:

 Chen, G., Nash, T.A., Cole, K.M., Kohn, P.D., Wei, S.-M., Gregory, M.D., 
 Eisenberg, D.P., Cox, R.W., Berman, K.F., Shane Kippenhan, J., 2021. Beyond 
 linearity in neuroimaging: Capturing nonlinear relationships with application to
 longitudinal studies. NeuroImage 233, 117891. 
 https://doi.org/10.1016/j.neuroimage.2021.117891

 To be able to run PTA, one needs to have the R packages "mgcv" installed with
 the following command at the terminal:

 rPkgsInstall -pkgs "mgcv"

 Alternatively you may install them in R:

 install.packages("mgcv")

 When a factor (e.g, groups, conditions) is involved, numerical coding is
 required in formulating the data information. See Examples 3 and 4. The
 following website provides some explanations regarding factor coding that
 might be useful for modeling formulation:

 https://stats.idre.ucla.edu/r/library/r-library-contrast-coding-systems-for-categorical-variables/

 There are two output files generated by PTA: one (with the affix -stat.txt)
 contains the information about the statistical evidence for various effects
 while the other (with the affix -prediction.txt) tabulates the predicted
 values and their standard errors which can be utilized to illustrate the
 inferred trajectories or trends (e.g., using graphical tools such as ggplot2
 in R). 


Example 1 --- simplest case: one group of subjects with a between-subject 
  quantitative variable that does not vary within subject. Analysis is 
  set up to model the trajectory or trend along age:

   PTA -prefix age         \
       -input data.txt     \
       -model 's(age)'     \
       -Y  height          \
       -prediction pred.txt                   

  The function 's(age)' indicates that 'age' is modeled via a smooth curve.
  No empty space is allowed in the model formulation.

   The file pred.txt lists all the explanatory variables (excluding lower-level variables
   such as subject) for prediction. The file should be in a data.frame format as below:

    age 
    10   
    12   
    14   
   
    20  
    22 
    24
    ...

   The age step in the above example is 2 years. To obtain smoother graphical appearance
   in plotted profiles, one can set the age values in pred.txt with a small grid sizer of, 
   for example, 0.5.

   The file data.txt stores the information for all the variables and input data in a
   data.frame format as below:

   Subj   age   height
   S1      24   175
   S2      14   163
    ...

   The subject labels in the above table can be characters or mixtures of characters
   and numbers, but they cannot be pure numbers.

  There will be two output files, one age-stat.txt and the other age-prediction.txt:
  the former shows the statistical evidence; the latter contains a predicted value
  for each age plus the associated uncertainty (standard error),  which can be
  plotted using tools such as ggplot2.
   

Example 2 --- Largely same as Example 1, but with 'age' as a within-subject 
  quantitative variable (varying within each subject). The model is now 
  specified by replacing the line of -model in Example 1 with the following 
  two lines:

          -model 's(age)+s(Subj,bs="re")'         \
          -vt Subj 's(Subj)'                      \

  The second term 's(Subj,bs="re")' in the model specification means that
  each subject is allowed to have a varying intercept or random effect ('re'). 
  To estimate the smooth trajectory through the option -prediction, the option
  -vt has to be included in this case to indicate the varying term (usually 
  subjects). That is, if prediction is desirable, one has to explicitly
  declare the variable (e.g., Subj) that is associated with the varying term
  (e.g., s(Subj)). No empty space is allowed in the model formulation and the
  the varying term. 

  The full script version is

   PTA -prefix age2                        \
       -input data.txt                     \
       -model 's(age)+s(Subj,bs="re")'     \
       -vt Subj 's(Subj)'                  \
       -prediction pred.txt                   

  All the rest remains the same as Example 1.
  

Example 3 --- two groups and one quantitative variable (age). The analysis is 
  set up to compare the trajectory or trend along age between the two groups,
  which are quantitatively coded as -1 and 1. For example, if the two groups
  are females and males, you can code females as -1 and males as 1. The following
  script applies to the situation when the quantitative variable age does not vary 
  within subject, 

  PTA -prefix age3a                      \
      -input data.txt                   \
      -model 's(age)+s(age,by=MvF)'     \
      -prediction pred.txt             

  The prediction table in the file data.txt contains the following structure:

  Subj  age grp MvsF
   S1   27   M   1
   S2   21   M   1
   S3   28   F  -1
   S4   18   F  -1
   ...

  The column grp above is not necessary for modeling, but it is included to
  be more indicative for the prediction values in the output file
  age3a-prediction.txt

  Similarly, the prediction file pred.txt looks like (set the age values with
  a small grid so that the graphical illustration would be smooth):

  age grp MvsF
  10   M   1
  12   M   1
  ...
  28   M   1
  30   M   1
  10   F  -1
  12   F  -1
  ...
  28   F  -1
  30   F  -1

  Note that the age values for prediction have a gap of 2 years: The a smaller
  the gap, the smoother the plotted predictions.

  On the other hand, go with the script below when the quantitative variable age
  varies within subject,

  PTA -prefix age3b                                   \
      -input data.txt                                \
      -model 's(age)+s(age,by=grp)+s(Subj,bs="re")'  \
      -vt  Subj 's(Subj)'                            \
      -prediction pred.txt
   

Example 4 --- This example demonstrates the situations where more than two
  levels are involved in a between-individual factor. Suppose that 
  three groups and one quantitative variable (age). The analysis is 
  set up to compare the trajectory or trend along age between the three groups,
  A, B and C that are quantitatively represented using dummy coding.

  PTA -prefix age4a                      \
      -input data.txt                   \
      -model 's(age)+s(age,by=AvC)+s(age,by=BvC)'     \
      -prediction pred.txt             

  The input table in the file data.txt contains the following structure:

  Subj   age grp AvsC BvC
   S1    27   A   1    0
   S2    21   A   1    0
   S3    17   B   0    1
   S4    24   B   0    1
   S5    28   C   0    0
   S6    18   C   0    0
  ...

  The column grp above is not necessary for modeling, but it is included to
  be more indicative for the prediction values in the output file
  age4a-prediction.txt

  On the other hand, go with the script below when the quantitative variable age
  varies within subject,

  PTA -prefix age4b                                   \
      -input data.txt                                \
      -model 's(age)+s(age,by=AvC)+s(age,by=BvC)+s(Subj,bs="re")'  \
      -vt  Subj 's(Subj)'                            \
      -prediction pred.txt
   

Example 5 --- Suppose tht we compare the profiles between two conditions 
  across space or time that is expreessed as a variable x. In this case
  profile estimation and statistical inference are separated into two steps.
  First, estimate the profile for each condition using Example 1 or Example 2
  as a template. Then, make inference about the contrast between the two
  conditions. Obtain the contrast at each value of x for each individual, and
  use the difference values as input. Specify the model as below if there are
  multiple individuals:

          -model 's(x)+s(id,bs="re")'         \
          -vt id 's(id)'                      \
  For one individual, change the model to

          -model 's(x)'                      \


Options in alphabetical order:
------------------------------

   -dbgArgs: This option will enable R to save the parameters in a
         file called .PTA.dbg.AFNI.args in the current directory
          so that debugging can be performed.

   -h: this help message

   -help: this help message

   -input file: input file in a table format (sames as the data frame structure of long format in R. Use the first row to specify the column names. The subject column, if applicable, should not be purely numbers. On the other hand, factors (groups, tasks) should be numerically coded using convenient coding methods such as deviation or dummy coding. 

   -interactive: Currently unavailable.

   -model FORMULA: Specify the model formulation through multilevel smoothing splines
         expression FORMULA with more than one variable has to be surrounded within
         (single or double) quotes. Variable names in the formula should be
         consistent with the ones used in the header of the input file.
         The nonlinear trajectory is specified through the expression of s(x,k=?)
         where s() indicates a smooth function, x is a quantitative variable with
         which one would like to trace the trajectory and k is the number of smooth
         splines (knots). The default (when k is missing) for k is 10, which is good
         enough most of the time when there are more than 10 data points of x. When
         there are less than 10 data points of x, choose a value of k slightly less
         than the number of data points.

   -prediction TABLE: Provide a data table so that predicted values could be generated for
graphical illustration. Usually the table should contain similar structure as the input
file except that columns for those varying smoothing terms (e.g., subject) and response
variable (i.e., Y) should not be included. Try to specify equally-spaced values with a small
for the quantitative variable of modeled trajectory (e.g., age) so that smooth curves could
be plotted after the analysis. See Examples in the help for a couple of specific tables used
for predictions.

   -prefix PREFIX: Prefix for output files. 

   -show_allowed_options: list of allowed options

   -verb VERB: VERB is an integer specifying verbosity level.
             0 for quiet (Default). 1 or more: talkative.

   -vt var formulation: This option is for specifying varying smoothing terms. Two components
         are required: the first one 'var' indicates the variable (e.g., subject) around
         which the smoothing will vary while the second component specifies the smoothing
         formulation (e.g., s(age,subject)). When there is no varying smoothing terms (e.g.,
         no within-subject variables), do not use this option.

   -Y var_name: var_name is used to specify the column name that is designated as
        as the response/outcome variable. The default (when this option is not
        invoked) is 'Y'.

  Gang Chen   (SSCC/NIMH/NIH)
This page auto-generated on Thu Oct 31 09:44:54 PM EDT 2024