Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Though seemingly affected only by its immediate surrounding, the sphere of external influence extends to infinite distance. Nikola Tesla

Table of Contents

Prerequisite

...

This tutorial teaches how to use the Maxfilter command line tool to remove artifacts on MEG signals coming from outside of the sphere of all MEG channels. This tool was build by Elekta, the vendor of our MEG.

It is also at this step that bad channels are marked and discarded (interpolated).

Step-by-step guide

  1. Choose a reference head position 
  2. Run Maxfilter on the raw data
  3. Check correction with Muse
  4. Iterate to fine tune correction parameters

...

Code Block
maxfilter_cenir -f run01.fif -st 20000 -corr 0.98 -bad 0221 0332 -trans meanmeanhp.fif -o run01_tsss.fif

Brief description of the options (the user is referred to the pdf manual for more information):

  • -f: the input file
  • -o: the output file
  • -tsss: perform temporal source space separation (the standard at CENIR). The option is followed by a buffer length (in seconds), which should always be larger than your individual recordings.
  • -corr: amount of correlation between data and noise that should be rejected (see manual for more explanation). Lowering the value below the default 0.98 may sometimes help getting rid of artifacts but can also lead to removing interesting signal from the data. Careful inspection is recommended (see below).
  • -bad: which channels should be considered bad, i.e. removed prior to correction and later reinterpolated. The -autobad command is not recommended because it leaves no trace of which channels are considered bad. Rather use xscan (see below).
  • -trans: transforms the MEG data into the sensor array defined by the channel info in a specified file (here mean.fif).

 


Warning
titleuse maxfilter_cenir

Be sure to use the maxfilter_cenir command and NOT maxfilter. This will ensure that correct tuning parameters found in the sss_config directory next to your data are applied during the computation. The full script below spells out the full command for each file it runs on.


Info
titleIn case of large artifacts, be sure to check this

On rare occasions, we experienced some trouble with tsss processing: when large dc-offset is present in the signal at the beginning of the file a bug can occur, leaving the resulting file with strong artifacts at the beginning of the file and a lot of noise above 80Hz on a number of channels.

If you encounter this kind of behavior, the solution is simple, before running tsss you need to remove the large dc-offset with dataHandler:
dataHandler -rbr 1 1000 -new run02_dc_offset run02.fiff
and then your maxfilter command: (for instance)
maxfilter_cenir -gui -st 20000 -trans meanhp.fif -f run02_dc_offset.fif

This problem is quite rare. A possible cause is large low frequency artifacts happening during recording (for those working with patients having big metallic part, be careful!).

...

Code Block
languagebash
titlemaxfilter.script (click on the right to open) --->
collapsetrue
#!/bin/bash

function display_usage() {
cat <<EOF

Usage:     $0 file1.fif file2.fif file3.fif ...
           $0 file1.fif file2.fif file3.fif ... -trans fileX.fif

This script takes any number of .fif files as input and generates up to three outputs per file.
For file1.fif:
    1/ a maxfiltered version file1_tsss.fif (using maxfilter -st)
    2/ a list of bad channels file1.bad (using xscan). If a file file1.bad already exists,
this step is skipped and the content of file1.bad will be used for step 3 below.
    3/ a maxfiltered version excluding these bad channels file1_tsss_nobad.fif (using maxfilter -bad )

If the -trans fileX.fif option is passed (often recommended), the head position in each file will be
set to that in fileX.fif

NOTE: this script will never overwrite any file. Remove previous versions of files if needed.

EOF
}

# first display usage if needed and parse trans arguments
if [ -z "$1" ]
then
    display_usage
    exit 1
else
    POSITIONAL=()
    while [[ $# -gt 0 ]]
    do
    key="$1"

    case $key in
        -trans)
        TRANS="$2"
        shift # past argument
        shift # past value
        ;;
        *)    # unknown option
        POSITIONAL+=("$1") # save it in an array for later
        shift # past argument
        ;;
    esac
    done
    set -- "${POSITIONAL[@]}" # restore positional parameters
    toprocess=$@
fi

# for each input file

for f in $toprocess
do
    dn=$(dirname "${f}")

    # make sure we use sss_config if next to the data
    if [ -d "${dn}/sss_config/" ]
    then
        xscan_cenir="xscan -ctc ${dn}/sss_config/ct_sparse.fif -cal ${dn}/sss_config/sss_cal.dat -st 20000 -corr 0.98 "
        maxfilter_cenir="maxfilter -ctc ${dn}/sss_config/ct_sparse.fif -cal ${dn}/sss_config/sss_cal.dat -st 20000 -corr 0.98 -trans $TRANS "
    else
        printf "Warning !\n No 'sss_config' directory next to the data in ${dn}\n\n maxfilter results may be inaccurate...\n\n"
        xscan_cenir="xscan -st 20000 -corr 0.98 "
        maxfilter_cenir="maxfilter -st 20000 -corr 0.98 -trans $TRANS "
    fi        
    
    # start 
    echo "processing $f"
    nf=`echo $f | sed -e 's/.fif$//g'`
    # if output _tsss file does not exist
    if [ ! -f ${nf}_tsss.fif ]
    then
        # run maxfilter -st
        echo "$maxfilter_cenir -f $f -o ${nf}_tsss.fif"
        $maxfilter_cenir -f $f -o ${nf}_tsss.fif
    else
        # if file exists, then skip
        echo "${nf}_tsss.fif exists. Skipping."
    fi
    
    # if a list of bad channels does not exist
    if [ ! -f ${nf}.bad ]
    then
        # create a list of bad channels        
        echo "detecting bad channels in $f"
        echo "$xscan_cenir -f $f"
        BAD_CHANNELS=`$xscan_cenir -f $f`
        echo $BAD_CHANNELS > ${nf}.bad
    else
        # else use existing list
        echo "${nf}.bad exists. Skipping automatic detection."
        BAD_CHANNELS=`cat ${nf}.bad`
    fi
    
    # if there is no bad channel
    if [[ -z "$BAD_CHANNELS" ]]
    then
        echo "No bad channels for $f"
    else
        # else create a _nobad.fif file where bad channels are excluded (interpolated)
        if [ ! -f ${nf}_tsss_nobad.fif ]
        then
            echo "Maxfilter ignoring bad channels..."
            echo "$maxfilter_cenir -f $f -o ${nf}_tsss_nobad.fif -bad $BAD_CHANNELS"
            $maxfilter_cenir -f $f -o ${nf}_tsss_nobad.fif -bad $BAD_CHANNELS
        else
            echo "${nf}_tsss_nobad.fif exists. Skipping."
        fi
    fi

done

If we call the script above "maxfilter.script", we run it as follows:

...

After Maxfilter has finished, it is important to check signal quality visually. We use Muse to do this.

Code Block
muse run01_tsss.fif

...