================================================================================
================================================================================

Title:      Audio Cartography - Processing 
Copyright:  2018 University of Oregon
Author:     M. Brittell
License: 
	Scripts for data processing released under the GNU General Public License 
	(GPL) version 3 (GPL3).
	
	"Configuration files for use with FSL FEAT are provided AS-IS
	for non-commercial use as a research courtesy by Dr. Megen Brittell
	AND ARE PROVIDED WITHOUT  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, 
	WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
	FOR A PARTICULAR PURPOSE. Download and use of these files indicates 
	acceptance of the License which governs the FMRIB Software Library (FSL), 
	Release 6.0, Copyright 2018, The University of Oxford."

This work was funded in part by the National Science Foundation (NSF) Doctoral 
Dissertation Research Improvement (DDRI) Grant #1634086 and the University of 
Oregon (UO) Lewis Family Endowment.

This work benefited from access to the University of Oregon high performance 
computer, Talapas.

================================================================================
================================================================================
Several scripts that performed data munging and re-formatting facilitate 
analysis of the data produced as part of an empirical evaluation of auditory
map types. The data that these scripts process represent participant responses
as recorded by software provided in "audioCartography-present".  

Reported analysis was based on data from 22 participants.  Behavioral and fMRI 
data for the 21 participants who gave their consent to include individual data 
in the public release are available in OpenNeuro: 
https://openneuro.org/datasets/ds001415.

--------------------------------------------------------------------------------
README (This file)
--------------------------------------------------------------------------------
File: audioCartography-process-README.txt

An overview of the contents of this part of the collection.


--------------------------------------------------------------------------------
LICENSE
--------------------------------------------------------------------------------
File: audioCartography-process-COPYING.txt

A copy of the GNU General Public License, version 3 (GPL3) under which the R, 
Python, and SLURM/Bash scripts are released.


--------------------------------------------------------------------------------
EXTRACT EVENTS
--------------------------------------------------------------------------------
File: audioCartography-process-events.py

Extract event timing from the log file to create a BIDS-compatible event file
(tab separated values, .tsv) and an FSL-compatible event files (three-column
explanatory variables, .ev).  Parsing relies on the format of the PsychoPy log 
file, including custom information tags.

Note: The input log file is expected to contain "EV" log entries (see 
audioCartography-present) and an "INFO" log entries that matches the text 
"Wait/Start MPRAGE", in additional to standard messages at logging level "info".

Note: This script is designed to be called from prep.srun; if running as a 
stand-alone script, the folders sub-N/func and derivatives/ev/sub-N are 
expected to already exist.

Note: If the participant response occurs after the end of the map file (e.g., 
at time 56.009 seconds after the start of the 56.0 second map), the response is 
logged in the PsychoPy output, but reflected in the event file as "n/a"; in the 
reported results, responses within milliseconds after the end of the map were 
scored manually and included in the analysis.

Usage: 
	python audioCartography-process-events.py [-h] [-v] \
		--tr 7 -- ta 2 -i demo.log \
		-b audioCartography -p 01 -t maplistening

Dependencies:
	argparse 1.1 - Python Standard Library (see Python)

	csv 1.0 - Python Standard Library (see Python)

	os - Python Standard Library (see Python)

	Python 2.7
		Copyright © 2001-2018 Python Software Foundation
	    Python Software Foundation ("PSF") license
		https://www.python.org

	Input:
		-i <infile>		log file with timestamped stimulus presentation and
						participant response events
		-b <BIDS root>	root of the destination BIDS data set
		-p <pNum>		participant identifier
		-t <task>		task label
		--tr <TR>		repetition time from the scan sequence
		--ta <TA> 		acquisition time from the scan sequence

	Output:
		<outfile>.tsv	tab separated values representing event timing using
						naming convention: 
						sub-<pNUM>_task-<task>_run-<run>_events.tsv
		
		<outfile>.ev	three-column stimulus time course written to the
						derivatives folder
		
		
--------------------------------------------------------------------------------
FRMI PRE-PROCESSING
--------------------------------------------------------------------------------
File: audioCartography-process-prep.srun

