Reprocess / Export Tracks

 

What is Reprocess / Export Tracks?
Running from the Dialog
Running from the Command-Line Interface (CLI)
Results
Technical points and hints
    Sequence of Processing
    Temporal Filtering
    Spatial Filtering and Adding Null Track
    ROIs
    Specifying list of tracks
    Exporting Computed Tracks

What is Reprocess / Export Tracks?

This is a versatile tool to read EEG files (or other tracks-like files), then export them to some new files after applying some basic transformations . They include things such as:

 

Input files can be anything that looks like tracks:

 

See here what the ouput files can be, plus the special case of frequency files .

Running from the Dialog

Call the dialog from Tools | Export tracks menu, which is context sensitive:

 

The following dialog pops out. Fill the parameters which are relevant for you, then click either on Process Current or Batch Process (according to how the dialog was invoked):

Tracks or ROIs

 

Tracks

From an opened EEG:
Prefilled with the current selected tracks, otherwise with the current displayed tracks.

In Batch Mode:
On first call, default is *, meaning all regular tracks .

You can of course modify this list. See important note below about notation .

Names from XYZ:

Optionally pointing to a file with the electrodes coordinates and names. The names of the electrodes are taken from this file , overriding the original names from the EEG (i.e. you can rename the electrodes).
Be careful that the list above respect these names, otherwise you will get an error message.

Constraints as in the link mechanism must be respected, such as same number of electrodes, same order, etc...

ROIs

The ROIs to be used in the export.

Note 1: The ROIs option and the Tracks field above are mutually exclusive.

Note 2: The ROIs option and the Add Null Tracks below are also mutually exclusive.

Input Time

 

Interval

Export a time interval, specified in time frames .

From

First time frame to be exported.

to

Last time frame to be exported.

End of File

Automatically set the last time frame to export to the actual end of the current file . Useful in Batch Mode, if the files have different lengths.

Triggers To Keep

Only the time frames contained in the specified list of triggers / markers will be exported.

Triggers To Exclude

Only the time frames excluded from the specified list of triggers / markers will be exported.

Processing Parameters

 

Appending Null Track(s):

A list of track name(s) that will be appended after the last input tracks. Its/their values will be set to 0.

The intent is to add a single reference track that was not included in the recording file, though you might go beyond this and add as many tracks as you wish.

Note: Appending Null Tracks and applying ROIs are mutually exclusive.

Filters:

Also see these notes about:

No Filters

No filtering at all, just using the raw data from the file.

Use Current Filters

Using the filters currently set in the current opened EEG. Useful as a kind of "Save what I see" feature.

Note: If user has added null tracks, these tracks will also be filtered.

Other Filters

Using these specific filters, bypassing any filters that might be in current use. This will pop out the usual Filter Dialog for you to fill the relevant filters parameters.

Note 1: You might have to fill the Sampling Frequency entry of this dialog, though.

Note 2: If user has added null tracks, these tracks will also be filtered.

Reference:

Also see this note about the Sequence of Processing .

No Reference

Use the same reference as when the file(s) was(were) written, that is, no change in reference.

Use Current Reference

Use the reference currently in use. Useful only if the files have already been opened in Cartool, and the user has changed the reference.

Average Reference

Use the average reference, overriding current reference.

Note: If user has added null tracks, these tracks will be included in the new average reference computation .

Other Reference

Use the average of the specified list of electrodes. If only one electrode is specified, this will be the reference.

Note: If user has added null tracks, these tracks can also be used as reference.

Baseline Correction:

 

Apply Baseline Correction

Select this to apply some baseline correction (subtracting each track with its average within a given time period).

Note: If user has added null tracks, these tracks will also have be baseline-corrected.

From

First time frame of the baseline.

This is an absolute value, not a relative one, and should be within the range of available time frames. Otherwise it will be clipped to these limits.

to

Last time frame of the baseline.

This is an absolute value, not a relative one, and should be within the range of available time frames. Otherwise it will be clipped to these limits.

The limits specified need not to be within the range of the time period exported. They can be whatever you wish, Cartool will handle all the cases gracefully.

End of File

Automatically set the last time frame of the baseline correction to the actual end of the current file. Useful in Batch Mode , if the files have different lengths.

Rescaling:

Note: If user has added null tracks, these tracks will also be rescaled.

No Rescaling

What is says.

Rescaled By

Rescale the EEG values by multiplying with the provided value. Negative factors are allowed to perform a polarity inversion.

GFP Normalize

For each EEG, compute the mean GFP (or RMS) over the selected time period, then divide the EEG values with it.

See this point on positive data and also this point.

Output Time

 

Output Time is:

 

Sequential

The input time period, once processed, is outputted sequentially.

F.ex. if the input time range selected is from 100 to 149 time frames, then the resulting output will be 50 time frames long.

Average

The input time period, once processed, is averaged, and a single value is outputted.

F.ex. if the input time range selected is from 100 to 149 time frames, then the resulting output will be 1 time frame long.

Time Downsampling:

 

Downsample by Integer Ratio:

Downsample the data by the specified integer ratio (>1). The resulting sampling frequency will be the original one divided by this ratio.

