osl_dynamics.meeg.maxfilter#

Maxfiltering.

This module wraps the Elekta Maxfilter command-line tool for applying Signal Space Separation (SSS) and temporal SSS (tSSS) to MEG data.

Note

This module requires a licensed installation of Elekta/MEGIN MaxFilter. MaxFilter is proprietary software and is not included with osl-dynamics.

OHBA users: The scanner argument sets the correct calibration files for OHBA scanners ("VectorView", "VectorView2" or "Neo"). To check which scanner was used to record a FIF file, run the following on an OHBA machine with a MaxFilter license:

from subprocess import run, PIPE

cmd = f"/neuro/bin/util/show_fiff -v -t 100:206 {path_to_fif}"
result = run(cmd.split(), stdout=PIPE, stderr=PIPE)
for line in result.stdout.decode().splitlines():
    print(line)

The output will show the recording date and scanner description.

Examples

Standard multistage Maxfiltering with the newest OHBA scanner:

run_maxfilter(
    files="sub-*_task-rest_meg.fif",
    outdir="derivatives/maxfiltered",
    scanner="Neo",
    mode="multistage",
    tsss=True,
    headpos=True,
    movecomp=True,
)

Cambridge CBU 3-stage pipeline with a single file:

run_maxfilter(
    files="sub-01_task-rest_meg.fif",
    outdir="derivatives/maxfiltered",
    mode="cbu",
)

Functions#

run_maxfilter(files, outdir[, maxpath, mode, scanner, ...])

Run Maxfilter on one or more FIF files.

Module Contents#

osl_dynamics.meeg.maxfilter.run_maxfilter(files, outdir, maxpath='/neuro/bin/util/maxfilter-2.2', mode='standard', scanner=None, tsss=False, st=10, corr=0.98, headpos=False, movecomp=False, movecompinter=False, nomovecompinter=False, autobad=False, autobad_dur=None, bads=None, badlimit=None, trans=None, origin=None, frame=None, force=False, inorder=None, outorder=None, hpie=None, hpig=None, ctc=None, cal=None, linefreq=None, hpisubt=None, skip=None, size_limit_gb=1.9, autobad_scan_dur=600.0, overwrite=False, dryrun=False)[source]#

Run Maxfilter on one or more FIF files.

Parameters:

  • files (str or list of str) – Path to a FIF file, a glob pattern, or a list of file paths.

  • outdir (str) – Output directory.

  • maxpath (str, optional) – Path to the maxfilter binary.

  • mode (str, optional) – Running mode: "standard", "multistage" or "cbu".

  • scanner (str, optional) – OHBA scanner name ("VectorView", "VectorView2" or "Neo"). Sets CTC and Cal files automatically. Overrides ctc and cal.

  • tsss (bool, optional) – Apply temporal extension of maxfilter (tSSS).

  • st (float, optional) – Data buffer length for tSSS processing (default 10).

  • corr (float, optional) – Subspace correlation limit for tSSS (default 0.98).

  • headpos (bool, optional) – Output additional head movement parameter file.

  • movecomp (bool, optional) – Apply movement compensation.

  • movecompinter (bool, optional) – Apply movement compensation on data with intermittent HPI.

  • nomovecompinter (bool, optional) – Remove default movecomp in the CBU 3-stage pipeline.

  • autobad (bool, optional) – Apply automatic bad channel detection.

  • autobad_dur (int, optional) – Set autobad with a specific duration.

  • bads (str, optional) – Static bad channels as a space-separated string of channel numbers, e.g. "2233 2312".

  • badlimit (int, optional) – Upper limit for number of bad channels to be removed.

  • trans (str, optional) – Transform data to the head position in the specified file, or "default" for the default head position.

  • origin (list of float, optional) – Custom sphere origin [x, y, z].

  • frame (str, optional) – Coordinate frame for the origin.

  • force (bool, optional) – Ignore program warnings.

  • inorder (int, optional) – Order of the inside expansion.

  • outorder (int, optional) – Order of the outside expansion.

  • hpie (int, optional) – Error limit for HPI coil fitting (mm).

  • hpig (float, optional) – Goodness-of-fit limit for HPI coil fitting.

  • ctc (str, optional) – Path to cross-talk calibration file.

  • cal (str, optional) – Path to fine-calibration file.

  • linefreq (int, optional) – Line interference frequency (50 or 60 Hz).

  • hpisubt (str, optional) – HPI signal subtraction mode.

  • skip (str, optional) – Time intervals (in seconds) to skip from processing, given as a space-separated list of start/stop pairs, e.g. "0 30 120 150". Maps to MaxFilter’s -skip flag.

  • size_limit_gb (float, optional) – Threshold above which oversized recordings are automatically chunked using -skip (default 1.9 GB, leaving 5% headroom under the 2 GB single-FIF float32 limit). Each input file’s estimated float32 maxfiltered output is checked; if it exceeds this limit, the recording is processed in time chunks and the chunked outputs are concatenated and saved as a BIDS split chain so mne.io.read_raw_fif() reads the result as a single Raw. Static bad channels are detected once on a short window (see autobad_scan_dur) and shared across chunks. Movement compensation across chunks requires an explicit trans reference; passing movecomp=True without trans will raise.

  • autobad_scan_dur (float, optional) – Duration in seconds of the autobad scan window used for chunked sessions (default 600 s = 10 min). Long enough for reliable bad-channel detection, short enough that the autobad FIF output stays well under the 2 GB limit at typical channel counts.

  • overwrite (bool, optional) – Overwrite existing output files.

  • dryrun (bool, optional) – Print commands without executing.

Return type:

None

Notes

The recommended use at OHBA is multistage maxfiltering:

from osl_dynamics.meeg.maxfilter import run_maxfilter

run_maxfilter(
    files="sub-01_task-rest_meg.fif",
    outdir="derivatives/maxfiltered",
    scanner="Neo",
    mode="multistage",
    tsss=True,
    headpos=True,
    movecomp=True,
)

Output files follow the BIDS-MEG proc- entity convention:

sub-01_task-rest_proc-sss_meg.fif          # SSS
sub-01_task-rest_proc-tsss_meg.fif         # tSSS
sub-01_task-rest_proc-tsss+trans_meg.fif   # tSSS + trans