[FieldTrip] IMPORTANT: Bug in ft_freqstatistics

[Eelke Spaak]

Dear FieldTrip community,

Short version: if you did ft_freqstatistics across subjects with a
different channel ordering across data sets (which is the case if you
use ft_channelrepair), your results might have been erroneous. Read
the following carefully.

Yesterday, we discovered a possibly severe bug in a utility function
(ft_selectdata_old) which was used by ft_freqstatistics. The bug
entails that ft_selectdata_old assumes that the channels in all data
input arguments are ordered identically, and does not take into
account the order of the data.label field. This means that when
several data input arguments with different channel orderings are
passed to ft_selectdata_old, the resulting output structure (with a
newly added 'rpt' dimension) will contain wrong data (i.e. data for
channel X might end up in another channel Y). Importantly, the same
thus holds for ft_freqstatistics: when doing statistics across
subjects, if the different subjects' data sets have different channel
orderings, the resulting statistics will be wrong.

We expect that in many cases, the channel ordering across different
data sets will be identical, and in those cases this bug will not have
had any effect. However, one important case in which channel ordering
*will* be different is when one does ft_channelrepair on a data set,
since this function appends the repaired channels to the end of the
data. So, if you have done ft_channelrepair on only a subset of your
subjects' data, and/or used ft_channelrepair to repair different
channels in different subjects, and subsequently passed the repaired
data sets to ft_freqstatistics, there is a good chance the results you
got were wrong.

Most likely, this bug was introduced with revision 4101, in september
2011, so it has been in the code for quite a while. Note that
ft_channelrepair only supports repairing missing channels since
revision 5216 (february 2012), and that this was advised against until
revision 6100 (june 2012), when the algorithm for doing so sensibly
was implemented.

The fix has been implemented and is now available from the FTP server
as of fieldtrip-20130319 (Donders users: the fix is automatically
available on the /home/common/ version of FieldTrip). Note that
ft_selectdata_old still does not work correctly, this is something we
will fix in the near future (ft_selectdata_old is deprecated). We
fixed the behaviour of ft_appendfreq (the preferred replacement
function for ft_selectdata_old when appending freq structures) and
changed ft_freqstatistics to use this function instead.

The other statistics functions, ft_timelockstatistics and
ft_sourcestatistics, were not affected by this bug. We strongly advise
you to upgrade to the latest version of FieldTrip. If the situation
described above applies to you, you will need to redo your
channel-level (time-)frequency statistics analyses.

Details on the bug (and a test script) can be found here:
http://bugzilla.fcdonders.nl/show_bug.cgi?id=2069 If you find any
problems related to the bug, please post them there.

We sincerely apologise for this bug and any trouble it might have caused.

Best,
On behalf of the FT core development team,

Eelke