Par-Files

Paradigm files, oir "par-files" are tab-delimited plain-text files that specify to Freesurfer's FS-FAST program when different experimental conditions occurred within each functional run. They have a very straightforward structure, with one line per event or block. The files have between two and four columns according to various sources, though this documentation has changed with different releases of Freesurfer. What seems to work for our release is the following column structure:

Cumulative_Onset     Condition_Number_Code     Duration     Weight

The cumulative onset is specified in seconds and assumes that the first volume onset is at t=0 seconds. If initial volumes have been truncated from the 4D time series, adjust the onsets accordingly, depending on your TR. For example, if your TR is 2 seconds, and you drop the first 4 volumes of a 100-volume series, your resulting data will contain only 96 volumes, and the first event will appear 4*2=8 seconds earlier in the series.

The following is a snippet from a par file for an experiment with a fixed schedule (i.e., all participants had the same experimental timings, rather than a self-paced experiment):

12.000     6     2     1
16.813     3     2     1
21.626     3     2     1
26.038     3     2     1
30.048     3     2     1
34.059     3     2     1
38.470     6     2     1
42.481     4     2     1
46.492     4     2     1
51.305     1     2     1

Here, the experiment starts with the first event happening 12 seconds into the run. It is event condition 6, and the duration of this trial (and all others) is 2 seconds. All trials are given a weight of 1 in the analysis (weights of 0 might be assigned if, for example, you want to discount activity associated with error trials).

An important thing to note: all .par files associated with a particular analysis must have the same filename. This is possible because each .par file is stored in the same directory as the fMRI data that it corresponds to, and the fMRI data for each run is kept in its own directory. For example, you might have the following directory structure:

• FS_T1_501
  • bold
    • 001
      • f.nii
      • booth.par
    • 002
      • f.nii
      • booth.par

When analyzing a fixed-schedule experiment, you should be able to simply copy the appropriate pre-existing par-file for that run from a source directory. For example, the par-files associated with the Booth data can be found in the par_files directory, in subdirectories corresponding with their Reading_Experiment_IDs.

When analyzing data from a self-paced experiment, each participant will have a unique par-file that will have to be generated from his/her MATLAB experimental data file.

Generating Par Files for Self-Paced Experiments

A MATLAB function, FSTSExtractor, has been written to extract the schedule of events from the .mat files generated by our PsychToolBox experiment scripts. Note that the structure of these .mat files is particular to our scripts, and that you shouldn't expect this procedure to work on experiment data files generated by any other means. However, the MATLAB code for this script is provided below and can be modified to accommodate other input data.

FSTSExtractor.m

function stamps=FSTSExtractor(varargin)
%% function stamps=TSExtractor()
% Extract all the timestamps associated with each condition stored in a .mat file.
% These values are saved, but also returned as a vector called stamps (which can be ignored).
% It is assumed that the .mat files are named
% PREFIX_Sub_SUBJECTNUMBER_Run_RUNNUMBER_DD_MMM_YYYY.mat
%
% Mandatory arguments:
%  subject: a string or cell array of strings
%      run: an integer or array of integers
%     date: a serial date number representing a particular date as an
%           integer. This can be created calling the datenum() function. E.g.
%           datenum('19-Nov-2015')
%
% Optional arguments:
%     prefix: a string, such as 'LDT_' that begins your .mat files (default:
%             empty string)
%  directory: a string, such as '/home/experimenter/fmri/data' that contains 
%             your .mat files (default: current working directory) 
%
% Sample usage:
% >> d=datenum('19-Nov-2015');
% >> FSTSExtractor('prefix', 'LDT_', 'subject', 1000, 'run', 1, 'date', d)
% >> FSTSExtractor('prefix', 'LDT_', 'subject', 1001, 'run', 1, 'date', d, ...
%    'directory', '/data/subjects/1001/')
%%
 
% define defaults at the beginning of the code so that you do not need to
% scroll way down in case you want to change something or if the help is
% incomplete
options = struct('prefix',,'subject',, 'run', 0, 'date', datenum(date()), 'directory', pwd() );
 
% read the acceptable names
optionNames = fieldnames(options);

% count arguments
nArgs = length(varargin);
if round(nArgs/2)~=nArgs/2
   error('TSExtractor needs propertyName/propertyValue pairs')
end
 
for pair = reshape(varargin,2,[]) % pair is {propName;propValue}
   inpName = lower(pair{1}); % make case insensitive
   
   if any(strcmp(inpName,optionNames))
       % overwrite options. If you want you can test for the right class here
       % Also, if you find out that there is an option you keep getting wrong,
       % you can use "if strcmp(inpName,'problemOption'),testMore,end"-statements
       options.(inpName) = pair{2};
   else
       error('%s is not a recognized parameter name',inpName)
   end
end

filename = ([options.prefix 'Sub_' num2str(options.subject) '_Run_' num2str(options.run) '_' ... 
datestr(options.date) '.mat']);
s = load([options.directory filesep filename]);
 
writefile=sprintf('Run_%d.par', options.run);
tempts=[s.expinfo.data.timestamp];
tempcn=[s.expinfo.data.conditon];
tempdn=[s.expinfo.data.rt];
tempwt=ones(1,length(tempcn));
%Make sure the condition numbers start at 1.
%If a condition is labeled 0, this is a problem.
%I think 0 is the implicit baseline or something
if(min(tempcn)<1)
 tempcn=tempcn+1;
end
parmatrix=[tempts' double(tempcn') tempdn' tempwt']
dlmwrite(writefile, parmatrix, '\t')
end