Pupil-linked phasic arousal evoked by violation but not emergence of regularity within rapid sound sequences

2019-08-19T09:02:47Z (GMT) by Sijia Zhao Maria Chait
This repository contains all raw and processed pupillometry and behavioural data and the analysis codes to replicate the figures in Zhao et al. (2019) Nature Communication.
See https://github.com/sijiazhao/RegRand for more analysis codes, including detailed instructions for replicating the figures from the manuscript.

# OVERVIEW
The paper showed pupillometry and behavioural data for 7 experiments. Their indices amd number of subjects are:
* Expt1A: N=18
* Expt1B: N=14
* Expt2: N=18
* EXPT3A: N=14
* EXPT3B: N=14
* Expt4A: N=12
* Expt4B: two groups of N=15

# DATA STRUCTURE

## Raw data
In each experiment's subfolder, you can find:

1. Raw eyetracking data in edf. Normally the file format is 'log_S1_Block1.edf', showing data for subject S1's block 1.
...* Special note #1: Some experiments have slightly different filname formatting, for example, 'log_S1_Aud_pat10dur50_Block1A' in Expt2. The extra string '_Aud_pat10dur50_' is identical across all subjects and all blocks, so it is very easy to ignore this extra string.
...* Special note #2: The raw eyetracking data in Expt 1A are lost, but the extracted data--sampling asc and events asc--are available.

2. Raw behaviour data in .mat. This file has identical name with (1). It contains:
...* variable 'design': a structure for the experimental information for this block (e.g. condition name, number of blocks etc.)
...* variable 'results': a structure of block trial information and key press data
...* variable 'stimuli': a cell array of all stimuli


## Processed data
All processed data are in .mat format. There are three types of processed data:

1. Processed data - Behaviour: Each experiment had one file, e.g., 'behav_expt1A.mat'. This file contains condition list, hit rate, false alarm rate and RT (if applicable). For Expts 1A, 1B, 2, 4A, 4B, these results are for gap detection. For Expt3A and Expt3B, the results are for transition detection. For Expt3A, the data is saved in a structure where RT is also available. Use the script 'plot_behav_expt3A.m' to plot behavioural data.

2. Processed data - Pupil diameter response: Each experiment had one file, e.g., 'pupil_expt1A_PDRatTrans.mat', containing all subjects' pre-processed pupil diameter data (P) against the time relative to transition. All data are sorted by condition. Gaze positions (G) and blink data (B) are also available. To reproduce the figures, run MATLAB script 'makefig_PDR_AllinOne.m'.

3. Processed data - Pupil dilation event: Pupil dilation/constriction event data. Only Expt1(1A+1B) and Expt4B(two groups) are available. To reproduce the figures, run MATLAB script 'makefig_PDevent.m'. Each experiment contains 6 files:
...* 1 file like 'PDevent_expt1.mat': Pupil diameter data used to extract pupil dilation and constriction events. This is almost identical to 'pupil_expt1A_PDRatTrans.mat', except its data have much longer baseline (3-second pre transition) to avoid edging effect when ploting pupil event results.
...* 4 files like 'pdEvent_expt1_PC_75.mat': Data for raster plot. 'PC' means 'Pupil Constriction' ('PD', pupil dilation), while the last number '75' means the event duration threshold as 75ms ('300', 300ms as threshold).
...* 1 file like 'pdRate_expt1.mat': Convolved rate for pupil dialtion/constriction events for two different thresholds (75ms, 300ms).


## Codes
Analysis codes for replicating the figures (PDR and pupil dilation events) are available along with processed data.
In order to run the time-series statsitical analysis, you must install the MATLAB package for EEG analysis 'fieldtrip' (http://www.fieldtriptoolbox.org/). You can find more analysis code on https://github.com/sijiazhao/RegRand or contact Sijia Zhao (sijia.zhao.10@ucl.ac.uk).

Special note: Before running the script, please make sure to change the directory of the processed data.
1. Behaviour: run 'plot_behav_expt3A.m' which will output Expt3A's behavioural result. This code can be applied to other experiments too.
2. Plot PDR: run 'makefig_PDR_AllinOne.m' which will output all 7 experiments' PDR result.
3. Plot pupil dilation/constriction event rates: run 'makefig_PDevent.m' which plots Figure 3 (Expt1) and Supplementary Figure 3 (Expt4B) including raster plot, convolved rate for both pupil dilation and pupil constriction.
4. Plot Figure 7 Relationship between RT and the pupil dilation response: run 'makefig_Expt3A_PDRsortedbyRT.m'.


## Stimulus examples
This folder includes audio files for example stimuli used all experiments.

Examples are grouped by experiment. One example is presented for each condition. Note that these are examples for reference only (actually presented stimuli were generated anew for each subject and each trial).
1. The subfolder 'Expt1' includes one example wav file of each of the five conditions used in Experiments 1A and 1B: STEP, CONST, REG10, REG10-RAND20, RAND20, and RAND20-REG10.
2. The subfolder 'Expt2' includes one example of each of the nine conditions used in Experiment 2: REG10, REG10-RAND10, REG10-RAND10d, REG10-RAND20, RAND10, RAND10-REG10, RAND10-REG10d and RAND20, RAND20-REG10.
3. The subfolder 'Expt3' includes one example of each of the five conditions used in Experiment 3A and 3B: STEP, CONST, REG10, REG10-RAND20, RAND20, and RAND20-REG10.
4. The subfolder 'Expt4A' includes one example of each of the seven conditions used in Experiment 4A RAND20-REG1, RAND20-REG10, RAND20, STEP, CONST, REG10, REG10-RAND20.
5. The subfolder 'Expt4B' includes one example of each of the five conditions used in Experiment 4B: RAND20, RAND20-REG1, RAND20-REG2, RAND20-REG5, RAND20-REG10.