Data file and data structure documentation for the data used in "Simultaneously
uncovering the patterns of brain regions involved in different story reading
subprocesses".

Leila Wehbe

Sept, 2014, edited Sept, 2018

fMRI data is available for a number of human subjects.  For each subject the
full data set is stored on a file containing the subject number (e.g., the data
for subject 1 is on subject_1.mat).

After you load a data file, you will find four variables defined: words, time, data, and
meta.  The variable 'meta' contains general information about the dataset.  The
variable 'words' describes information about each word, when it's presented and
for how long.  The variable 'data' contains the actual image intensity data values. 
The variable time indicates the start time at which each row of data was acquired (the 
time in which each row was acquired is 2 seconds, i.e. we used a TR of 2 seconds).

The features used in the paper are also provided. There is one variable called 'features'
that we describe here as well.

Detailed documentation for each variable is provided below:

==================================== DATA file ===========================================
META

meta: This variable provides information about the data set. Relevant fields are
shown in the following example:

meta = 

       subject: '1'
          nTRs: 1307
       nvoxels: 21764
          dimx: 51
          dimy: 61
          dimz: 23
    colToCoord: [21764x3 double]
    coordToCol: [51x61x23 double]
   colToROInum: [21764x1 double]
 coordToROInum: [51x61x23 double]
  ROInumToName: {1x117 cell}
    voxel_size: [3,3,3]
        matrix: [4x4 double] 

meta.subject gives the identifier for the human subject.

meta.TRs gives the number of rows in the data set.

meta.nvoxels gives the number of voxels (3D pixels) in each image.

meta.dimx gives the maximum x coordinate in the brain image.  The minimum x
coordinate is x=1.  meta.dimy and meta.dimz give the same information for the y
and z coordinates.

meta.colToCoord(v,:) gives the geometric coordinate (x,y,z) of the voxel
corresponding to column v in the data.

meta.coordToCol(x,y,z) gives the column index (within the data) of the voxel
whose coordinate is (x,y,z)

meta.colToROInum(v) gives the ROI number according to the AAL atlas of the voxel v.

meta.coordToROInum(x,y,z) the ROI number of the voxel whose coordinate is (x,y,z).

meta.ROInumToName{i} gives the name of the ROI with number i.

meta.voxel_size gives the size of the voxels we used (they are 3mm*3mm*3mm for all 
subjects).

meta.matrix gives the map to the MNI space

===========================================
WORDS

info: This variable describes the sequence of words in the natural story shown to the subject.
The relevant fields are illustrated in the following example:

words(50) =

          text: 'Harry'
    	    start: 62.5
          length: 0.5


words(i).text returns the string that was displayed to the subject.

words(i).start indicates the start time from the beginning of the experiment.

words(i).length indicates the time the word was on the screen (we showed the words for 
0.5 seconds each).


===========================================
TIME

time is a nTRs x 2 matrix in which the first column indicates the start time of the 
recording of each row in the data matrix. 
The second column indicates the run to which every row belongs. The experiment consisted
of 4 runs, each starting with 20 seconds (=10 TRs) of rest, and ending with 10 seconds (=5 TRs) of rest.
To be specific, each run ends with 4.25 TRs of rest, because 3 words appear in the last but 5th TR. These can be discarded for convenience/uniformity.

===========================================
DATA

data: This variable contains the raw observed data.  The fMRI data is a
sequence of images collected over time.  The data structure 'data' is a [nTRS x nVoxels]
matrix, with one row per image acquired.  The element data(t,v) gives the fMRI observation
at voxel v during TR t.  The full image at time t is given by data(t,:).

The fMRI images have been realigned, slice timing corrected and coregistered with the 
subject's anatomical scan and normalized to the MNI space. The cerebrospinal fluid voxels
were discarded. 

The first 10 images and the last 3 images of every run consisted of only fixation.

=================================  FEATURE FILE  =========================================

FEATURES

features(1) =

      type: 'NNSE'
     names: {1x100 cell}
    values: [5176x100 double]
    
features(i).type gives the name of the feature set

features(i).names is a 1xp array that gives the name for each of the p individual features
in the feature set

features(i).values is a 5176xp array that gives the values of the p features for each of 
the 5176 words. The words are found in the 'words' structure in the data file, and the
order is the same.