mne.epochs.average_movements(epochs, head_pos=None, orig_sfreq=None, picks=None, origin='auto', weight_all=True, int_order=8, ext_order=3, destination=None, ignore_ref=False, return_mapping=False, mag_scale=100.0, verbose=None)[source]

Average data using Maxwell filtering, transforming using head positions.

epochsinstance of Epochs

The epochs to operate on.

head_posarray | tuple | None

The array should be of shape (N, 10), holding the position parameters as returned by e.g. read_head_pos. For backward compatibility, this can also be a tuple of (trans, rot t) as returned by head_pos_to_trans_rot_t.

orig_sfreqfloat | None

The original sample frequency of the data (that matches the event sample numbers in Can be None if data have not been decimated or resampled.

picksstr | list | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values “all” to pick all channels, or “data” to pick data channels. None (default) will pick all data channels.

originarray_like, shape (3,) | str

Origin of internal and external multipolar moment space in head coords and in meters. The default is 'auto', which means a head-digitization-based origin fit.


If True, all channels are weighted by the SSS basis weights. If False, only MEG channels are weighted, other channels receive uniform weight per epoch.


Order of internal component of spherical expansion.


Order of external component of spherical expansion.

regularizestr | None

Basis regularization type, must be “in” or None. See mne.preprocessing.maxwell_filter() for details. Regularization is chosen based only on the destination position.

destinationstr | array_like, shape (3,) | None

The destination location for the head. Can be None, which will not change the head position, or a string path to a FIF file containing a MEG device<->head transformation, or a 3-element array giving the coordinates to translate to (with no rotations). For example, destination=(0, 0, 0.04) would translate the bases as --trans default would in MaxFilter™ (i.e., to the default head location).

New in version 0.12.


If True, do not include reference channels in compensation. This option should be True for KIT files, since Maxwell filtering with reference channels is not currently supported.


If True, return the mapping matrix.

mag_scalefloat | str

The magenetometer scale-factor used to bring the magnetometers to approximately the same order of magnitude as the gradiometers (default 100.), as they have different units (T vs T/m). Can be 'auto' to use the reciprocal of the physical distance between the gradiometer pickup loops (e.g., 0.0168 m yields 59.5 for VectorView).

New in version 0.13.

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

evokedinstance of Evoked

The averaged epochs.


The Maxwell filtering version of this algorithm is described in [1], in section V.B “Virtual signals and movement correction”, equations 40-44. For additional validation, see [2].

Regularization has not been added because in testing it appears to decrease dipole localization accuracy relative to using all components. Fine calibration and cross-talk cancellation, however, could be added to this algorithm based on user demand.

New in version 0.11.



Taulu S. and Kajola M. “Presentation of electromagnetic multichannel data: The signal space separation method,” Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005.


Wehner DT, Hämäläinen MS, Mody M, Ahlfors SP. “Head movements of children in MEG: Quantification, effects on source estimation, and compensation. NeuroImage 40:541–550, 2008.