This documentation is for development version 0.18.dev0.

mne.epochs.average_movements

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.

Parameters:
epochs : instance of Epochs

The epochs to operate on.

head_pos : array | 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_sfreq : float | None

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

picks : str | 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.

origin : array-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.

weight_all : bool

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.

int_order : int

Order of internal component of spherical expansion.

ext_order : int

Order of external component of spherical expansion.

regularize : str | 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.

destination : str | 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.

ignore_ref : bool

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.

return_mapping : bool

If True, return the mapping matrix.

mag_scale : float | 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.

verbose : bool, str, int, or None

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

Returns:
evoked : instance of Evoked

The averaged epochs.

Notes

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.

References

[1](1, 2) 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.
[2](1, 2) 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.