# This file contains some examples of basic AFNI commands.  Going
# through these can help users have a better feel for running AFNI
# programs and using the programs (that is the hope, at least!). This
# is a somewhat self-guided tour, or one to go through in a Bootcamp.
# There are some pieces of information the users themselves are asked
# to provide. Enjoy!

# And if you find these examples useful, you might enjoy the
# <<Jazzercise>> examples that are also distributed in afni_handouts
# (likely in a subdirectory called 'reference/'). The full Jazzercise
# set comprises the following files:
#     
#     afni19_jazz.pdf         : questions to work through
#     afni19_jazz_hints.pdf   : some useful pointers for where to find 
#                               solution hints, if needed
#     afni19_jazz_answers.pdf : the ultimate answer guide; OK to look at,
#                               certainly, but worth trying on your own
#                               first and using the "hints"

# ----------------------------------------------------------------------------

# First, we note a couple things about loading+viewing data in the
# AFNI GUI.  We will run these from the following Bootcamp directory:

  cd ~/AFNI_data6/FT_analysis/FT.results/

  # open current and sub-directories recursively:

  afni -R -all_dsets

  # then select: Underlay -> pb00.FT.r01+orig
  #              Overlay  -> MNI152_2009_template.nii.gz
  
  # What do you notice?  Why is this happening? (discuss in class...)

  # Check header properties relevant for this:

  3dinfo                            \
      -space -av_space -prefix      \
      MNI152_2009_template.nii.gz   \
      pb00.FT.r01.tcat+orig.

# ----------------------------------------------------------------------------

# The rest of this document walks through a tiny sample of AFNI
# commands. 

# We will run these in this AFNI Bootcamp directory:

  cd ~/AFNI_data6/afni/

# A useful place to explore AFNI programs across different
# functionality (e.g., searching for keywords in the page) is here:

  https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/programs/classified_progs.html

# ----------------------------------------------------------------------------

# Make an automask from the first volume of an EPI dataset (using AFNI
# subbrick selectors), outputting a NIFTI dataset

  3dAutomask -prefix mask_1.nii.gz epi_r1+orig.HEAD'[0]'

# Help file describes how the algorithm's masking can be made tighter/looser.

# ----------------------------------------------------------------------------

# A different way of masking, simply by thresholding (like where values > 500):

  3dcalc -a epi_r1+orig'[0]' -expr "ispositive(a-500)" -prefix mask_2.nii.gz

# Compare the masks in a couple different ways:

  # conjunction mask

    3dcalc -a mask_1.nii.gz -b mask_2.nii.gz -expr "a+2*b" -prefix mask_con.nii.gz

  # absolute value of difference
  
    3dcalc -a mask_1.nii.gz -b mask_2.nii.gz -expr "abs(a-b)" -prefix mask_absdiff.nii.gz

# Make an intersection of the two masks (**user pop quiz:** provide expression):

  3dcalc -a mask_1.nii.gz -b mask_2.nii.gz -expr "     " -prefix mask_inter.nii.gz

# ... and check out various expressions in 3dcalc's help file: lots of logic
# operations and other functions

# Some additional notes about using 3dcalc:

  # Note that the default datum type for the output is that of the '-a' dset.

  # Q1: What happens when the following is run, and why?

    3dcalc -a anat+orig. -b epi_r1+orig. -expr "a+b" -prefix OUT

  # Q2: How can we pre-check whether we can do such calculations with datasets?

  # Q3: Can we underlay/overlay these datasets in the GUI?  Why or why not?

# ----------------------------------------------------------------------------

# Make an image of the conjunction mask, whose values are in range [0, 3]:

@chauffeur_afni -ulay anat+orig. -olay mask_con.nii.gz           \
                -pbar_posonly -func_range 3 -prefix img_mask_con

# There are many, many, many options for controlling image creation,
# such as for colorbar, montage size, cropping, thresholding,
# etc. Check out the help file and online examples.

# ----------------------------------------------------------------------------

# 3dZeropad: add slices to a dataset

  3dZeropad -A 10 -P 20 -prefix anat_ZP.nii.gz  anat+orig.HEAD

# ... and the program also taketh away (negative zeropadding). Here, remove 
# subbrain slices:

  3dZeropad -I -50 -prefix anat_ZPneg.nii.gz  anat+orig.HEAD

# ----------------------------------------------------------------------------

# Calculate voxelwise statistics/quantities from a 4D dataset:

  # stdev (NB: this has detrending by default):

    3dTstat -stdev -prefix stat_stdev.nii.gz  epi_r1+orig.HEAD

  # median (**user pop quiz:** provide the necessary option):

    3dTstat        -prefix stat_median.nii.gz  epi_r1+orig.HEAD

  # **user pop quiz:** is the median pre-detrended or not?

# **user pop quiz:** The epi*HEAD dset contains 2 pre-steady state
#   time points at the beginning. How could we get the stdev *without*
#   including those?

# ----------------------------------------------------------------------------

# AFNI statistics programs put useful meta-information in the header,
# so we can convert stats in different ways, such as to/from
# p-values. We can use this in scripts, typically just specifying a
# particular subbrick within a stat-bearing dataset, as well as the
# sidedness of the test (2sided/bisided, or 1sided):

  p2dsetstat -bisided -inset func_slim+orig.'[2]' -pval 0.001

# The above is verbose, and thus difficult for scripting; to just get
# the value out:

  p2dsetstat -bisided -inset func_slim+orig.'[2]' -pval 0.001 -quiet

# NB: the degree of freedom (DF) info can also be seen with 3dinfo
# (and -subbrick_info)

# ----------------------------------------------------------------------------

# Calculate a correlation matrix, and also get whole brain correlation
# maps for free (rall_vr+orig is a concatenation of 3 runs but
# unadjusted for baseline jumps, so we just use the first run here)

  3dNetCorr                                  \
     -inset    rall_vr+orig.HEAD'[0..149]'   \
     -in_rois  mask.left.vis.aud+orig.HEAD   \
     -ts_wb_corr                             \
     -ts_out                                 \
     -prefix   CORR1

# Visualize the correlation matrix:

  fat_mat2d_plot.py                          \
     -input  CORR1_000.netcc                 \
     -vmin   -1                              \
     -vmax    1                              \
     -pars   CC

# Visualize the two time series (first convert row -> col):

  1dtranspose CORR1_000.netts > CORR1_000.col.1D

  1dplot -sepscl CORR1_000.col.1D

# NB: Or, we could transpose at read in: 1dplot -sepscl CORR1_000.netts\'

# Visualize whole brain time series (NB: EPI data have not been
# processed, regressed, blurred or anything); can open datasets in
# current- and sub-directories:

  afni -R -all_dsets

  # ... and leave anatomical as underlay, and select WB corr map dsets
  # from CORR1_000_INDIV/... as overlay

# ----------------------------------------------------------------------------