TSTagger

A MATLAB function named TSTagger has been written to facilitate assigning volumes from a time series to a particular condition for supervised learning in a neural network. The function has no return value, but instead writes a series of .csv files. Each row in the .csv file represents an event from the time series. The input patterns are the median values from each column of the time series within a 5-second window following the event onset.

function TSTagger(varargin)
 Isolate TimeSeries data associated with each condition in a .mat runtime
 file
 
 Mandatory arguments:
   condition: a cell array of condition codes matching values in the
       condition column

   tr: scan interval (E.g. 2.047)

   dat: a cell array of structs: {dat.expinfo, dat.mat}, where expinfo comes
     from the PsychToolBox runtime .mat files, and mat is a (usually) normalized 
     timepoints x regions matrix of BOLD data generated by the
     gettimecourses.sh BASH script 
   
 Optional arguments:
   duration: a scalar indicating the number of volumes for each event
   (default: 1)

   volumes_dropped: number of INITIAL volumes dropped (i.e., volumes from 
       the start of the run), either as a single value or else as a vector
       of numbers. If a single value is provided, it will be applied to
       all paired data files, otherwise the values will be applied to the
       corresponding dat argument cell. Important: Do not use this parameter 
       if your event timestamps have already been adjusted for the volumes dropped 

   precision: input values will be rounded to PRECISION decimal places
   (default: 3)

   jitter: n vectors will be generated for each event, where each element
   vector is randomly selected from the lower quartile, median or upper
   quartile of values within the window. (default: 1 - only 1 vector using
   the median is generated for each event)

   jitter_p: jittered vectors will have jitter_p proportion of values
   randomly replaced with the lower and upper quartile value. (default:
   0.1, where 0.05 are replaced by lower, and 0.05 are replaced by upper)

   bias: when jittering, the lower and upper quartile values will be
   pulled towards the median value with a weighting of bias:1. (default:
   2, meaning that each jittered value is weighted 2:1 in favour of the
   median)

Sample Usage

 %use PTBParser to extract the runtime data from the .mat files for the participant
 eio=PTBParser();

 nruns=6
 for i=1:nruns
   DAT{i}.expinfo=eio{i};
   DAT{i}.mat=SCALED{i};
 end
 hifam=[11 21 31]; %Condition codes for hi familiar Semcat experiment
 lofam=[12 22 32];
 TR=2.047; %TR in the semcat experiment
 DROPVOLS=4; %We dropped the first 4 volumes when processing the data
 TSTagger('tr', TR, 'volumes_dropped', DROPVOLS, 'condition', ...
      hifam, 'dat', DAT);