Round up the neuroimaging and behavioral data and establish a BIDS-style file
structure. The script is written in Bash, and includes a header for submission
as a SLURM job.

Note: With fMRI data that uses sparse sampling, the analysis does not apply 
slice timing correction (see Perrachione and Ghosh 2013).

Dependencies:
	audioCartography-process-events.py (in this collection)

	Bourne Again Shell (Bash) 4.2.46
		Copyright © 2011 Free Software Foundation, Inc. 
		GNU General Public License 3 or later
		https://www.gnu.org/software/bash/

	dcm2niix v1.0.20171215
		Chris Rorden
		https://github.com/rordenlab/dcm2niix
		
	FMRIB Software Library (FSL) v5.0.10
		Wellcome Centre for Integrative Neuroimaging (FMRIB), 
		University of Oxford
		https://fsl.fmrib.ox.ac.uk/fsl
		(Jenkinson, et al. 2012)
	
	MRIConvert (mcverter) v2.1.0 build 440
		GNU General Public License
		Jolinda Smith
		Lewis Center for Neuroimaging (LCNI), University of Oregon
		https://lcni.uoregon.edu/downloads/mriconvert/mriconvert-and-mcverter
		
	mri_deface v1.22
		FreeSurfer, Harvard
		https://surfer.nmr.mgh.harvard.edu/fswiki/AutomatedDefacingTools
		(Bischoff-Grethe, et al. 2007)


--------------------------------------------------------------------------------
ANALYSIS OF BEHAVIORAL DATA
--------------------------------------------------------------------------------
File: audioCartography-process-beh.R

Perform statistical analysis of behavioral data results are plotted in the 
default graphics device and results of the statistical tests are printed to the 
console.  Input is read from event files (.tsv) in the BIDS-compatible data 
structure available from OpenNeuro (see link above).
	
Requires:
	R 3.3.1
		Copyright © 2016 R Core Team 
		GNU General Public License 2 or 3
        https://www.R-project.org/

	tidyr 0.7.2
		Copyright © Hadley Wickam and RStudio
		MIT + file license
		https://cran.r-project.org/web/packages/tidyr/
		
	
Inputs:
	<BIDS directory>		location from which to read data

Outputs (to graphics device and console):	
    summary plots			aggregate performance data in a box and whisker
							plot for response time and a bar plot for accuracy
							
	statistics				results from the Friedman rank sum test (response
							time) and McNemar's chi-squared test (accuracy) 
							print to interactive console
 
 
--------------------------------------------------------------------------------
FEAT DESIGN FILES
--------------------------------------------------------------------------------
Files: 
	audioCartography-process-firstLevelContrast.fsf
	audioCartography-process-individualAverage.fsf
	audioCartography-process-groupAverage.fsf

Configuration files for the first-level analysis specify two paired contrasts: 
sequential vs. augmented-sequential map type and augmented-sequential vs. 
concurrent map type, in both directions (A>B and A<B) to be executed in FEAT 
(Woolrich, et al. 2001; Woolrich, et al. 2004), part of FSL.  Execution of the 
first-level analysis is automated (see audioCartography-process-stats.srun). 

The individual average is computed in higher-level analysis, combining data
within participant and across run with fixed effects.  

The final analysis computes a group average in a higher-level analysis with
mixed effects: one execution for each of the four contrasts of interest.
The contrast should be updated in the FEAT design file REPLACE_COPE (values: 
"cope1", "cope2", "cope3", "cope4") and the output file should be named 
accordingly REPLACE_NAME (example values: "cope1-seq-aug", "cope2-aug-seq", 
"cope3-con-aug", "cope4-aug-con")

All three FEAT design files expect absolute path names; paths have been 
replaced with a placeholder (REPLACE_BIDS; or REPLACE_FEAT in first level).

Dependencies:
	FMRIB Software Library (FSL) v5.0.10
		Wellcome Centre for Integrative Neuroimaging (FMRIB), 
		University of Oxford
		https://fsl.fmrib.ox.ac.uk/fsl
		(Jenkinson, et al. 2012)
	