The method used is equivalent to a CIC (Cascaded Integrator-Comb) filter, followed by a light High Pass FIR (compensation) filter, and finally the decimation itself.

 

Also note that downsampling is disabled in the following cases:

  • Input Time Period is taken from Triggers

  • Averaging the output value

Output File

 

Filename Infix 

The exported filenames will have these characters inserted. Default is "Export".

Output File Type

A drop-down list with currently the following available types:

TXT (text)

Text file, actually the same as the .ep file except for the extension.

EP (text)

Text file, basically a plain matrix of data. See the .ep file specification.

EPH (text)

Text file, basically the same as the .ep above but with an additional header line. See the .eph file specification.

SEF (binary)

Binary file, see the .sef file specification.

Useful when exporting original recording file(s), or to include the electodes / ROIs names in the new file(s).

EEG (binary)

Binary file, file format from BrainVision . This is the default option as it is a quite versatile format.

EDF (binary)

Binary file, see the .edf file specification.

Useful only for data interchange, otherwise don't use (loss of precision)!

RIS (binary)

Binary file, see the .ris file specification.

Used mainly if you are already testing other .ris files, and want to visualize the results in 3D.

Options

 

Export Underlying Markers

Also exports the markers belonging to the selected time period, creating a .mrk file

Open File(s) Upon Completion

...of the exportation. Just be careful in Batch Mode , this could open a lot of files (read: crash)! (the original EEG files are opened one at a time, then closed when done).

Concatenate all into 1 File

If you have Batch Process a list of files, then the results will be concatenated into a single output file. Note that this happanes as the last step of the Reprocess Tracks, so what is appended depends on the parameters chosen above!

Markers will be conveniently added at each starting point of the original files.

Process Current

Enabled when called from an EEG window, the exportation will apply to this file only.

 

This button remains disabled until all the parameter dialogs have received enough (and consistent) informations . If this is not the case, first check the current dialog: if its "Next" button is disabled, the problem is in the current dialog. Otherwise, browse the other dialogs for some missing informations.

Batch Process

Enabled when not called from an EEG window:

  • Clicking this button will open a dialog from which you can select a set of files , within a single directory.

  • Using Drag & Drop, you can drop files in the dialog and process them directly. Plus, it allows you to pick files from different directories , if you can select them through a handy utility like Everything beforehand.

 

This button remains disabled until all the parameter dialogs have received enough (and consistent) informations . If this is not the case, first check the current dialog: if its "Next" button is disabled, the problem is in the current dialog. Otherwise, browse the other dialogs for some missing informations.

Cancel

Quit the dialog.

Help

Launch the Help to the right page (should land on this page...).

Runnning from the Command-Line Interface (CLI)

You can call the Reprocess toolbox directly from the command-line, see the full syntax and examples here .

Results

Technical points and hints

Sequence of Processing

The various available processing follow a very precise sequence, which is:

Temporal Filtering

Cartool uses a classic sliding window method, which is mandatory to avoid artifacts, especially with high-pass filter:

 

As a consequence, Cartool reads / filters / processes way more points than are actually written to file. This is the only way to ensure the results are correct, so be patient, it has to be done only once after all...

filtersize depends on the sampling frequency of the current file. The higher the sampling frequency, the bigger the filtersize variable, the longer the computation.

Spatial Filtering and Adding Null Track

The Spatial Filter depends on a .xyz coordinates file to operate, as it needs the spatial locations of each and every electrodes. It is also requires that the number of tracks in the EEG file and the number of electrodes in the .xyz file be exactly the same . Cartool enforces that for you all the time, so nothing to worry here.

However, in case the user required for an additional null track , the EEG has suddenly one more dimension. To properly apply any Spatial Filter, the user should then select the Other Filter option , and drop a correct .xyz file with an additional electrode, too. This way both EEG and electrodes coordinates dimensions will match again.

In case of mismatch, Cartool will likely complain, skip the Spatial Filter step(!), and add an error message in the .vrb verbose file...

ROIs

If a .rois file has been provided (see Creating ROIs), all members of a given roi are averaged together as a final step. Then only the averaged value is written to file.

If you intend to do some stats later on these roi-ed files, think twice! In fact, it is a far better practice to not compute the rois yourself (for the stats), but let the Statistics processing do it for you . The main problem being that data normalization that will be wrong, as the original data will be lost, so will be the original GFP. Plus, why fill your drive with another set of files?

But if you just want ROIs for some display purpose, or re-ordering your tracks, just proceed!

 

Noteworthy is a side-effect of Exporting with ROIs, which is the re-ordering of the tracks that occurs. Within each roi, all tracks will follow the exact sequence given in the .rois file. See an example, first the original order, then one roi with a quarter of the electrodes:

Specifying the list of tracks

You can:

 

With interval notation, the ordering is the one found in the file you are processing, and is by no mean lexicographic (à la dictionary). So in this example C1-C2 means C1, Cz, C2; and T3-T4 means T3, C3, C1, Cz, C2, C4, T4:

Exporting Computed Tracks

You can export the computed tracks by using any of the following predefined names:

Exporting frequency files

See the Results paragraph.