NAME

zil_soas.pl - parses DMDX input and .zil files to output times in TRs

If you have an input file myexp.rtf, and an output file my_exp.zil in the same directory. You want the stim / response times from the second subject. The first 6 scans were dummy scans, and the pulse from the scanner occurs at the beginning of the scan. The subjects potential responses were button press 1 (+Bit0 in DMDX), and button press 2. 

zil_soas.pl myexp.zil -subject 2 -dummies 6 -pdelay 0 -respstr +Bit0 -respstr +Bit1

will output the stimulus and response times in TRs relative to the onset of the first non-dummy scan, as a text file myexp_sub2.txt

See ZilUtility for more information.

Note: requires RTF::Parser, available via CPAN: http://search.cpan.org/author/PVERD/RTF-Parser-1.07/

DESCRIPTION

zil_soas.pl takes a DMDX .rtf input file, and an output .zil file, and outputs the recorded stimulus and response events in terms of TRs for use - in particular - with SPM.

FEATURES

zil_soas parses the rtf and zil files to estimate the onset times of the first event relative to the beginning of the experiment. It uses scanner pulses recorded in the zil file to calculate a best estimate of the TR, if required. Outputs are text files for each subject in the zil file, specifying stimulus and response times in terms of the beginning of the first non-dummy TR.

SYNOPSIS

zil_soas.pl [options] input_file.zil

Options: 

-help          print help message and quit
    -man           full documentation and quit
    -verbose       more messages, more detailed help output
    -quiet         no messages during operation
    -clobber       overwrite preexisting files
    -rtf           specify input rtf file
    -subject       one or more subjects to convert
    -all           convert all subjects 
    -outdir        directory to output files
    -outroot       root name of files to output 
    -pdelay        time (ms) from start of scan to pulse
    -tr            TR (usually calculated)
    -esttr         starting guess for TR if calculated
    -limit         margin by which estimated TR may be incorrect
    -tol           allowable error in ms for estimated TR
    -misstrs       TRs to miss (any spacebar events, preceding pulses)
    -dummies       dummy scans
    -scanpulses    strings defining scan pulse events
    -respstrs      strings defining responses
    -omititem      item numbers to omit
    -nullval       string to signal null value
    -version       returns version no

OPTIONS

-help
Print a long help message and exit.
-man
Prints the manual page and exit.
-verbose
Gives out moderately helpful warning and other messages during image conversion. Adding -verbose to -help outputs more help.
-rtf

Specify input rtf file. If not specified, the rtf file is assumed to have the same name (and directory) as the .zil file. If this is not correct, use the rtf option thus: zil_soas.pl myexp.zil -rtf ../myexp.rtf

-showvals
Prints out the output of stimulus, response times to the screen for review
-quiet
Turn off any messages during conversion
-clobber

Will overwrite preexisting files. If there are preexisting files, and you do not use -clobber, will exit with an error message.

-subject
Specify to convert, e.g. zil_soas.pl myexp.zil -subject 1 -subject 3 will convert subject 1 and 3 only. Defaults to all subjects if not set.
-all
Convert all subjects in the file. This is the default.
-outdir

Directory to output files to; e.g. zil_soas.pl myexp.zil -all -outdir /home/me/exp_onsets The default output directory is the current directory.

-outroot
Root name of files to output (extension ignored); e.g.

zil_soas.pl myexp.zil -subject 1 -subject 2 -outname myfile will create output files: ./myfile_sub1.txt ./myfile_sub2.txt. zil_soas derives the default file name from the name of the input data file. Thus zil_soas.pl myexp.zil -subject 1 will generate files: ./myexp_sub1.txt

-pdelay
Sets delay in onset of scanner pulse after the start of the TR. Value is in milliseconds. For example, if the TR is 3 seconds, and the pulse is right at the end to fthe TR, and lasts 50 ms, then the command line might be: zil_soas.pl myexp.zil -subject 1 -pdelay 2950
-tr
Set the exact TR (in milliseconds) by hand, rather than calculating from the .zil file - e.g.: zil_soas.pl myexp.zil -subject 1 -tr 3000
-esttr
Give starting estimate for TR, to help in calculating the correct TR, e.g.: zil_soas.pl myexp.zil -subject 1 -esttr 3000
-limit
Give limits within which to search for exact TR; for example: zil_soas.pl myexp.zil -subject 1 -esttr 3000 -limit 100 will search between 2900 and 3100 for the best TR. Default is 200.
-tol
Required accuracy of TR estimate in ms. For example: zil_soas.pl myexp.zil -subject 1 -esttr 3000 -tol 0.1 will allow a 100 microsecond error in the TR estimate. Default is 0.05;
-misstrs
Sometimes, you may wish to start the experiment with one or more spacebar presses, rather than letting the scanner trigger the start of the experiment; this will show up as extra '0' events in your DMDX file which do not correspond to a scanner pulse. You can tell the program not to treat these intial '0' events as a pulse using this option, e.g.: zil_soas.pl myexp.zil -subject 1 -misstrs 1
-dummies
A scanning session usually begins with several dummy scans. The TR values needed for the analysis are in relation to the beginning of the first non-dummy TR (where 0 = the beginning the the first TR). Use this option to set the number of dummy scans and therefore the number of TRs to subtract from the TR values in the output file, relative to the start of the experiment: zil_soas.pl myexp.zil -subject 1 -dummies 6
-scanpulses
Strings in the zil file signifying scanner pulse events - onset, offset or both. For example, if the scanner pulse is recorded as 'Bit1' in the zil file, use: zil_soas.pl myexp.zil -subject 1 -scanpulses +Bit1 -scanpulses -Bit1

The default corresponds to -scanpulses +Bit0 -scanpulses -Bit0

-respstrs
Strings in the zil file signifying response events. For example, if the response can be on button 1 or button 2, and these are recorded as '+Bit2' and '+Bit3' in the zil file, use: zil_soas.pl myexp.zil -subject 1 -respstrs +Bit2 -respstrs +Bit3

The default corresponds to -respstrs +Bit1

-omititem
Event numbers in the DMDX file which should not be noted in the output file. For example, you might not want to model the onset of a fixation cross in the output file, and you may have signalled this in your DMDX file by giving the fixation cross and event number of 1000. In this case, to omit these events from the output: zil_soas.pl myexp.zil -subject 1 -omititem 1000 You can specify more than one number to omit, with several repeats: e.g. zil_soas.pl myexp.zil -subject 1 -omititem 1000 -omititem 2000
-nullval
String / number to signal null value in the output file. Default is 'NaN' for use with matlab. If you prefer (e.g.) 0: zil_soas.pl myexp.zil -subject 1 -nullval 0
-version
Returns version no to the console.