Skip to main content

mne_process_raw

Overview​

mne_process_raw is the batch-mode raw data processing tool for MEG/EEG data. It provides a complete offline processing pipeline including filtering, decimation, event detection, epoch-based averaging, noise-covariance matrix estimation, and Signal-Space Projection (SSP) operator creation — all driven from the command line without a GUI.

This is a C++ port of the original MNE-C mne_process_raw by Matti Hämäläinen. In the original MNE-C distribution, mne_browse_raw (interactive GUI) and mne_process_raw (batch mode) were two names for the same binary; when invoked as mne_process_raw, no user interface appeared and all operations were controlled through command-line options and description files.

Usage​

mne_process_raw [options]

At minimum, one --raw file must be specified. All other options are optional and can be combined freely.

Options​

General​

OptionDescription
--helpPrint grouped help and exit
--versionPrint version information and exit
--cd <dir>Change working directory before processing

Input​

OptionDescription
--raw <file>Raw data file to process (required, repeatable). When multiple files are given, grand averaging and grand covariance are computed across all files.
--grad <number>Desired software gradient compensation order (for CTF / 4D data)
--allowmaxshieldAllow loading of unprocessed Elekta MaxShield data

Events​

OptionDescription
--events <file>Load event list from file (FIFF or text format)
--eventsout <file>Save detected events to file
--alleventsDetect all trigger transitions, not just rising edges
--digtrig <name>Digital trigger channel name (default: STI 014). Use underscores for spaces, e.g. STI_014.
--digtrigmask <value>Bit mask applied to the trigger channel (decimal or 0x hex)

Projection (SSP)​

OptionDescription
--proj <file>Load SSP vectors from file (repeatable)
--projonActivate SSP projections when processing
--projoffDeactivate SSP projections
--makeprojCompute new SSP operators from the data
--projevent <code>Event code selecting the epochs for SSP computation
--projtmin <sec>Start time of the window for SSP computation
--projtmax <sec>End time of the window for SSP computation
--projngrad <n>Number of gradiometer SSP components (default: 2)
--projnmag <n>Number of magnetometer SSP components (default: 2)
--projneeg <n>Number of EEG SSP components (default: 0)
--projgradrej <fT/cm>Gradiometer rejection threshold for SSP (default: 2000)
--projmagrej <fT>Magnetometer rejection threshold for SSP (default: 3000)
--projeegrej <µV>EEG rejection threshold for SSP (default: 0)
--saveprojtag <tag>Tag appended to SSP output filenames

Filtering​

OptionDescription
--filtersize <n>FFT length for the FIR filter (default: 8192)
--highpass <Hz>High-pass corner frequency
--lowpass <Hz>Low-pass corner frequency
--highpassw <Hz>High-pass transition bandwidth
--lowpassw <Hz>Low-pass transition bandwidth
--filteroffDo not filter the data

Output / Decimation​

OptionDescription
--save <file>Save processed (filtered, projected) raw data to file
--decim <factor>Decimation (down-sampling) factor (default: 1)
--split <MB>Split output files at this size in megabytes
--anonOmit subject information from the output file
--savehereWrite output to the current directory instead of the raw file's directory

Averaging​

OptionDescription
--ave <file>Off-line averaging description file (repeatable)
--saveavetag <tag>Tag appended to average output filenames
--gave <file>Grand average output file (used with multiple --raw files)

Covariance​

OptionDescription
--cov <file>Covariance matrix description file (repeatable)
--savecovtag <tag>Tag appended to covariance output filenames
--gcov <file>Grand covariance output file (used with multiple --raw files)

Description​

mne_process_raw orchestrates a complete batch processing pipeline for raw MEG/EEG data. Operations are executed in a natural order: the raw file is opened, events are attached or detected, projections are loaded, and then the requested processing steps (filtering, saving, averaging, covariance estimation, SSP computation) are carried out.

Processing Pipeline​

The processing pipeline proceeds in the following order for each input file:

  1. Open raw data — Load the FIFF raw data file and apply gradient compensation if requested.
  2. Attach events — Load events from an external file or detect them automatically from the digital trigger channel.
  3. Load projections — Read SSP vectors from external projection files and optionally activate them.
  4. Filter and save — If --save is specified, apply the filter and decimation settings and write the processed raw data to a new file.
  5. Compute averages — If --ave is specified, parse the averaging description file(s) and compute epoch-based averages with artifact rejection.
  6. Compute covariance — If --cov is specified, parse the covariance description file(s) and estimate noise-covariance matrices from the specified baseline epochs.
  7. Compute SSP — If --makeproj is specified, create new signal-space projection operators from the data.

When multiple --raw files are given, the pipeline processes each file independently and then computes grand averages (--gave) and/or grand covariance matrices (--gcov) across all files.

Event Detection​

