User Tools

Site Tools


jvs:fscan:manual:chapter2:reference

fScan Reference Manual, Chapter 2 (CmdLineOptions): reference

Reference -- Specify timing information

usage: -reference length LENG1 LENG2 ... labels LABEL1 LABEL2 ... delay DELAYTIME skip SKIPTIME (etc.)

REFERENCE has many modifiers, which can be combined in a single -ref command or listed in separate -ref commands within a single command line. The “usage” line above shows only a few common modifiers. Arguments in lower case are reserved words entered as shown (or abbreviated); arguments in upper case are numbers or names that you supply.

The complete option list is:
-reference labels LABEL1 LABEL2 …
-reference codes CODE1 CODE2 …
-reference length LENG1 LENG2 …
-reference skip SKIPTIME
-reference delay DELAYTIME
-reference total TOTALTIME
-reference bin BINSIZE
-reference offset OFFSETTIME
-reference cycles
-reference events
-reference starts
-reference hrf LATENCY
-reference hrf LATENCY TRANSITION
-reference hrf LATENCY RISE WIDTH FALL [UNDERSHOOT RECOVERY]
-reference hrf LATENCY DIP DEPTH RISE WIDTH FALL UNDERSHOOT RECOVERY
-reference name REFNAME
-reference expand [REF0] [TOTSECS SECSPERPOINT]
-reference sine CYCLESECS TOTSECS PHASESECS [SECSPERPOINT]
-reference convolve [REF0] CONVREF
-reference mask [REF0] MASKREF
-reference correlate REF2
-reference response [FLAG]
-reference schedule [GROUP]
-reference new
-reference REFNAME write schedule [PREFIX]

  • SKIP -The amount of time to ignore at the beginning of the time series
  • DELAY -Indicates the expected delay between the reference time and the signal response (e.g. hemodynamic delay)
  • OFFSET -A fixed time offset to be added to every reference time point (e.g to correct global synchronization)

Note: Times for SKIP, DELAY, TOTAL, BIN, & LENGTH can be followed by 's' or 'i' (or 'S'/'I') to specify seconds or images (seconds is default).

For blocks or cycles, only 1 full cycle needs to be specified; it will be expanded by repetition to fill the total time series being analyzed. (EXPAND can be specified to force expansion during creation.)

Reading Schedule-format timing files

SCHEDULE is used to create a reference time course based on linked “schedule” files (see -set schedule). Schedule files are typically in a 3-column text format indicating the onset and duration of different events; each file corresponds to a different type of event. Schedule files can be organized in groups to allow the events for a task to be separated in different ways. Within a group, events should not overlap in time. Schedule groups can be specified by either a number or a single letter. Three naming conventions are recognized for grouping schedules:

   schXG_NAME          where X is a number and G is a single letter 
   sch_G_NAME          where G is a number or a single letter 
   sch_TG_NAME         where G is a number and T is any text not including '_' 

NAME above can be any condition label that makes sense to you. If the filename ends in “.txt” that suffix will not be included in the label names.

The default schedule group includes any schedule files that do not match the above naming convention, or for which G is either a number or the letter 'a'. In general, if schedule files are organized in analysis groups the group should be specified explicitly when using the '-ref schedule' command.

Examples of schedule file groupings would be:

 sch6a_CONDA1.txt           sch_s1_FIRSTGRP_COND1.txt 
 sch6a_CONDA2.txt           sch_s1_FIRSTGRP_COND2.txt 
 sch6b_CONDB1.txt           sch_s2_SECONDGRP_COND3.txt 
 sch6b_CONDB2.txt           sch_s2_SECONDGRP_COND4.txt 
 
   -ref schedule b name schedb     (loads events labeled 'CONDB1' and 'CONDB2') 
   -ref schedule 1 name sched1     (loads events labeled 'FIRSTGRP_COND1' & 'FIRSTGRP_COND2' 
 
The default group depends on what filenames have been linked. 
If only the first column (sch6...) files were linked: 
   -ref schedule                   (loads only events labeled 'CONDA1' and 'CONDA2') 
If the second column (sch_s...) files were linked the default would include multiple groups ('a', 1, and 2) 
which is almost certainly not what you want.  If you link multiple schedule file groups to your data sets 
you should probably explicitly specify which group you want when creating a new reference time course. 

Writing Schedule files

To write out a reference time course as a set of 3-column “schedule” files, use the following command:

 
  -ref REFNAME write schedule [PREFIX] 

  Where REFNAME is the name of an existing reference time course (use $lastref to get the current active time course). 
  PREFIX is the filename prefix you want to use; the default PREFIX is "sch". 

The REFNAME time course must have labels specified for the different conditions. For each condition label (CONDLABEL), a separate schedule file will be created, named: PREFIX_CONDLABEL.txt.

 
  For example, consider the sample reference time course named MYREF: 
  To view your reference time course use: 
    -show ref myref 

     Time    Value Duratn Label 
    0.000     1.0   10.0 rest 
   10.000     2.0   30.0 taskon 
   40.000     3.0   10.0 rest 
   50.000     2.0   30.0 taskon 
   80.000     1.0   10.0 rest 
   90.000     2.0   30.0 taskon 
  120.000     3.0   10.0 rest 
   
  To write MYREF out as schedule files you could use: 
    -ref myref write schedule sch3a 
  which would 2 generate files, sch3a_rest.txt and sch3a_taskon.txt: 
     sch3a_rest.txt            sch3a_taskon.txt 
    0.0    10.0   1            10.0   30.0   1 
   40.0    10.0   1            50.0   30.0   1 
   80.0    10.0   1            90.0   30.0   1 
  120.0    10.0   1 

Expanding or convolving a reference time course

For some statistics (t-test, correl), reference time course may be convolved with a canonical response function (e.g. hemodynamic response) before being used. The RF can be specified globally using '-set convolve REFNAME', in which case the named REFNAME will be used automatically when appropriate. A convolution can also be specified explicitly using '-reference convolve' as part of the reference definition.

 
    E.g.:  -ref hrffunc.txt name MyHRFunc 
           -ref 10 10s convolve MyHRFunc name MyTask 

T-test convolutions use only fixed delays

See Also:
ILists,
EventLists,
ILists,
Queries

fScan Home,
fScan Manual,
CmdLineOptions,
Manual Help

jvs/fscan/manual/chapter2/reference.txt · Last modified: 2016/06/11 03:42 by voyvodic