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

Title:      Audio Cartography - Presentation 
Copyright:  2017 University of Oregon
Author:     M. Brittell
License:    GNU General Public License, version 3 (GPL3)

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.

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

Stimulus presentation was implemented in PsychoPy (Peirce, 2007) experiment, in 
which the timing of the presentation was synchronized with the quiet intervals
of a sparse-sampling scan sequence.

The stimuli were based on data, which were systematically generated and 
rendered by scripts provided in the accompanying "audioCartography-prepare".  
The data sets were also rendered in alternative formats, which are provided in 
the accompanying "audioCartography-maps".  Files produced by this software were 
processed for analysis with scripts provided in "audioCartography-process".

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

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

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

A copy of the GNU General Public License, version 3 (GPL3) under which these 
scripts are released.

--------------------------------------------------------------------------------
Audio Cartography PsychoPy Experiment
--------------------------------------------------------------------------------
File: audioCartography-present.psyexp

PsychoPy-based script (Peirce, 2007) that presents auditory and visual stimuli, 
synchronizes that presentation with the fMRI scan sequence, and records 
timestamped events (software state and participant responses). The same 
software was used in both a practice run during the training session 
("behavioral") and two runs during a scanning session ("scan").

The experiment runs in full-screen mode.  The graphic response prompts are set 
within a square background (screen area outside the square is filled with black 
pixels).

The log output includes "EV" entries in addition to standard logging from the 
PsycoPy experiment at the "INFO" level.

Progress through the experiment:
1. The message "Please rest until the session begins." shows on the screen and 
	progress is blocked, providing time to position the participant in the 
	scanner, until the researcher initiates the activity (press space bar).
	
2. [Scan only] The experiment displays a message "Please rest and remain still 
	while a reference scan runs." and blocks progress, providing time to run a 
	localizer scan, until the researcher advances to the trials (press space 
	bar).
	
3. The message "Waiting for the scanner..." appears when a trial is ready to 
	begin, the experiment will automatically advance upon receiving the trigger 
	pulse from the scanner (apostrophe key or space bar).
	
4. After each listening activity (first part of each trial), the experiment 
	waits for a trigger pulse (apostrophe key or space bar) before advancing to 
	the response activity (second part of each trial).
	
5. [Scan only] Between the two runs, the experiment has a placeholder to 
	display a message that the run has concluded and then to "Please rest and 
	remain still while a reference scan runs." for the MPRAGE.  The researcher 
	advances past each of these screens by pressing the space bar.
	
6. [Scan only] After the second run, the experiment displays a message "Please 
	rest and remain still while a reference scan runs." and blocks progress, 
	providing time to run scans to support creation of field maps, until the 
	researcher advances (press space bar).

7. [Scan only] Finally, the experiment displays a fixation cross on an otherwise 
	blank screen (full screen, not "cropped" to a square), providing a standard 
	visual display to accompany a resting state scan.  The resting state scan
	was part of the scanning center protocol and data from that scan was not 
	used in this study.

The researcher can stop (interrupt) the experiment by pressing the escape key 
or the "q" key. Note that audio playback blocks the interrupt, but the 
experiment will stop at the conclusion of the audio clip.
	
Usage:
	<run from Builder view>
	
	Note: if exporting and running from the script editor, the comments on the 
	"welcome" block include a modification to the initial dialog box that would
	create a drop-down menu with the valid options for session, preferred hand, 
	and order.
	
Requires:
    Python 2.7.11
    	Copyright © 2001-2018 Python Software Foundation
        Python Software Foundation ("PSF") license
		https://www.python.org
		
	PsychoPy 1.84
		Copyright © 2002-2015 Jonathan Peirce
		GNU General Public License 3
		http://www.psychopy.org
		
Inputs (via dialog box):
	order			Presentation of the two stimulus sets ("AB" or "BA"; 
					applies to the "scan" sessions only)
	participant		Unique identifier (numeric code to protect identity).  The 
					file naming convention reflects the participant identifier.
	preferred hand	Participant's preferred hand and the hardware button box
					through which response were entered ("right" or "left")
	session			Data collection session type ("behavioral" or "scanner") 
					that indicates which conditions file to use, sets which 
					response keys are scored for answers (arrow keys for 
					behavioral, number keys for scan), and dictates whether or 
					not the experiment pauses for reference scans.  The file 
					naming convention reflects the session type.

