mnefun is designed to streamline ILABS data processing by automating and standardizing data retrieval, remote machine processing (MaxFilter), preprocessing steps, and inverse computation.

A critical idea is that, once an experiment is complete, you or another ILABS person should be able to run your analysis script once, from scratch, for all subjects, and end up with all of the basic preprocessed files (evoked, epochs, inverse, etc.) you will need for your downstream scripts used for publication (stats, etc.).

To achieve mnefun’s reproducibility goal, it is important not to run your processing script by changing parameters for different subjects as you process each of them, or by doing steps manually. Where subject-specific values are needed, we can add functionality to allow subject-specific values in the script itself, such as proj_nums (see below).


The one step that might (somewhat routinely) need to be “worked around” is the data fetching step, which requires that the files on the acquisition machine be named properly, which might not always be the case, for example when:

  • files are named incorrectly (typos, inconsistently) during acquisition

  • runs are re-executed and saved with a different name (e.g., _redo_raw.fif).

But this should ideally be the exception and not the rule.

Experiment parameters can be specified using a params = Params(...) call in a script (old way), or by specifying a YAML script with the experiment parameters (new way) and using mnefun.read_params() to load the parameters. The processing pipeline steps and relationships are given below. All YAML parameters are described in their appropriate sections. Consider looking at mnefun/examples/funloc directory for a canonical example of how to process data using mnefun.

Flow chart

