Using bxh_eventstats

This document is intended to serve as a starting point for using bxh_eventstats, a program that collects and averages fragments of the hemodynamic response in a 4-D time-series. These fragments, or "epochs", are time-locked to "events" (stored in XML events files) selected by the user using an event "query". The duration of the epoch and starting time relative to the event onset time can be specified by the user. Multiple queries can be specified. Epochs for events which occur between image acquisitions are cubic-spline interpolated. The results of a given query can be optionally correlated to a vector template, or to the results of another query.

The requirements of bxh_eventstats are:

Usage (shown on multiple lines for readability):

  bxh_eventstats [opts]
                 PREFIX
                 IMG1.bxh EVENTS1a.xml,EVENTS1b.xml
                 IMG2.bxh EVENTS2a.xml,EVENTS2b.xml
                 ...

The first non-option argument specifies the prefix for all output filenames. This prefix may contain directory names, and may be a full or relative pathname. So for example, the prefix "output/stats" will send all output to the subdirectory named "output", with all output filenames starting with the prefix "stats".

The next arguments must come in pairs. The first argument of each pair is an input 4-D image in BXH or XCEDE format. The second argument is a list of one or more XML events files associated with that image. If there are more than one XML events files, the file names must be separated by commas. Naturally, the filenames themselves are prohibited from having commas.

The behavior of bxh_eventstats is parameterized by many options. Options to bxh_eventstats can be specified in two ways. The first is directly on the command-line, using options of the style --OPTION or --OPTION OPTIONARG. The second, and most common way is to put the options in an options file and instruct bxh_eventstats to read the options from this file using the --optsfromfile option. The option names in the option file omit the leading double dash (--). A documented list of all options is in the example options file eventstats_opts.txt.

An example usage is as follows (newlines added for readability):

  bxh_eventstats --optsfromfile eventstats_opts.txt
                 run001.bxh eventsRun1.xml,qa_events_run001.xml
                 run002.bxh eventsRun2.xml,qa_events_run002.xml
                 run003.bxh eventsRun3.xml,qa_events_run003.xml
                 run004.bxh eventsRun4.xml,qa_events_run004.xml

The above example collects and averages fragments of the image files run00*.bxh. Each file has two XML events files associated with them, one from stimulus presentation software, and another from the output of a quality assurance (QA) program.

Queries

Queries are used to select events whose onsets will be used to calculate the starting times of hemodynamic response fragments, or "epochs". These epochs will be averaged together to create an "epoch average" and written as output images. Multiple epoch averages can be created using different queries. These fragment collections are also known as "bins". In other analysis programs, you may be required to explicitly specify onset times by creating a timing file -- here you specify timings by selecting or excluding particular events by matching some of their defining characteristics.

There are two event query languages supported by bxh_eventstats: "event" and "XPath". The examples in this document will use only the "event" query language. For more info, see the guide to the "event" query language. For more info on XPath, see the XPath specification. (For XPath afficionados, note that any XPath queries are applied as predicates to each event element, as if it had been specified as //events/event[QUERY])

An example event in an XML events file is shown below:

  <event type="shape">
    <onset>60.4</onset>
    <duration>1.5</duration>
    <value name="color">red</value>
    <value name="shape">square</value>
    <value name="position">center</value>
  </event>

Note that this event has onset and duration fields, as well as several "values", indicating various characteristics of this event. These characteristics, as well as onset, duration, and other special fields can be matched in a query. For example, specifying the following query in the option file:

  querylabel RedSquare
  query "$type=='shape' & %color=='red' & %shape=='square'"

will create a bin called "RedSquare" that collects epochs time-locked to all events whose "color" and "shape" values are "red" and "square" respectively. This kind of query is called a "primary query". Note: the '$' and '%' prefixes are meant to distinguish names of special fields from the names of "value" fields; if there is no conflict, then the prefixes can be omitted.

bxh_eventstats also supports the filtering of these events based on other events that are occuring at the same time. Suppose audio stimuli are running independently but simultaneously with the visual stimuli. An example event:

  <event type="audio">
    <onset>55</onset>
    <duration>10</duration>
    <value name="frequency">1000</value>
  </event>

Suppose the red square visual stimuli are the primary events that interest you, but you would like to look at only those that occur simultaneously with events similar to the one above. Then you can use an additional "filter query", which specifies an additional restriction on the events selected for the bin:

  querylabel RedSquareTone
  query "$type=='shape' & %color=='red' & %shape=='square'"
  queryfilter "$type=='audio' & %frequency=1000"

If a filter query (specified by a queryfilter line) is specified for one bin in an option file, then a query filter must be specified for all bins. Empty filter queries of the form:

  queryfilter ""

act as a pass-through filter, and are useful if you don't need to filter anything, but are required to specify a queryfilter option for a given bin.

The third type of query, an "epoch exclusion query", is used to exclude an event from a bin if any matched exclusionary event overlaps with the epoch surrounding that event. This is useful if you are using the events output of fmriqa_generate.pl, which generates several QA metrics for each acquired image volume. An example QA event:

  <event>
    <onset>3</onset>
    <duration>1.5</duration>
    <value name="volmean">244.938</value>
    <value name="cmassx">117.079</value>
    <value name="cmassy">133.368</value>
    <value name="cmassz">39.6865</value>
    <value name="volmean_z_grand">0.969522618695653</value>
    <value name="cmassx_z_grand">1.39452591264842</value>
    <value name="cmassy_z_grand">0.800837946534433</value>
    <value name="cmassz_z_grand">0.791582533551492</value>
    <value name="volmean_z_indiv">0.969522618695653</value>
    <value name="cmassx_z_indiv">1.39452591264842</value>
    <value name="cmassy_z_indiv">0.800837946534433</value>
    <value name="cmassz_z_indiv">0.791582533551492</value>
  </event>

If you wanted to select "red square" events, but excluding those events whose epochs include volumes whose mean intensity is more than three standard deviations from the average, you could use:

  querylabel RedSquare
  query "$type=='shape' & %color=='red' & %shape=='square'"
  queryepochexclude "volmean_z_indiv > 3"

Just like queryfilter, if you specify queryepochexclude for any bin, you must specify it for all bins. An empty queryepochexclude ("") acts like a pass-through filter, excluding nothing.