Cartool can be called directly from the command-line, either from Windows batch files, Matlab or Python scripts, and therefor be called as a library within external processing pipe-lines. To finer control its behavior, you can pass it options and sub-commands, which are described in this page.
This will not be a full tutorial on the CLI11 Command-Line syntax , but just a few hints to help you get the job done:
General options are used to control the main window and children windows appearance . It can also return a full, up-to-date help syntax message in case you are lost.
To get the latest, up-to-date commands and syntax, you can always call:
cartool64.exe --help or cartool64.exe <subcommand> --help
Current version can be retrieved with:
cartool64.exe --version
You can control the main window state, size and position with:
cartool64.exe --mainwindow={minimized,maximized,normal} [maximized]
--mainwindowsize=width,height
--mainwindowpos=x,y
You can skip the splash-screen with:
cartool64.exe --nosplash
And you can even select which monitor to open Cartool to:
cartool64.exe --monitor=<number>
Note that the monitor index might differ from what the Control Panel shows you, though. This is a Windows thing, sorry about that...
Opening Cartool on the top left part of the screen, resized for HD:
cartool64.exe --mainwindowpos=0,0 --mainwindowsize=1920,1080
Fast opening Cartool full screen on a second monitor:
cartool64.exe --mainwindow=maximized --monitor=2 --nosplash
You can control every new child window state, size and position by using any of these options before a given file (note the "--" before the files):
cartool64.exe --childwindow={minimized,maximized,normal} [normal]
--childwindowsize=width,height
--childwindowpos=x,y
-- <files>
Each of these parameters could be repeated for each file with different values. In case some parameters are missing, the last valid ones will be used.
Also note that, for the moment, you can not specify any parameter for the nth file without specifying the parameters of all previous files!
Single file opened maximized:
cartool64.exe --childwindow=maximized -- <file1>
First file opened normally, next one opened minimized:
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> or cartool64.exe --childwindow=normal minimized -- <file1> <file2>
First file opened normally, 2 successive files opened minimized:
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> <file3>
First file opened normally, 2 successive files opened minimized, last one opened maximized:
cartool64.exe --childwindow=normal minimized minimized maximized -- <file1> <file2> <file3> <file4>
Single file opened normally, with overridden size and position:
cartool64.exe --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>
Single file resized and repositionned, then minimized:
cartool64.exe --childwindow=minimized --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>
Two files opened normally, with overridden sizes and positions:
cartool64.exe --childwindowsize=500,250 200,800 --childwindowpos=0,0 500,250 -- <file1> <file2>
Sub-commands allow to run a specific toolbox or processing of Cartool. Each sub-command has its own set of options, which are therefor not available to other sub-commands. Sub-commands still can use some of the general options, though.
Registering Cartool to Windows allows for double-click file opening, icons and files associations etc... These associations are silently set for you by the Cartool installer, once and for all. But if anything gets corrupted, like erroneous icons and files associations, it is possible to invoke this registration manually. Still not an everyday manoeuvre, though...
Registration is a sub-command, with only one of these exclusive options :
cartool64.exe register --{yes,no,reset,help}
Also note that upon execution, Cartool will exit straight away. It might be necessary to reboot your machine if things get confusing for Windows, though most of the time, you need not.
This sub-command corresponds to the Reprocess / Export Tracks Dialog .
Getting the Reprocess / Export Tracks subcommand full syntax with:
cartool64.exe reprocesstracks --help
Which gives:
Re-process / Export tracks command
Usage: reprocesstracks [OPTIONS]
Options:
--tracks TEXT Tracks to export Special values: * gfp dis avg
--xyzfile TEXT Excludes: --roisfile
Using electrodes names from a XYZ electrodes coordinates file
--roisfile TEXT Excludes: --nulltracks --xyzfile
Computing ROIs & using ROIs names from a ROIs file
--timemin INTEGER Excludes: --keeptriggers --excludetriggers
Exporting from Time Frame
--timemax INTEGER Excludes: --keeptriggers --excludetriggers
Exporting to Time Frame
--keeptriggers TEXT Excludes: --timemin --timemax --excludetriggers
Exporting only the data from a triggers / markers list
--excludetriggers TEXT Excludes: --timemin --keeptriggers --timemax
Exporting all data but from a triggers / markers list
--nulltracks TEXT Excludes: --roisfile
List of null tracks to append
--filters TEXT A whole string of filtering options, in double quote, as coming from a verbose file
--dc,--baseline Baseline / DC correction (recommended with any High-Pass or Band-Pass filter)
--highpass FLOAT Excludes: --bandpass
High-Pass Butterworth filter
--lowpass FLOAT Excludes: --bandpass
Low-Pass Butterworth filter
--bandpass FLOATS x 2 Excludes: --lowpass --highpass
Band-Pass Butterworth filter
--order INTEGER [8 or 16] Butterworth filter order
--causal Causal filters, using only forward filtering
--notches FLOATS... Notches filter
--harmonics Needs: --notches
Adding Notches harmonics
--spatialfilter ENUM:{SpatialOutliers,SpatialOutGauss,SpatialOutWeight,SpatialIGM,SpatialIWM,SpatialMedian,SpatialIQM,SpatialMinMax} [SpatialIWM] Needs: --xyzfile
Spatial filter
--ranking Ranking data at each time point to [0..1] range
--rectification ENUM:{abs,absolute,power,squared}
Rectification, i.e. making data all positive
--envelope FLOAT Needs: --rectification
Sliding-window smoothing after rectification (positive-only data), value in [ms]
--keepabove FLOAT Thresholding data, keeping data above value
--keepbelow FLOAT Thresholding data, keeping data below value
--samplingfrequency FLOAT Default Sampling Frequency, only in case a file has none
--reference TEXT List of new reference tracks Special values: 'none' (default) or 'average'
--baselinecorr INTEGERS x 2 Baseline correction interval, in time frames since beginning of file
--rescaling TEXT Scaling factor Special value: 'meangfp'
--sequential Excludes: --average
Sequential output Default option
--average Excludes: --sequential
Averaging the time dimension
--downsampling INTEGER Downsampling ratio
--infix TEXT Infix appended to the file name
--ext,--extension ENUM:{txt,ep,eph,sef,eeg,edf,ris} [eeg]
Output file extension
--nomarkers Not saving the markers to file
--concatenate Concatenate all output into a single file
-h,--help This message
Band-Pass option excludes both High-Pass and Low-Pass options. However, it is currently allowed to specify both High-Pass and Low-Pass options, which will be internally combined into a proper High-Pass.
For a single High-Pass or Low-Pass filter, the order, if overridden, must be an even value. Current default value is 8.
For a Band-Pass filter, the order must be a multiple of 4 , as it basically sums up the high and low pass orders together. Which means the default is 8+8=16. Note that this does not follow the Matlab convention, which would erroneously show 8 instead...
Saving files to another format, f.ex. to BrainVision .eeg:
cartool64.exe reprocesstracks --infix=NewExt --ext=eeg -- <file1> <file2> <file3>
Renaming the electrodes, "borrowing" actual names from a .xyz file:
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --infix=Renamed --ext=eeg -- <file1> <file2> <file3>
Cropping the time range, from time frame 100 to 499; cropping from time frame 200 up to end-of-file (note the missing --timemax option in the latter case):
cartool64.exe reprocesstracks --timemin=100 --timemax=499 --infix=Cropped -- <file1> <file2> <file3> cartool64.exe reprocesstracks --timemin=200 --infix=Cropped -- <file1> <file2> <file3>
Keeping only some epochs, labelled as "Good" markers, from the time line:
cartool64.exe reprocesstracks --keeptriggers=Good --infix=OnlyGoodies -- <file1> <file2> <file3>
Deleting some epochs, labelled as "Bad" or "Blink" markers, from the time line:
cartool64.exe reprocesstracks --excludetriggers=Bad,Blink --infix=NoBaddies -- <file1> <file2> <file3>
Appending a null track called "MyRef":
cartool64.exe reprocesstracks --nulltracks=MyRef --infix=Nullos -- <file1> <file2> <file3>
Changing the reference to Cz, using a .xyz file to get the names right; setting an Average Reference:
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --reference=Cz --Infix=RefCz -- <file1> <file2> <file3> cartool64.exe reprocesstracks --reference=average --Infix=RefAvg -- <file1> <file2> <file3>
Downsampling files by a factor of 4, f.ex. from a sampling frequency of 1000 Hz down to 250 Hz:
cartool64.exe reprocesstracks --downsampling=4 --infix=Down -- <file1> <file2> <file3>
Concatenating files into a single file:
cartool64.exe reprocesstracks --concatenate --infix=Concat -- <file1> <file2> <file3>
You have access to all the filters from the EEG Filters Dialog .
For example, a typical band-pass for EEG (note the DC removal, for safety reasons):
cartool64.exe reprocesstracks --dc --bandpass=1,40 --notch=50 --harmonics --order=16 --infix=BandPass -- <file1> <file2> <file3>
Applying the default Spatial Filter of Cartool. Attention to the EEG and XYZ dimensions, which sould match exactly, especially if you added some null tracks:
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --spatialfilter --infix=Spatial -- <file1> <file2> <file3>
Applying some rectification + envelope, with a time window of 100ms:
cartool64.exe reprocesstracks --rectification=power --envelope=100 --infix=Envelope -- <file1> <file2> <file3>
Thresholding the data, ranking and keeping data above 0.95; keeping data either below -1 or above 1; keeping data above -1 and below 1:
cartool64.exe reprocesstracks --ranking --keepabove=0.95 --infix=Significant5 -- <file1> <file2> <file3> cartool64.exe reprocesstracks --keepbelow=-1 --keepabove=1 --infix=OutsideInterval -- <file1> <file2> <file3> cartool64.exe reprocesstracks --keepabove=-1 --keepbelow=1 --infix=InsideInterval -- <file1> <file2> <file3>