Events are detected from the digital trigger channel (default: STI 014). The trigger channel is scanned for transitions from zero to a nonzero value (rising edges). The event code is taken from the trigger channel value at the transition point.

  • Use --digtrigmask to mask out specific bits (e.g., 0xFF to consider only the low 8 bits).
  • Use --allevents to detect all transitions (not just rising edges), which is useful when trigger lines carry multiple overlapping codes.
tip

Since the sampling clock and stimulation devices are usually not synchronized, trigger bits may not all transition at the same sample. The event detector automatically handles this by checking subsequent samples for additional transitions.

Description Files for Averaging​

The averaging description file (.ave) specifies one or more stimulus categories, each with its own event code, time window, baseline correction, and artifact rejection criteria. The format follows the MNE-C convention:

average {
    name        "Auditory Left"
    event       1
    tmin        -0.2
    tmax        0.5
    basemin     -0.2
    basemax     0.0
    gradReject  3000e-13
    magReject   4000e-15
    eegReject   150e-6
    eogReject   150e-6
}

Key fields:

  • event — The trigger event code to epoch on.
  • tmin / tmax — Epoch boundaries relative to the event (seconds).
  • basemin / basemax — Baseline correction interval (seconds).
  • gradReject / magReject / eegReject / eogReject — Peak-to-peak artifact rejection thresholds.

For detailed format documentation, see the MNE-C manual.

Description Files for Covariance Estimation​

The covariance description file (.cov) specifies the time window and event-based epochs from which the noise-covariance matrix is estimated:

cov {
    name        "Noise Covariance"
    event       1
    tmin        -0.2
    tmax        0.0
    basemin     -0.2
    basemax     0.0
    gradReject  3000e-13
    magReject   4000e-15
    eegReject   150e-6
}

The noise-covariance matrix is a critical input for inverse modeling. For background on how it is used, see The Minimum-Norm Estimates.

Signal-Space Projection (SSP)​

The --makeproj option computes new SSP operators from the raw data. This is typically done using empty-room data (recorded without a subject) to characterize environmental noise patterns.

The SSP algorithm:

  1. Selects epochs around the specified event code (--projevent)
  2. Computes the covariance matrix of these epochs
  3. Extracts the leading eigenvectors as the noise subspace basis
  4. Saves the resulting projection operator

Separate components are computed for gradiometers (--projngrad), magnetometers (--projnmag), and EEG channels (--projneeg). Rejection thresholds (--projgradrej, --projmagrej, --projeegrej) exclude noisy epochs from the computation.

For the mathematical background on SSP, see Signal-Space Projection.

Filtering and Decimation​

mne_process_raw applies an FFT-based FIR filter to the data before saving. The filter is specified by high-pass and low-pass corner frequencies and their transition bandwidths.

important

When decimating, the output sampling frequency must be at least three times the low-pass filter corner frequency to satisfy the Nyquist criterion and avoid aliasing.

Grand Averaging​

When multiple raw data files are specified with --raw, the tool can compute grand averages and grand covariance matrices across all files. This is useful for group-level analyses:

  • --gave <file> — After computing per-file averages (driven by --ave), combine them into a single grand-average evoked file.
  • --gcov <file> — After computing per-file covariance matrices (driven by --cov), combine them into a single grand covariance matrix.

Examples​

Detect events and save them​

mne_process_raw --raw sample_audvis_raw.fif \
    --eventsout sample_audvis_raw-eve.fif

Band-pass filter and decimate​

mne_process_raw --raw sample_audvis_raw.fif \
    --highpass 1 --lowpass 40 \
    --decim 4 \
    --save sample_audvis_filtered_raw.fif

Compute averages from a description file​

mne_process_raw --raw sample_audvis_raw.fif \
    --ave auditory.ave

Compute noise covariance from pre-stimulus baselines​

mne_process_raw --raw sample_audvis_raw.fif \
    --cov noise.cov

Full pipeline with SSP, filtering, and averaging​

mne_process_raw --raw sample_audvis_raw.fif \
    --proj ssp_audvis.fif --projon \
    --highpass 0.1 --lowpass 40 \
    --ave auditory.ave \
    --cov noise.cov

Grand average across multiple subjects​

mne_process_raw \
    --raw subj01_audvis_raw.fif \
    --raw subj02_audvis_raw.fif \
    --raw subj03_audvis_raw.fif \
    --ave paradigm.ave \
    --gave grand_average-ave.fif

Create SSP operators from empty-room data​

mne_process_raw --raw empty_room.fif \
    --makeproj \
    --projngrad 3 --projnmag 3 \
    --saveprojtag _emptyroom

Save filtered data with anonymization​

mne_process_raw --raw patient_data.fif \
    --highpass 1 --lowpass 100 \
    --save filtered_anon.fif --anon

See Also​