strict digraph "mnefun flow diagram" { graph [bb="0,0,558.5,834", bgcolor="#00000000", nodesep=0.2, ranksep=0.1 ]; node [fontname="sans-serif", fontsize=8, label="\N", margin="0.1,0.05", shape=box ]; edge [fontname="sans-serif", fontsize=8 ]; { graph [rank=same]; htm [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/</FONT><BR/><FONT POINT-SIZE="10">subj_fil*_report.html</FONT>>, pos="237.5,44", style=filled, width=1.5833]; legend [height=1.2222, label=<<TABLE BORDER="0" CELLBORDER="0" CELLSPACING="4" CELLPADDING="4"><TR><TD BGCOLOR="#CCBB44"> </TD><TD ALIGN="left">Remote: acquisiton machine</TD></TR><TR><TD BGCOLOR="#EE6677"> </TD><TD ALIGN="left">Local: obligatory user-created files</TD></TR><TR><TD BGCOLOR="#FFD8DF"> </TD><TD ALIGN="left">Local: optional user-created files</TD></TR><TR><TD BGCOLOR="#66CCEE"> </TD><TD ALIGN="left">Local: pipeline-created files</TD></TR></TABLE>>, margin=0, pos="399.5,44", shape=plaintext, width=2.5139]; } sco [fillcolor="#EE6677", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./</FONT><BR/><FONT POINT-SIZE="10">score.py</FONT>>, pos="53.5,700", style=filled, width=0.77778]; lst [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/lists/</FONT><BR/><FONT POINT-SIZE="10">ALL_*-eve.lst</FONT>>, pos="39.5,568", style=filled, width=1.0972]; sco -> lst [URL="../overview.html#do-score", fontsize=10, label=<<B>2. do_score</B>>, labeltooltip="2. do_score", lp="74,656", pos="e,37.631,586.01 44.113,681.87 43.048,679.29 42.123,676.62 41.5,674 35.334,648.05 35.562,617.47 36.89,596.03", target=_top]; evo [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/inverse/, ./SUBJ/epochs/</FONT><BR/><FONT POINT-SIZE="10">*-evo.fif, *-epo.fif</FONT>>, pos="126.5,186", style=filled, width=1.9306]; lst -> evo [fontsize=10, pos="e,73.885,204.09 39.5,549.99 39.5,536.02 39.5,515.73 39.5,498 39.5,498 39.5,498 39.5,248 39.5,231.04 50.725,218.39 65.11,209.15"]; evo -> htm [URL="../overview.html#gen-report", fontsize=10, label=<<B>11. gen_report</B>>, labeltooltip="11. gen_report", lp="192.5,123", pos="e,201.77,62.233 128.29,167.92 130.81,150.65 136.76,123.87 150.5,105 161.51,89.872 177.56,77.275 192.88,67.593", target=_top]; mri [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">structural/mri/</FONT><BR/><FONT POINT-SIZE="10">T1.mgz</FONT>>, pos="450.5,312", style=filled, width=1]; bem [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">structural/bem/</FONT><BR/><FONT POINT-SIZE="10">*-bem-sol.fif</FONT>>, pos="519.5,249", style=filled, width=1.0833]; mri -> bem [fontsize=10, label=Freesurfer, labeltooltip=Freesurfer, lp="515.5,280.5", pos="e,500.1,267.15 470.09,293.68 476.99,287.58 484.89,280.6 492.31,274.04"]; tra [fillcolor="#EE6677", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/trans/</FONT><BR/><FONT POINT-SIZE="10">*-trans.fif</FONT>>, pos="341.5,249", style=filled, width=0.91667]; mri -> tra [fontsize=10, label="mne coreg", labeltooltip="mne coreg", lp="409.5,280.5", pos="e,358.83,267.27 414.31,300.13 404.02,296.35 393.02,291.61 383.5,286 377.75,282.61 372.02,278.4 366.73,274.07"]; src [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">structural/bem/</FONT><BR/><FONT POINT-SIZE="10">*-src.fif</FONT>>, pos="427.5,249", style=filled, width=1.0833]; mri -> src [fontsize=10, pos="e,435.29,267.13 445.08,293.67 443.65,289.29 442.02,284.53 439.07,276.8"]; fwd [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/forward/</FONT><BR/><FONT POINT-SIZE="10">*-fwd.fif</FONT>>, pos="345.5,186", style=filled, width=1.0556]; bem -> fwd [fontsize=10, pos="e,383.71,198.84 480.42,232.85 463.06,226.25 442.33,218.54 423.5,212 413.83,208.64 403.43,205.19 393.47,201.97"]; tra -> fwd [URL="../overview.html#gen-fwd", fontsize=10, label=<<B>9. gen_fwd</B>>, labeltooltip="9. gen_fwd", lp="374.5,217.5", pos="e,344.38,204.15 342.64,230.68 342.97,225.62 343.34,219.95 343.7,214.42", target=_top]; src -> fwd [fontsize=10, pos="e,383.63,197.15 421.49,230.93 418.45,224.3 414.18,217.1 408.5,212 403.85,207.82 398.41,204.3 392.71,201.34"]; inv [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/inverse/</FONT><BR/><FONT POINT-SIZE="10">*-inv.fif</FONT>>, pos="296.5,123", style=filled, width=1.0417]; fwd -> inv [URL="../overview.html#gen-inv", fontsize=10, label=<<B>10. gen_inv</B>>, labeltooltip="10. gen_inv", lp="357,154.5", pos="e,310.28,141.15 331.59,167.68 327,161.97 321.79,155.49 316.83,149.3", target=_top]; inv -> htm [fontsize=10, pos="e,250.56,62.041 283.41,104.91 275.61,94.743 265.58,81.653 256.89,70.303"]; pbd [fillcolor="#EE6677", fontcolor="#000000", height=0.5, label="params.mf_prebad[SUBJ]", pos="197.5,700", style=filled, width=1.6111]; mfb [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/raw_fif/</FONT><BR/><FONT POINT-SIZE="10">*_raw_maxbad.txt</FONT>>, pos="123.5,612", style=filled, width=1.4583]; pbd -> mfb [URL="../overview.html#do-sss", fontsize=10, label=<<B>3. do_sss</B>>, labeltooltip="3. do_sss", lp="172.5,656", pos="e,126.37,630.06 155.51,681.87 152.22,679.54 149.15,676.92 146.5,674 137.84,664.48 132.34,651.38 128.9,639.76", target=_top]; mfp [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/raw_fif/</FONT><BR/><FONT POINT-SIZE="10">*_raw.pos</FONT>>, pos="174.5,524", style=filled, width=1]; pbd -> mfp [fontsize=10, pos="e,179.09,542.07 198.42,681.86 198.85,669.61 198.99,652.75 197.5,638 194.5,608.25 187.18,574.75 181.59,552.01"]; sss [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/sss_fif/</FONT><BR/><FONT POINT-SIZE="10">*_raw_sss.fif</FONT>>, pos="233.5,418", style=filled, width=1.0694]; pbd -> sss [fontsize=10, pos="e,240.66,436.15 214.71,681.9 229.17,665.65 247.5,639.77 247.5,613 247.5,613 247.5,613 247.5,470 247.5,461.96 245.86,453.44 243.7,\ 445.73"]; mfb -> mfp [fontsize=10, pos="e,164.37,542.08 133.82,593.6 141.13,581.28 151.05,564.55 159.26,550.7"]; mfb -> sss [fontsize=10, pos="e,194.72,418.98 116.29,593.73 104.41,562.25 85.013,494.94 116.5,453 132.24,432.04 160.16,423.4 184.78,420.07"]; mfp -> sss [fontsize=10, pos="e,227.45,436.05 190.28,505.69 194.55,500.53 198.97,494.73 202.5,489 210.9,475.39 218.25,459.11 223.69,445.68"]; aan [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/raw_fif/</FONT><BR/><FONT POINT-SIZE="10">*-annot.fif</FONT>>, pos="159.5,471", style=filled, width=1]; mfp -> aan [fontsize=10, pos="e,164.57,489.25 169.42,505.73 168.79,503.57 168.13,501.33 167.46,499.06"]; sss -> sss [URL="../overview.html#do-ch-fix", fontsize=10, label=<<B>4. do_ch_fix</B>>, labeltooltip="4. do_ch_fix", lp="319.5,418", pos="e,272.19,413.3 272.19,422.7 280.22,422.21 286,420.64 286,418 286,416.68 284.56,415.63 282.11,414.84", target=_top]; bad [fillcolor="#EE6677", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/bads/</FONT><BR/><FONT POINT-SIZE="10">*_post-sss.txt</FONT>>, pos="191.5,365", style=filled, width=1.1389]; sss -> bad [fontsize=10, pos="e,205.7,383.25 219.28,399.73 217.02,396.99 214.65,394.11 212.28,391.23"]; pca [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/sss_pca_fif/</FONT><BR/><FONT POINT-SIZE="10">*_fil55_raw_sss.fif</FONT>>, pos="238.5,249", style=filled, width=1.4306]; sss -> pca [fontsize=10, pos="e,290.34,263.76 272.17,416.08 296.88,413.23 327.24,405.04 343.5,383 368.61,348.95 308.5,275.89 307.5,275 304.9,272.68 302.07,270.58 \ 299.08,268.66"]; pro [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/sss_pca_fif/</FONT><BR/><FONT POINT-SIZE="10">*-proj.fif</FONT>>, pos="230.5,312", style=filled, width=1.2361]; sss -> pro [URL="../overview.html#gen-ssp", fontsize=10, label=<<B>5. gen_ssp</B>>, labeltooltip="5. gen_ssp", lp="113,365", pos="e,185.88,317.19 194.71,413.69 154.72,409.38 96.306,400.26 82.5,383 72.506,370.51 72.533,359.52 82.5,347 94.172,332.34 138.51,323.48 \ 175.64,318.5", target=_top]; pex [fillcolor="#FFD8DF", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/sss_pca_fif/</FONT><BR/><FONT POINT-SIZE="10">*-extra-proj.fif</FONT>>, pos="291.5,365", style=filled, width=1.2361]; sss -> pex [fontsize=10, pos="e,271.88,383.25 253.14,399.73 256.73,396.58 260.53,393.23 264.3,389.92"]; aan -> sss [fontsize=10, pos="e,208.72,436.08 184.55,452.73 189.67,449.21 195.13,445.44 200.48,441.76"]; bad -> pca [fontsize=10, pos="e,204.92,267.02 182.89,346.73 176.83,332.01 171.15,310.64 179.5,294 183.49,286.04 189.69,279.15 196.59,273.34"]; bad -> pro [fontsize=10, pos="e,217.31,330.25 204.7,346.73 206.8,343.99 209.01,341.11 211.21,338.23"]; pca -> evo [URL="../overview.html#write-epochs", fontsize=10, label=<<B>7. write_epochs</B>>, labeltooltip="7. write_epochs", lp="191,217.5", pos="e,132.55,204.04 186.93,241.56 172.75,237.87 158.1,232.08 146.5,223 143.02,220.27 140.05,216.76 137.55,213", target=_top]; pca -> fwd [fontsize=10, pos="e,329.6,204.35 290.02,231.55 295.74,229 301.35,226.15 306.5,223 311.97,219.66 317.34,215.47 322.27,211.15"]; cov [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/cov/</FONT><BR/><FONT POINT-SIZE="10">*-cov.fif</FONT>>, pos="239.5,186", style=filled, width=0.81944]; pca -> cov [URL="../overview.html#gen-covs", fontsize=10, label=<<B>8. gen_covs</B>>, labeltooltip="8. gen_covs", lp="272,217.5", pos="e,239.22,204.15 238.78,230.68 238.87,225.62 238.96,219.95 239.05,214.42", target=_top]; pro -> pca [URL="../overview.html#apply-ssp", fontsize=10, label=<<B>6. apply_ssp</B>>, labeltooltip="6. apply_ssp", lp="259.5,280.5", pos="e,226.58,267.21 223.89,293.66 222.87,289.37 222.25,284.72 223.75,277.31", target=_top]; pex -> pca [fontsize=10, pos="e,287.83,267.36 297.53,346.72 303.06,327.56 308.47,296.53 294.5,275 294.44,274.91 294.38,274.82 294.32,274.73"]; pex -> pro [fontsize=10, pos="e,251.13,330.25 270.85,346.73 267.07,343.58 263.07,340.23 259.11,336.92"]; cov -> htm [fontsize=10, pos="e,237.75,62.307 239.25,167.83 238.91,144.01 238.3,100.66 237.89,72.349"]; cov -> inv [fontsize=10, pos="e,280.48,141.15 255.68,167.68 261.26,161.71 267.63,154.9 273.64,148.46"]; acq [fillcolor="#CCBB44", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">user@minea</FONT><BR/><FONT POINT-SIZE="10">*_raw.fif</FONT>>, pos="197.5,816", style=filled, width=0.91667]; raw [fillcolor="#66CCEE", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/raw_fif/</FONT><BR/><FONT POINT-SIZE="10">*_raw.fif</FONT>>, pos="197.5,753", style=filled, width=1]; acq -> raw [URL="../overview.html#fetch-raw", fontsize=10, label=<<B>1. fetch_raw</B>>, labeltooltip="1. fetch_raw", lp="232.5,784.5", pos="e,197.5,771.15 197.5,797.68 197.5,792.62 197.5,786.95 197.5,781.42", target=_top]; raw -> sco [fontsize=10, pos="e,81.67,716.04 161.13,743.68 144.27,739.4 124.12,733.67 106.5,727 101.35,725.05 96.024,722.77 90.826,720.39"]; raw -> pbd [fontsize=10, pos="e,197.5,718.25 197.5,734.73 197.5,732.66 197.5,730.5 197.5,728.32"]; raw -> mfb [fontsize=10, pos="e,120.25,630.26 161.34,740.85 150.33,735.66 139.34,728.28 132.5,718 117.27,695.12 116.82,662.94 119.04,640.25"]; raw -> sss [fontsize=10, pos="e,258.84,436.13 233.75,743.65 254.92,736.39 277.5,723.4 277.5,701 277.5,701 277.5,701 277.5,470 277.5,460.12 272.71,451.21 266.29,\ 443.71"]; can [fillcolor="#FFD8DF", fontcolor="#000000", height=0.5, label=<<FONT POINT-SIZE="8">./SUBJ/raw_fif/</FONT><BR/><FONT POINT-SIZE="10">*-custom-annot.fif</FONT>>, pos="342.5,656", style=filled, width=1.4444]; raw -> can [fontsize=10, pos="e,333.5,674.29 233.88,747.52 251.51,744.03 272.31,737.86 288.5,727 305.07,715.88 318.74,698 328.18,683.1"]; can -> sss [fontsize=10, pos="e,272.09,425.17 336.71,637.76 331.44,620.56 324.5,593.25 324.5,569 324.5,569 324.5,569 324.5,470 324.5,447.76 303.55,435.12 281.76,\ 427.99"]; }

Running parameters

general: General options


Working directory, usually “.”.


Directory containing the structurals.


Which subjects to process.


Display status.


Anywhere a dict is supported as an option (e.g., mf_prebad or proj_nums), a special entry '__default__' can be used turn the dictionary into a defaultdict instance. This is useful in cases where a single set of values works for most subjects, but a few need different ones. For example in YAML form:

proj_nums: {
  __default__: [[2, 2, 0], [1, 1, 2], [0, 0, 0]],
  subj_08: [[2, 2, 0], [1, 1, 3], [0, 0, 0]],

1. fetch_raw

Fetch raw files from an acquisition machine.

fetch_raw: Raw fetching parameters

subjectslist of str

Subject names.

structuralslist of str

List of subject structurals.

dateslist of tuple or None

Dates to use for anonymization. Use “None” to more fully anonymize.


The acquisition machine SSH name.

acq_dirlist of str

List of paths to search and fetch raw data.


Acquisition port.

acq_excludelist of str

Regular expressions to exclude when trying to find the correct remote directory. This can be useful for example if a subject was run more than once, or someone has done some preprocessing or made copies on the acquisition machine, e.g.:

['genz_proc', 'genz_[0-9]+_[0-9]+a']

which means “exclude anything with ‘genz_proc’; or anything with a substring that has ‘genz_’, followed by at least one number, followed by ‘_’, followed by at least one number, followed by ‘a’” – the latter being useful when subjects should be named genz100_9a but have some duplicate directories named genz_100_9a.

run_nameslist of str

Run names for the paradigm.

runs_emptylist of str

Empty room run names.

subject_run_indiceslist of array-like | dict | None

Run indices to include for each subject. This can be a list (must be same length as params.subjects) or a dict (keys are subject strings, values are the run indices) where missing subjects get all runs. None is an alias for “all runs”.

2. do_score

Do the scoring. This converts TTL triggers to meaningful events.

scoring: Scoring parameters

scorecallable | None

Scoring function used to slice data into trials.


Called at each processing step.

3. do_sss


Before running SSS, set params.mf_prebad[SUBJ] to a list of bad MEG channels (str), or (old way) create SUBJ/raw_fif/SUBJ_prebad.txt with space-separated list of bad MEG channel numbers (int). Using p.mf_autobad=True can help fill in missed bad channels, but is not as reliable as experienced analyst inspection.

Run SSS processing. This will:

  1. Copy each raw file to the SSS workstation.

  2. Automatically determine bad channels (only if mf_autobad=True)

  3. Estimate head positions (remotely if hp_type='maxwell', otherwise locally), see preprocessing: head_position_estimation: Head position estimation parameters.

  4. Copy the head positions to the local machine.

  5. Delete generated files from the remote machine.

  6. Annotate bad segments automatically, see preprocessing: annotations: Annotation parameters.

  7. Add any custom annotations (e.g., for segments that operators want to manually mark as bad) that have been saved as FILENAME-custom-annot.fif.

  8. Run SSS processing locally using mne.preprocessing.maxwell_filter().

The addition of annotations before SSS ensures that tSSS operations are not disrupted by bad segments of data, and also ensures that the output files have the annotations (as they are preserved by mnefun).

preprocessing: multithreading: Multithreading parameters


Number of jobs to use in parallel operations.


Number of jobs to spawn in parallel for operations that can make use of MKL threading. If Numpy/Scipy has been compiled with MKL support, it is best to leave this at 1 or 2 since MKL will automatically spawn threads. Otherwise, n_cpu is a good choice.

n_jobs_firint | str

Number of threads to use for FIR filtering. Can also be ‘cuda’ if the system supports CUDA.

n_jobs_resampleint | str

Number of threads to use for resampling. Can also be ‘cuda’ if the system supports CUDA.

preprocessing: pre-SSS bads: Automatic bad channel detection


Dict with subject keys, with each value being a list of str of bad MEG channels (e.g., ['MEG0121', 'MEG1743']).


Default False. If True use Maxwell-filtering-based automatic bad channel detection to mark bad channels prior to SSS.


Default ‘maxwell’. If ‘maxwell’, use MaxFilter to do automatic detection, if ‘python’ (preferred) use MNE-Python.


MaxFilter threshold for noisy channel detection (default is 7).

preprocessing: head_position_estimation: Head position estimation parameters

coil_t_windowfloat | dict

Time window for coil position estimation.

coil_t_step_minfloat | dict

Coil step min for head / cHPI coil position estimation.

coil_dist_limitfloat | dict

Dist limit for coils.

coil_gof_limitfloat | dict

Goodness of fit limit for coils.

preprocessing: annotations: Annotation parameters

coil_bad_count_duration_limitfloat | dict

Remove segments with < 3 good coils for at least this many sec.

rotation_limitfloat | dict

Rotation limit (deg/s) for annotating bad segments.

translation_limitfloat | dict

Head translation limit (m/s) for annotating bad segments.

preprocessing: sss: SSS parameters

movecompstr | None

Movement compensation to use. Can be ‘inter’ or None.


Head position estimation method. Must be either ‘maxfilter’ or ‘python’.


Signal space separation method. Must be either ‘maxfilter’ or ‘python’.


Order of internal component of spherical expansion. Default is 8. Value of 6 recomended for infant data.


Order of external component of spherical expansion. Default is 3.


SSS regularization, usually “in”.

tsss_durfloat | None

Buffer length (in seconds) fpr Spatiotemporal SSS. Default is 60. however based on system specification a shorter buffer may be appropriate. For data containing excessive head movements e.g. young children a buffer size of 4s is recommended.


Correlation limit between inner and outer subspaces used to reject ovwrlapping intersecting inner/outer signals during spatiotemporal SSS. Default is .98 however a smaller value of .9 is recommended for infant/ child data.


Filter cHPI signals before SSS.

filter_chpi_t_windowstr | float | None

If None, use coil_t_window. Otherwise, options are the same as coil_t_window.

trans_tostr | array-like, (3,) | None

The destination location for the head. Can be:

  • ‘median’ (default)

    Median (across runs) of the starting head positions.

  • ‘twa’

    Time-weighted average head position.

  • None

    Will not change the head position.

  • str

    Path to a FIF file containing a MEG device to head transformation.

  • array-like

    First three elements are coordinates to translate to. An optional fourth element gives the x-axis rotation (e.g., -30 means a backward 30° rotation).

sss_originarray-like, shape (3,) | str

Origin of internal and external multipolar moment space in meters. Default is center of sphere fit to digitized head points.


If True, include EEG points in estimating the head origin.


Cross-talk file, usually “uw” to auto-load the UW file.


Calibration file, usually “uw” to auto-load the UW file.


Deprecated. SSS numerical format when using MaxFilter.


Deprecated. Extra arguments for MF SSS.


If True (default False), use eSSS to improve the external basis estimate using continuous empty-room projectors (proj_nums[2]). Only supported when Python is used for SSS.

4. do_ch_fix

Fix EEG channel ordering, and also anonymize files.

5. gen_ssp


Before running SSP, examine SSS’ed files and make SUBJ/bads/bad_ch_SUBJ_post-sss.txt; usually, this should only contain EEG channels. Alternatively, you can use params.auto_bad = some_float, see preprocessing: post-SSS bads: Marking bad channels during SSP.

Generate SSP vectors. If additional projectors are required (e.g., to get rid of muscle movement artifacts in a verbal response paradigm), you can use p.proj_extra, which get applied before any other projectors are computed (e.g., ECG, blink).

preprocessing: filtering: Filtering parameters

hp_cutfloat | None

Highpass cutoff in Hz. Use None for no highpassing.


High-pass transition band.


Cutoff for lowpass filtering.


Low-pass transition band.

filter_lengthint | str

See mne.filter.create_filter().


See mne.filter.create_filter().


See mne.filter.create_filter().


See mne.filter.create_filter().

preprocessing: post-SSS bads: Marking bad channels during SSP

auto_badfloat | None

If not None, bad channels will be automatically excluded after SSS if they disqualify a proportion of events exceeding auto_bad. This does not require the autoreject module.

auto_bad_rejectstr | dict | None

Default is None. Must be defined if using Autoreject module to compute noisy sensor rejection criteria. Set to ‘auto’ to compute criteria automatically, or dictionary of channel keys and amplitude values e.g., dict(grad=1500e-13, mag=5000e-15, eeg=150e-6) to define rejection threshold(s). See http://autoreject.github.io/ for details.

auto_bad_flatdict | None

Flat threshold for auto bad.

auto_bad_eeg_threshint | None

If more than this number of EEG channels is automatically marked bad, an error will be raised. This helps ensure that not too many channels are marked as bad.

auto_bad_meg_threshint | None

Same as above but for MEG.

preprocessing: ssp: SSP creation parameters

proj_numslist | dict

List of projector counts to use for ECG/blink/ERM/HEOG/VEOG; each list contains three values for grad/mag/eeg channels. Can be a dict that maps subject names to projector counts to use. The order of computation and application is empty-room, ECG, blink, HEOG, VEOG.

ECG, blink, and ERM are obligatory lists (though they can be lists of all zeros). Lists for HEOG and VEOG are optional. For example, if you want 1 blink, 2 HEOG, and 3 VEOG projectors (for a total of 6 EOG-related projectors) for each channel type, you would do:

 [1, 1, 1],
 [2, 2, 2],
 [3, 3, 3]]

If you want just blink and HEOG, you can use a list of 4 lists instead of 5 (or 3).

proj_sfreqfloat | None

The sample freq to use for calculating projectors. Useful since time points are not independent following low-pass. Also saves computation to downsample.


Can be “separate” (default for backward compat) or “combined” (should be better for SSS’ed data).


The percentage threshold to use when deciding whether or not to plot Epochs drop_log.


If True, plot the raw files with the ECG/EOG events overlaid.

ssp_eog_rejectdict | None

Amplitude rejection criteria for EOG SSP computation. None will use the mne-python default.

ssp_ecg_rejectdict | None

Amplitude rejection criteria for ECG SSP computation. None will use the mne-python default.

eog_channelstr | dict | None

The channel to use to detect blink events. None will use EOG* channels. In lieu of an EOG recording, MEG1411 may work.

heog_channelstr | dict | None

The channel to use to detect HEOG events. None will use EOG061. In lieu of an EOG recording, MEG1411 may work.

veog_channelstr | dict | None

The channel to use to detect HEOG events. None will use EOG062.

ecg_channelstr | dict | None

The channel to use to detect ECG events. None will use ECG063. In lieu of an ECG recording, MEG1531 may work. Can be a dict that maps subject names to channels.

eog_t_limstuple | dict

The time limits for EOG calculation. Default (-0.25, 0.25).

heog_t_limstuple | dict

The time limits for HEOG calculation. Default (-0.25, 0.25).

veog_t_limstuple | dict

The time limits for VEOG calculation. Default (-0.25, 0.25).

ecg_t_limstuple | dict

The time limits for ECG calculation. Default(-0.08, 0.08).

eog_f_limstuple | dict

Band-pass limits for EOG detection and calculation. Default (0, 2).

heog_f_limstuple | dict

Band-pass limits for HEOG detection and calculation. Default (0, 2).

veog_f_limstuple | dict

Band-pass limits for VEOG detection and calculation. Default (0, 2).

ecg_f_limstuple | dict

Band-pass limits for ECG detection and calculation. Default (5, 35).

eog_threshfloat | dict | None

Threshold for EOG detection. Can vary per subject.

heog_threshfloat | dict | None

Threshold for HEOG detection. Can vary per subject.

veog_threshfloat | dict | None

Threshold for VEOG detection. Can vary per subject.


If True, average artifact epochs before computing proj.

proj_extrastr | None

Extra projector filename to load for each subject, e.g. extra-proj.fif will load SUBJ/sss_pca_fif/extra-proj.fif.

get_projs_fromlist of int | dict

Indices for runs to get projects from.


Highpass to use for continuous ERM projectors (default None).

cont_hp_transfloat | None

Highpass transition bandwidth to use for continuous ERM projectors (default 0.5).


Lowpass to use for continuous ERM projectors (default 5).

cont_lp_transfloat | None

Lowpass transition bandwidth for continuous ERM projectors (default None).

cont_rejectdict | None

Rejection parameters for continuous empty-room projection calculations. None (default) will use params.reject. This likely needs to be set when cont_as_esss=True.


If True, plot drop logs after preprocessing.

6. apply_ssp

Apply SSP vectors and filtering to the files.

7. write_epochs

Write epochs to disk.

epoching: Epoching parameters


tmin for events.


tmax for events.


Adjustment for delays (e.g., -4e-3 compensates for a 4 ms delay in the trigger.

baselinetuple | None | str

Baseline to use. If “individual”, use params.bmin and params.bmax, otherwise pass as the baseline parameter to mne-python Epochs. params.bmin and params.bmax will always be used for covariance calculation. This is useful e.g. when using a high-pass filter and no baselining is desired (but evoked covariances should still be calculated from the baseline period).


Lower limit for baseline compensation.


Upper limit for baseline compensation.

decimint | float | list

Amount to decimate the data after filtering when epoching data (e.g., a factor of 5 on 1000 Hz data yields 200 Hz data). If a float is used, it should be the destination sample rate (e.g., a value of 200. with 1000 Hz data will use decim=5).

epochs_typestr | list

Can be ‘fif’, ‘mat’, or a list containing both.

match_funcallable | None

If None, standard matching will be performed. If a function, must_match will be ignored, and match_fun will be called to equalize event counts.


Rejection parameters for epochs.


Flat thresholds for epoch rejection.

reject_tminfloat | None

Reject minimum time to use when epoching. None will use tmin.

reject_tmaxfloat | None

Reject maximum time to use when epoching. None will use tmax.


Can set to ‘error’ | ‘warning’ | ‘ignore’. Default is ‘error’. Determine what to do if one or several event ids are not found in the recording during epoching. See mne.Epochs docstring for further details.

autoreject_thresholdsbool | False

If True use autoreject module to compute global rejection thresholds for epoching. Make sure autoreject module is installed. See http://autoreject.github.io/ for instructions.


Default is (‘mag’, ‘grad’, ‘eeg’). Can set to (‘mag’, ‘grad’, ‘eeg’, ‘eog) to use EOG channel rejection criterion from autoreject module to reject trials on basis of EOG.

reject_epochs_by_annotbool | str

If True, reject epochs by BAD annotations. If str, will reject epochs by annotations that match the given regular expression str.

pick_events_autorejectcallable | string | None

Function for picking autoreject events, or the string “restrict” to limit events to those with an id in in_numbers.

analyseslist of str

Lists of analyses of interest.

in_nameslist of str

Names of input events.

in_numberslist of list of int

Event numbers (in scored event files) associated with each name.

out_nameslist of list of str

Event types to make out of old ones.

out_numberslist of list of int

Event numbers to convert to (e.g., [[1, 1, 2, 3, 3], …] would create three event types, where the first two and last two event types from the original list get collapsed over).

must_matchlist of int

Indices from the original in_names that must match in event counts before collapsing. Should eventually be expanded to allow for ratio-based collapsing.


If True, in addition to standard averages / evoked data, averages will be computed from every other trial, i.e., from even and odd trials separately. This can help assess the SNR of the data.

epochs_projbool | ‘delayed’

The proj argument in mne.Epochs. Should be 'delayed' if you want the option of plotting sensor-space data with no projectors.


If True (default False), allow resampling raw instances (and events) to that of the first raw insntance in the case that raws do not all have a matching sample rate. This is useful when recordings were errantly performed at different sample rates.

8. gen_covs

Generate covariances.

covariance: Covariance parameters


Covariance calculation method.


Default is False. Set to True to compute rank of the noise covariance matrix during inverse kernel computation.

pick_events_covcallable | string | None

Function for picking covariance events, or the string “restrict” to limit events to those with an id in in_numbers.

cov_rankstr | int

Cov rank to use, usually “auto”.


Can be “estimate_rank” to use mne.rank.estimate_rank, or “compute_rank” to use mne.compute_rank(). The latter seems to work better for custom tol values by not row-normalizing data.

cov_rank_tolfloat | str

Tolerance for covariance rank computation. Can also be “auto” or “float32”, though these tend not to be very robust.


If True, force the ERM cov to be full rank. Usually not needed, but might help when the empty-room data is short and/or there are a lot of head movements.

9. gen_fwd


Make SUBJ/trans/SUBJ-trans.fif using mne coreg.

Generate forward solutions (and source space if necessary).

forward: Forward parameters


Defaults to '5120-5120-5120', use '5120' for a single-layer BEM.

srcstr | dict

Can start be:

  • ‘oct6’ to use a surface source space decimated using the 6th (or another integer) subdivision of an octahedron, or

  • ‘vol5’ to use a volumetric grid source space with 5mm (or another integer) spacing


Default is 7 mm. Defines source grid spacing for volumetric source space.


Minimum distance (mm) for sources in the brain from the skull in order for them to be included in the forward solution source space.

10. gen_inv

Generate inverses.

inverse: Inverse parameters

inv_nameslist of str

Inverse names to use.

inv_runslist of int

Runs to use for each inverse.

11. gen_report

Write mne.Report HTML of results to disk.

report_params: Report parameters


Function to run before adding any Report sections. Must have the signature:

def pre_fun(report, p, subject, **kwargs):

The **kwargs is necessary for future compatibility.


cHPI SNR (default True).


Number of good HPI coils (default True).


Head movement (default True).


10 evenly spaced raw data segments (default True).


Raw PSDs, often slow (default True).


SSP topomaps (default True).


Source alignment (default True).


Plot the epochs drop log (default True).


Covariance image and SVD plots.


Plot the BEM.


SNR plots, with keys ‘analysis’, ‘name’, and ‘inv’.


Whitening plots, with keys ‘analysis’, ‘name’, and ‘cov’.


Sensor topomaps, with keys ‘analysis’, ‘name’, ‘times’, and ‘proj’. ‘proj’ can be True (default), False, or ‘reconstruct’. False and ‘reconstruct’ require epochs_proj='delayed'.


Source plots, with keys ‘analysis’, ‘name’, ‘inv’, ‘times’, ‘views’, and ‘size’.


Function to run after adding all other Report sections. Must have the same signature as pre_fun above.


If True (default False), load all raw data into memory before generating plots. Can help speed up computations like PSD estimates, but can also consume a large amount of memory.

Filename standardization

mnefun imposes custom standardized structure on filenames:

naming: File naming tags and folders


Directory for event lists, usually “lists”.


Directory to use for bad channels, usually “bads”.


Tag for bid channel filename, usually “_post-sss.txt”.


Raw directory, usually “raw_fif”.


Keep original files after anonymization.


File tag for raw data, usually “_raw.fif”.


File tag for SSS-processed files, usually “_raw_sss.fif”.


Directory to use for SSS processed files, usually “sss_fif”.


Directory for processed files, usually “sss_pca_fif”.


Directory for epochs, usually “epochs”.


The prefix to use for the -epo.fif file.


Tag for epoochs, usually ‘-epo’.


Tag for equalized data, usually “eq”.


Directory to use for covariances, usually “covariance”.


Directory for forward solutions, usually “forward”.


Directory to use for trans files, usually “trans”.


Directory for storing inverses, usually “inverse”.


Tag for all inverses, usually “-sss”.


Tag for ERM inverse, usually “-erm”.


Tag for fixed inverse, usually “-fixed”.


Tag for loose inverse, usually “”.


Tag for free orientation inverse, usually “-free”.

Preparing your machine for MaxFilter use


Head position estimation and bad channel detection are now available using hp_type='python' and mf_autobad_type='python, respectively. These are the preferred processing methods going forward (as of March 2020), and using MaxFilter should be considered deprecated.

Parameters for remotely connecting to SSS workstation (‘sws’) can be set by adding a file ~/.mnefun/mnefun.json with contents like:

$ mkdir ~/.mnefun
$ echo '{"sws_ssh":"kasga", "sws_dir":"/data06/larsoner/sss_work", "sws_port":22}' > ~/.mnefun/mnefun.json

This should be preferred to the old way, which was to set in each script when running on your machine:

params.sws_ssh = 'kasga'
params.sws_dir = '/data06/larsoner/sss_work'

Using per-machine config files rather than per-script variables should help increase portability of scripts without hurting reproducibility (assuming we all use the same version of MaxFilter, which should be a safe assumption).

To test that things are configured correctly, you can do:

$ python -c "import mnefun; mnefun.check_sws()"
On kasga: maxfilter -version (0 sec)
Revision: 2.2.15 Neuromag maxfilter Dec 11 2012 14:48:44

If you get an error:

  1. Ensure that your file is correctly set up in ~/.mnefun/mnefun.json. It needs to use standard quotation marks like ", not fancy ones like so ensure that your text editor (if you used one) did not use fancy quotation marks.

  2. Ensure that maxwell_filter is accessible as a command on the remote machine. Log into the remote machine and do:

    $ which maxfilter

    If you get no output with this command, it means that MaxFilter is not available on your PATH on the remote machine. To fix this, consider adding the following line to the end of your ~/.bashrc on the remote machine:

    export PATH=${PATH}:/neuro/bin/util:/neuro/bin/X11