Outputs:
	<participant>_AudioCartography_<session type>_<date>.csv
					tabular record in which each row represents a trial and 
					the columns contain details of the stimulus and response
	
	<participant>_AudioCartography_<session type>_<date>.log
					timestamped events and log messages
	
	<participant>_AudioCartography_<session type>_<date>.psydat
					Serialized session state

--------------------------------------------------------------------------------
Resources
--------------------------------------------------------------------------------
File: audioCartography-present-conditions.json

Metrics that describe characteristics of the trials in each run.  The 
characteristics are organized in a comma separated values (.csv) file, and the 
columns contained in that file are described in the accompanying Brain Imaging 
Data Structure (BIDS)-style JSON (.json) sidecar file (Gorgolewski et al. 
2016).

A subset of the columns are identical to those in the respective map 
description (see audioCartogrphy-maps/audioCartography-maps.json)

--------------------------------------------------------------------------------

Folder: audioCartography-present/conditions/

Record of stimulus details.  The presentation order within each set was 
randomized by the TrialHandler associated with the Loops "run1" and "run2"; the
order in which participants experienced "scan1" and "scan2" is counterbalanced
across participants using the "order" parameter (see 
audioCartography-present.psyexp).

File: scan1.csv
	Details of the stimuli in set A of the scanning session

File: scan2.csv
	Details of the stimuli in set B of the scanning session

File: train.csv
	Details of the stimuli used in the practice run during the training session

Each file contains details of the trails presented in the respective run (see 
audioCartography-present-conditions.json)

--------------------------------------------------------------------------------

Folder: audioCartography-present/images/

Graphics that supported the behavioral task by reminding the participant of the
task ("instruction"), providing a cue for the upcoming audio map type 
("presentation"), and indicating the locations of the two response options 
("response").


Sub-Folder: audioCartography-present/images/instruction
-------------------------------------------------------
File: left.png
	Graphic depiction of the left-hand response hardware (button box) and brief 
	text-based instruction.

File: right.png
	Graphic depiction of the right-hand response hardware (button box) and 
	brief text-based instruction.


Sub-Folder: audioCartography-present/images/presentation
--------------------------------------------------------
File: blank.png
	A square white background over which the fixation cross, icons, and 
	response options were graphically rendered.
	
File: fixation.png
	Fixation cross displayed at the start of the response activity and during 
	the reference scans.
	
File: fixConcurrent.png
	Icon indicating that the next trial would present data concurrently
	("concurrent" map type)
	
File: fixSequential.png
	Icon indicating that the next trial would present data sequentially
	("sequential" and "augmented-sequential" map types)


Sub-Folder: audioCartography-present/images/response
----------------------------------------------------
File: distractor.png
	Square to display in the location of the response option that is toward 
	the right side of the screen (east side of the map).  NOTE: despite it's 
	name, the "distractor" does not give any indication as to the correct 
	answer to the behavioral task.

File: target.png
	Square to display in the location of the response option that is toward 
	the left side of the screen (west side of the map).  NOTE: despite it's 
	name, the "target" does not give any indication as to the correct answer to 
	the behavioral task.

--------------------------------------------------------------------------------

Folder: audioCartography-present/sounds/

Files: trackNN.wav	<NN: two-digit track number>

	Auditory stimulus files following the naming convention 
	"track<data set number>.wav"; identical to the map files provided in 
	"audioCartography-maps-audio".  If the track number is less than 10, 
	the number is left-padded with zero to make a two-digit number
	

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

REFERENCES

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/

Peirce, J.W. (2007) PsychoPy–psychophysics software in Python. Journal of 
	Neuroscience Methods, 162(1–2):8 – 13.  Available: http://www.psychopy.org/

Peirce, J.W. (2009) Generating stimuli for neuroscience using PsychoPy. 
	Frontiers in Neuroinformatics, 2:10. doi: 10.3389/neuro.11.010.2008
	
Python software is copyright © 2001-2015 Python Software Foundation. Web site: 
	https://www.python.org

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