This README.txt file was generated on 07-Jul-2022 14:05:23 by Emilio Salinas GENERAL INFORMATION 1. Title of Software: Software for running the urgent pro- and antisaccade tasks 2. Author Information: Author 1 (co-investigator) Name: Allison T Goldstein ORCID: 0000-0002-5475-5965 Institution: Wake Forest School of Medicine Address: 1 Medical Center Blvd, Winston-Salem, NC 27157, USA Email: agoldste@wakehealth.edu Author 2 (co-investigator) Name: Terrence R Stanford ORCID: 0000-0003-0759-5599 Institution: Wake Forest School of Medicine Address: 1 Medical Center Blvd, Winston-Salem, NC 27157, USA Email: stanford@wakehealth.edu, trspepper@gmail.com Author 3 (lead contact) Name: Emilio Salinas ORCID: 0000-0001-7411-5693 Institution: Wake Forest School of Medicine Address: 1 Medical Center Blvd, Winston-Salem, NC 27157, USA Email: esalinas@wakehealth.edu, esal64@gmail.com 3. Funding sources that supported the development of the software: Grant R21MH120784 from the National Institute for Mental Health; Grant R01EY025172 from the National Eye Institute; training grant T32NS073553-01 from the National Institute for Neurological Disorders and Stroke 4. Summary: This sofware package comprises scripts and functions written in Matlab for the purpose of running urgent versions of the classic prosaccade and antisaccade tasks. The scripts control the stimulus display and record the participant's responses either via a standard computer mouse (typically for development/debugging purposes) or via an EyeLink eye tracking system in combination with a VIEWPixx monitor (typically for experimental data collection). The code uses standard Matlab commands plus the Psychtoolbox 3 package. Routines are also provided that process the collected mouse/eye movements and generate behavioral data matrices, i.e., arrays where each row represents one trial and each column represents a task variable (trial type, reaction time, participant's choice, etc.). Although the primary goal of this package is to provide the code for running the tasks, additional tools are included that illustrate the complete sequence from data collection to behavioral analysis. SHARING/ACCESS INFORMATION 1. License for the software: CC BY 4.0 You can share, copy and modify this software so long as you give appropriate credit, provide a link to the CC BY license, and indicate if changes were made, but you may not do so in a way that suggests the rights holder has endorsed you or your use of the software. Note that further permission may be required for any content within the software that is identified as belonging to a third party. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 2. Links to publications that cite or use the software: Goldstein AT, Stanford TR, Salinas E (2022) Exogenous capture accounts for fundamental differences between prosaccade and antisaccade performance. eLife (in press). 3. Relationship to complementary dataset: Experimental data collected using this sofware package are described in the article mentioned above. Those data (in the form of arrays with trial-by-trial behavioral metrics) are publicly available from Zenodo. The reference for the dataset is Goldstein AT, Stanford TR, Salinas E (2022) Dataset: Exogenous capture accounts for fundamental differences between prosaccade and antisaccade performance [Data set]. Zenodo. https://doi.org/10.5281/zenodo.6757622 4. Recommended citation for this software: Goldstein AT, Stanford TR, Salinas E (2022) Software for running the urgent pro- and antisaccade tasks. Zenodo. https://doi.org/10.5281/zenodo.6784837 SOFTWARE & FILE OVERVIEW 1. File list (within task_share_proanti.zip): .\CPAS_Vpixx.m Matlab function for running the compelled (or urgent) pro- and antisaccade tasks. It presents visual stimuli, tracks and records the participant's response movements, and bundles all the data into two structures that are saved into files. All later processing is based on those saved structures. INSTRUCTIONS.txt Text file that provides some instructions and pointers for how to run CPAS_Vpixx and organize and process the resulting data. It illustrates this with example data files included in the package. The following are Matlab functions, usually very short, that perform specific computations and are called by CPAS_Vpixx .\closeExperiment.m .\displayVisual.m .\first.m .\getDistance.m .\getEyePosition2.m .\openExperiment_Vpixx.m .\renderVisual.m .\SwitchState.m .\data_files\binoCI.m .\data_files\boxit.m .\data_files\first.m .\data_files\getargs.m .\data_files\quantize.m .\data_files\smooth.m .\data_files\xycone.m See their individual headers (>> help function_name, in Matlab) to learn what they do. .\data_files This is the folder where CPAS_Vpixx saves the data collected after each call/experimental run. .\data_files\TEST_CPAS_Block_1_out .\data_files\TEST_CPAS_Block_1_out_1 .\data_files\TEST_CPAS_Block_1_out_2 Example files generated by CPAS_Vpixx containing the results of 3 runs of prosaccade (task 1) trials, collected using the computer mouse. .\data_files\TEST_CPAS_Block_2_out .\data_files\TEST_CPAS_Block_2_out_1 .\data_files\TEST_CPAS_Block_2_out_2 .\data_files\TEST_CPAS_Block_2_out_3 Example files generated by CPAS_Vpixx containing the results of 4 runs of antisaccade trials (task 2), collected using the computer mouse. .\data_files\eye2hdata.m Function that analyzes raw eye/mouse-movement data (generated by CAS_Vpixx) and puts it into a matrix with a standard format, wherein each row corresponds to one trial and each column to one variable (e.g., choice, reaction time, trial type). Such matrix can then be used to generate psychometric curves. This function processes raw data from one run. .\data_files\hfPooled.m Function that calls eye2hdata repeatedly in order to aggregate data spread across multiple data files. It produces combined data arrays that include multiple runs of CPAS_Vpixx for the same task and/or participant. .\data_files\humanbiz.m Function for analyzing the behavioral data matrices produced by eye2hdata or hfPooled. .\data_files\humanplots.m Function for plotting the output of humanbiz. 2. Relationship between files: The master program that runs the urgent tasks is CPAS_Vpixx. This function saves results in .mat files in the .\data_files directory. The saved files contain structures with the raw eye-movement (or mouse-movement) traces recorded in each trial. The function eye2hdata analyzes these raw movement traces and determines the direction of the response (i.e., the participant's choice) and its onset time (i.e., the participant's reaction time) in each trial. These quantities, along with other trial-wise variables, are returned by eye2hdata as a matrix where each row is one trial and each column a variable of interest. hfPooled calls eye2hdata repeatedly in order to aggregate data from multiple runs of a task. The functions humanbiz and humanplots perform basic analyses of the processed behavioral data matrices, generating psychometric curves and other behavioral metrics. METHODOLOGICAL INFORMATION 1. Requirements To run the sofware you will need Matlab (The Mathworks) to be installed. Version 2013b or more recent should work. You will also need Psychtoolbox version 3, which is described here: Brainard DH (1997). The psychophysics toolbox. Spatial Vision 10:433--436. Kleiner M, Brainard D, Pelli D (2007) What's new in Psychtoolbox-3? Perception 36 (ECVP Abstract Supplement). /http://psychtoolbox.org/ The Matlab function that runs the task, CPAS_Vpixx, can be configured in two ways, (1) to collect the participant's responses using the computer mouse on any vanilla system running Matlab+Psychtoolbox, or (2) to collect the participant's gaze responses using a VIEWPixx LED monitor (VPixx Technologies Inc., Saint Bruno, Quebec, Canada; 1920 x 1200 screen resolution, 120 Hz refresh rate, 12-bit color) for stimulus display and an EyeLink infrared camera and tracking system (SR Research, Ottawa, Canada; 1000 Hz sampling rate is best) for tracking the eye movements --- on a system with Matlab installed, of course. Using mode 1, CPAS_Vpixx has been tested in a variety of Windows-based systems; in mode 2, it worked in two different setups with VIEWPixx and EyeLink systems, also hooked to Windows-based computers. For further details about the science behind these urgent tasks, see the associated publication and references therein, or visit www.urgentchoicelab.org 2. Methods for processing collected data: The raw behavioral data saved by CPAS_Vpixx are continuous mouse or eye position measurements sampled at a certain frequency (1000 Hz in the case of the former). For behavioral analysis, these data need to be converted into discrete behavioral responses (e.g., choice, reaction time) for each trial performed. This is done by the function eye2hdata and others found in the .\data_files folder, as mentioned above. 3. People involved with development of the software: Emilio Salinas developed the code for running the pro- and antisaccade tasks (CPAS_Vpixx and associated functions) based on earlier scripts that implemented the state-transition framework for a different task, which were written and kindly shared by Benjamin A Rowland. Allison T Goldstein edited the code, tested it extensively, and collected data from participants under the supervision of ES and Terrence R Stanford. Scripts for processing the collected raw data were developed by ES and ATG. This software was bundled and submitted by ES. VERSION-SPECIFIC INFORMATION: Version 1.0.2 Included a file that was missing in the package (MyBeep.wav). Version 1.0.1 Fixed a few typos and made other minor edits in the .txt files. Version 1.0.0 First release of the sofware.