--------------------------------------------------------------------------------
ANALYSIS OF FMRI DATA
--------------------------------------------------------------------------------
File: audioCartography-process-firstLevelFEAT.srun

Automate execution of the first-level FEAT analysis using a configuration file
with placeholders that need replacement for each functional scan file.  The 
processing relies on details described in the template configuration file (see 
audioCartography-process-firstLevelContrast.fsf), and parameter values are 
extracted from the data and from the metadata files output by mcverter (see 
audioCartography-process-prep.srun).  The script is written in Bash, and 
includes a header for submission as a SLURM job.

The script expects to find the FEAT design file in the "code" sub-folder within 
the BIDS directory.

Note: Higher level analysis are run through the FEAT GUI starting with the 
respective design files (see audioCartography-process-individualAverage.fsf and 
audioCartography-process-groupAverage.fsf).

Dependencies:
	audioCartography-process-firstLevelContrast.fsf (in this collection)
	
	Bourne Again Shell (Bash) 4.2.46
		Copyright © 2011 Free Software Foundation, Inc. 
		GNU General Public License 3 or later
		https://www.gnu.org/software/bash/
		
	FMRIB Software Library (FSL) v5.0.10
		Wellcome Centre for Integrative Neuroimaging (FMRIB), 
		University of Oxford
		https://fsl.fmrib.ox.ac.uk/fsl
		(Jenkinson, et al. 2012)


================================================================================
================================================================================

REFERENCES

Bischoff-Grethe, A., I.B. Ozyurt, E. Busa, B.T. Quinn, C. Fennema-Notestine, 
	C.P. Clark, S. Morris, M.W. Bondi, T.L. Jernigan, A.M. Dale, G.G. Brown, 
	and B. Fischl. (2007) A technique for the deidentification of structural 
	brain MR images. Human Brain Mapping, 28(9):892–903. doi: 10.1002/hbm.20312

Bourne Again Shell (Bash) software is copyright © 2007 Free Software 
	Foundation. Web site: https://www.gnu.org/software/bash/

Gorgolewski, K.J., T. Auer, V.D. Calhoun, R.C. Craddock, S. Das, E.P. Duff, G.
	Flandin, S.S. Ghosh, T. Glatard, Y.O. Halchenko, D.A. Handwerker, M. Hanke, 
	D. Keator, X. Li, Z. Michael, C. Maumet, B.N. Nichols, T.E. Nichols, J. 
	Pellman, J.-B. Poline, A. Rokem, G. Schaefer, V. Sochat, W. Triplett, J.A. 
	Turner, G. Varoquaux, and R.A. Poldrack. (June 2016) The brain imaging data 
	structure, a format for organizing and describing outputs of neuroimaging 
	experiments. Scientific Data, 3. Web site: http://bids.neuroimaging.io/
	
Jenkinson, M., C. F. Beckmann, T. E. J. Behrens, M. W. Woolrich, and S. M. 
	Smith. (August 2012) FSL. NeuroImage, 62(2):782–790. doi:
	10.1016/j.neuroimage.2011.09.015

Perrachione, T., and Ghosh, S. (2013). Optimized design and analysis of 
	sparse-sampling fMRI experiments. Frontiers in Neuroscience, 7:55.
	
Python software is copyright © 2001-2015 Python Software Foundation. Web site: 
	https://www.python.org

R Core Team (2016). R: A language and environment for statistical computing. R 
    Foundation for Statistical Computing, Vienna, Austria. Available: 
    https://www.R-project.org/.

Woolrich, M., T. Behrens, C. Beckmann, M. Jenkinson, and S. Smith. (April 2004)
	Multi-level linear modelling for FMRI group analysis using Bayesian 
	inference. NeuroImage, 21(4):1732–1747. PMID 15050594. doi: 
	10.1016/j.neuroimage.2003.12.023

Woolrich, M.W., B.D. Ripley, M. Brady, and S.M. Smith. (2001) Temporal 
	autocorrelation in univariate linear modeling of fMRI data. NeuroImage, 
	14(6):1370 – 1386. doi: 10.1006/nimg.2001.0931

================================================================================
================================================================================
