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)

Average data using Maxwell filtering, transforming using head positions.

Parameters:

epochsinstance of Epochs

The epochs to operate on.

head_posarray | None

If array, movement compensation will be performed. The array should be of shape (N, 10), holding the position parameters as returned by e.g. read_head_pos.

orig_sfreqfloat | 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.

picksstr | array_like | 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. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

originarray_like, shape (3,) | str

Origin of internal and external multipolar moment space in meters. The default is 'auto', which means (0., 0., 0.) when coord_frame='meg', and a head-digitization-based origin fit using fit_sphere_to_headshape() when coord_frame='head'. If automatic fitting fails (e.g., due to having too few digitization points), consider separately calling the fitting function with different options or specifying the origin manually.

weight_allbool

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_orderint

Order of internal component of spherical expansion.

ext_orderint

Order of external component of spherical expansion.

destinationpath-like | array_like, shape (3,) | instance of Transform | None

The destination location for the head. Can be:

None

Will not change the head position.

Transform

A MEG device<->head transformation, e.g. info["dev_head_t"].

numpy.ndarray

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).

path-like

A path to a FIF file containing the destination MEG device<->head transformation.

ignore_refbool

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_mappingbool

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 v0.13.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

evokedinstance of Evoked

The averaged epochs.

See also

mne.preprocessing.maxwell_filter

mne.chpi.read_head_pos

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 v0.11.

References

[1]

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]

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.

Examples using mne.epochs.average_movements

Signal-space separation (SSS) and Maxwell filtering

Signal-space separation (SSS) and Maxwell filtering

Maxwell filter data with movement compensation

Maxwell filter data with movement compensation