| title | tags | ||
|---|---|---|---|
How to use ft_checkconfig |
|
The function ft_checkconfig checks the input configuration (cfg) for the main FieldTrip functions. This is similar to what ft_checkdata does for the input data. The ft_checkconfig function is automatically called when you use a FieldTrip function. You may not even notice this, unless it gives you feedback about your cfg (i.e., warning or error messages).
ft_checkconfig can also control the output cfg (i.e., the cfg that is given back by the function, usually data.cfg) and give more elaborate feedback to the user. This tutorial explains what ft_checkconfig does, and importantly, how you can control it and use it to your advantage!
This function checks the input cfg of the main FieldTrip functions in three ways:
1: It checks whether the cfg contains all the required options, it gives a warning when renamed or deprecated options are used, and it makes sure no forbidden options are used. If necessary and possible, this function will adjust the cfg to the input requirements. If the input cfg does NOT correspond to the requirements, this function gives an elaborate warning message.
2: It controls the relevant cfg options that are being passed on to other functions, by putting them into substructures or converting them into the required format.
3: It controls the output cfg (data.cfg) such that it only contains relevant and used fields. The size of fields in the output cfg is also controlled: fields exceeding a certain maximum size are emptied.
When you use a FieldTrip function, this automatically calls ft_checkconfig to check the cfg you supplied. If necessary, ft_checkconfig will give you feedback. How can you control this feedback? As explained in the help documentation
% The behavior of checkconfig can be controlled by the following cfg options,
% which can be set as global FieldTrip defaults (see FT_DEFAULTS
% cfg.checkconfig = 'pedantic', 'loose' or 'silent' (control the feedback behavior of checkconfig)
% cfg.trackconfig = 'cleanup', 'report' or 'off'
% cfg.checksize = number in bytes, can be inf (set max size allowed for output cfg fields)
When you use a FieldTrip function, this automatically calls the function ft_defaults, which takes care of path setting, plus it sets defaults to be used throughout FieldTrip. It does this by creating a global variable called ft_default, i.e. a variable that is available to all functions, but not directly visible to the user. You can make it visible by typing global ft_default. The variable ft_default has the following fields and default settings that pertain to ft_checkconfig.
ft_default.checkconfig = 'loose';
ft_default.trackconfig = 'off';
ft_default.checksize = 1e5;
These settings control the behavior of ft_checkconfig. If you want to change these settings, either do it via the global variable (this way they will apply to all FieldTrip functions and automatically be added to the cfg), or do it directly via the cfg when you call a specific function. What are the available options?
cfg.checkconfig: 'pedantic', 'loose' or 'silent'
This setting determines the type of feedback ft_checkconfig gives about the input cfg. An important function of ft_checkconfig is to check whether the input cfg contains all the required options, and no renamed, unused, deprecated or forbidden options. If possible, ft_checkconfig will adjust the cfg to the input requirements and give feedback to the user. You can control the type of feedback given. This can either be 'silent', which means no feedback is given at all, or 'loose' which means warnings are given for all inconsistencies, or 'pedantic', which means errors are given for each inconsistency in your input cfg. Note that a missing required field in the cfg will always lead to an error, because FieldTrip simply will not run without it.
To give an example using ft_freqdescriptives, if your cfg contains the field 'jacknife' (which was used in a previous version of FieldTrip but has since been renamed to 'jackknife'
cfg = [];
cfg.jacknife = 'no';
test = ft_freqdescriptives(cfg, freq)
You will get the following feedback
Warning: use cfg.jackknife instead of cfg.jacknife
In this case, you don't have to do anything: ft_checkconfig will rename the field for you, and ft_freqdescriptives can do its job. Of course the idea is, that you will use this feedback to improve your scripts!
Note: the feedback ft_checkconfig gives on your input cfg is not exhaustive, meaning that not all possible options you could come up with will be taken care of. It mainly ensures backward compatibility of old scripts, and checks some important required and forbidden fields.
cfg.trackconfig: 'cleanup', 'report' or 'off'
ft_checkconfig can also control the output cfg. It tracks the cfg from the moment you put it into a function until it comes out again (usually as data.cfg). This can provide you with useful feedback: which of the options you specified were actually used? Which options have been added as defaults by the FieldTrip function? You can control the behavior of configtracking: 'report' will only give you a report, 'cleanup' will give both a report and a cleaned output cfg. If you do not want to use configtracking at all, use 'off'.
cfg.checksize: number in bytes, can be inf
This determines the maximum size allowed for output cfg fields (i.e. the data.cfg). Some fields in the output cfg can be very large, e.g., the cfg.grid field when you do sourceanalysis. To avoid that several MBs or even GBs of your disk space are taken up by the data.cfg, you can set a maximum and ft_checkconfig will empty all the cfg fields that are too big, before adding the cfg to the data. Crucial fields such as the cfg.trl and cfg.event will never be removed (currently, the following fields are ignored: 'checksize', 'trl', 'trlold', 'event', 'artifact', 'artfctdef', 'previous'). The default is set to 100000 bytes, but you can change this to anything you want. If you do not want any fields to be removed, set checksize to inf.
Ok, let's see this in action. In this example the tutorial dataset is used, but you can of course use this on any dataset. If you are using the tutorial dataset, first get the trial definitio
cfg = [];
cfg.dataset = 'Subject01.ds';
cfg.trialdef.eventtype = 'backpanel trigger';
cfg.trialdef.prestim = 1;
cfg.trialdef.poststim = 2;
cfg.trialdef.eventvalue = 3;
cfg = ft_definetrial(cfg);
Now, run ft_preprocessing with trackconfig set to cleanup. This will give you both a report (on screen) and a cleaned data.cfg:
cfg.trackconfig = 'cleanup';
cfg.unused = 1; % to test whether it works!
data = ft_preprocessing(cfg);
The report will look like this:
The following config fields were specified by YOU and were USED
cfg.dataset
cfg.trackconfig
cfg.checkconfig
cfg.datafile
cfg.headerfile
The following config fields were specified by YOU and were NOT USED
cfg.trialdef
cfg.trialfun
cfg.unused
The following config fields were set to DEFAULTS and were USED
cfg.channel
cfg.removemcg
cfg.feedback
cfg.precision
cfg.padding
cfg.headerformat
cfg.dataformat
cfg.dftfilter
cfg.lpfilter
cfg.hpfilter
cfg.bpfilter
cfg.bsfilter
cfg.medianfilter
cfg.reref
cfg.refchannel
cfg.implicitref
cfg.continuous
cfg.polyremoval
cfg.detrend
cfg.blc
cfg.hilbert
cfg.derivative
cfg.rectify
cfg.boxcar
cfg.absdiff
cfg.conv
cfg.montage
The following config fields were set to DEFAULTS and were NOT USED
cfg.removeeog
cfg.polyorder
cfg.blcwindow
cfg.lpfiltord
cfg.hpfiltord
cfg.bpfiltord
cfg.bsfiltord
cfg.lpfilttype
cfg.hpfilttype
cfg.bpfilttype
cfg.bsfilttype
cfg.lpfiltdir
cfg.hpfiltdir
cfg.bpfiltdir
cfg.bsfiltdir
cfg.medianfiltord
cfg.dftfreq
cfg.dftinvert
Thus, it specifies which options were set by you and whether they were used. As you can see, the cfg.unused indeed ends up as "set by you, not used". Furthermore, the report shows the options that were added by the ft_preprocessing function, and whether they were actually used for your analysis. There is quite a list of unused defaults. When we now look at the output cfg we see that it is nicely cleaned. Compare this with a call to ft_preprocessing without using trackconfig.
cfg.trackconfig = 'off';
data2 = ft_preprocessing(cfg);
data.cfg % cleaned
data2.cfg % not cleaned
This example showed how trackconfig can be used when doing preprocessing. The same approach can be applied for all the main FieldTrip functions. (Currently, trackconfig has been implemented in about 20 FieldTrip functions, this will be expanded.)
As explained above, you can use cfg.checksize to set a limit to the size of fields in the output cfg, ft_checkconfig then empties fields that are too big. Crucial fields such as the trl will never be removed. This all pertains to the output cfg, i.e. the cfg that comes out of the function (depending on the FieldTrip function you are using, this is either cfg or data.cfg). This does not change any data.cfg.previous fields.
However, you may have lots of analysed data on disk, with data.cfgs that might be taking up quite some of your disk space. Especially after doing beamforming (sourceanalysis) the output cfg can be large, since the grid is always kept in the data.cfg. If you would like to free some disk space (and are sure you can do without these fields), the following trick can be applie
%%% script to downsize cfgs of stored data
%%% this can free up significant amounts of disk space
downsizefiles={
'/mydir/dataset1'
'/mydir/dataset2'
'/mydir/etc.'};
for k=1:length(downsizefiles)
load(downsizefiles{k})
data.cfg.checksize=100000;
data.cfg=ft_checkconfig(data.cfg, 'checksize', 'yes');
save(downsizefiles{k}, 'data')
end
This way ft_checkconfig will run recursively through the entire data.cfg, including all the previous fields, and empty the fields that are larger than the specified maximum. This can be used on all FieldTrip data.