# ========================================
# ========================================
# Keith Bush, PhD (2018)
# Univ. of Arkansas for Medical Sciences
# Brain Imaging Research Center (BIRC)
# ========================================
# ========================================

# ----------------------------------------
# ----------------------------------------
    OTHER CONTRIBUTORS:
# ----------------------------------------
# ----------------------------------------
Kayla Wilson (2018-2019)
    heart rate change analysis

# ----------------------------------------
# ----------------------------------------
    OVERVIEW: 
# ----------------------------------------
# ----------------------------------------

This project is the processing and analysis pipeline used to conduct a
secondary analysis of heart rate physiological measures of affect
processing as part of the NSF Cognitive Neuroscience project titled
"Cognitive Control Theoretic Mechanisms of Real-time fMRI-guided
Neuromodulation (Award# BCS-1735820). For award details, see:

https://www.nsf.gov/awardsearch/showAward?AWD_ID=1735820

WARNING: The methodological steps of this project will be migrated to:
https://github.com/kabush/IN for permanent hosting and maintenance
upon the conclusion of this project's NSF funding (ca. 2020).

# ----------------------------------------
# ----------------------------------------
    INTRODUCTION: 
# ----------------------------------------
# ----------------------------------------

The purpose of this code is to perform the following tasks:

1) Preprocess fMRI and psychophysiological (HR) for the project using
best practices (and document literature of each step).

2) Construct beta-series (Rissman, 2004) features for each data type
where relevant (fMRI & HR change)

3) Predict cognitive (i.e., emotion) measures via physiological (i.e.,
HR change betas) and fMRI-derived whole-brain neural activations to
identify the "plant" of the system (valence). For the purposes of this
project, we define the plant as the functional neuranatomical
activations encoding the valence dimension of affect according to the
circumplex model of emotion.  Beta-series of fMRI are referred to
(pseudo-correctly) as brain states.

4) Identify functional neuranatomical descriptions of affect
processing.

# ----------------------------------------
# ----------------------------------------
    DATA SOURCES:
# ----------------------------------------
# ----------------------------------------

WARNING: The data for this project (MRI & physio) will be placed in 
a public repository upon the conclusion of this project's NSF funding
(ca. 2020).

# ----------------------------------------
# ----------------------------------------
    PROJECT OVERVIEW:
# ----------------------------------------
# ----------------------------------------

/HR
    run_project.m  # the master script which sequentially
    		   # calls all supporting scripts.  If the
	      	   # project executes correctly then the 
	      	   # log directory will contain a textual
	      	   # description of all important statistical
	      	   # findings and the fig directroy will contain
	      	   # all important figures.  Intermediate data
	      	   # will be stored at the path location specified
	      	   # by proj.path.data in the proj.mat 
    matlab_reset.m # clears the workspace and resets matlab's
                   # path to the initial launch state
    /source
        init_project.m  # all project parameters
    	clean_project.m # wipes the directory storing
    			# intermediate files

        /analysis
	    # contains code for statistical tests
	    # and plotting
        /beta_series
	    # beta_series extraction 
	    # scripts for all data types
	/haufe
	    # contains code for constructing permutation
	    # tested Haufe-transformed encoding hyperplanes
        /mvpa
	    # whole-brain and dimensionally
	    # reduces MVPA predictions of
	    # affect
        /preprocess
            # preprocessing scripts for
	    # all data types

    /design
        # Stores critical task design data files
 	# which maintain all of the experiment
	# designs (*.mat files currently)
    /subj_lists
        # stores text files listing the included
	# subjects for each study being used in
	# this project analysis
    /log
        # where statistical findings are stored
    /fig
        # where plots are stored
    /doc
        # where project documentation is stored    

# ----------------------------------------
# ----------------------------------------
    REQUIRED SOFTWARE
# ----------------------------------------
# ----------------------------------------

matlab (Tested only for R2016B)
    - statistical analysis toolbox
    - parallel computing toolbox

ANFI (Version AFNI_18.2.06)

FSL (5.0.9)

python (2.7)
    - numpy	
    - scipy
    - matplotlib
    - pandas

# ----------------------------------------
# ----------------------------------------
    REQUIRED MATLAB LIBRARIES
# ----------------------------------------
# ----------------------------------------

kablab
    https://github.com/kabush/kablab    

export_fig
    https://www.mathworks.com/matlabcentral/fileexchange/23629-export-fig

nifti (Jimmy Shen)
    https://www.mathworks.com/matlabcentral/fileexchange/8797-tools-for-nifti-and-analyze-image?s_tid=prof_contriblnk