Functions for forward and inverse computation of EEG/MEG data
Recent changes to the forward code
Recent changes to the inverse code
Related documentation

Functions for forward and inverse computation of EEG/MEG data

FieldTrip has a consistent set of low-level functions for forward and inverse computations, i.e. source estimation. The main reason for making the functions consistent is that that facilitates supporting the different methods in the FieldTrip toolbox. Another reason is that this allows other projects to re-use the implemented methods and perhaps also to contribute to FieldTrip.

The low-level functions are combined in the forward and the inverse toolboxes, which are released together with FieldTrip but can also be downloaded here as separate toolboxes. In the past these functions were combined in one toolbox.

Module layout

Both, the forward and inverse modules contain high-level functions that are publicly available for the end-user. The functionality of these functions within these modules depend on low-level functions. This is in particular the case for the forward module where high-level functions depend on functions for specific head models. These functions are not available to the end-user and combined in a private directory.

Supported methods for forward computations of the potential or field

The following forward methods are implemented for computing the electric potential (EEG):

single sphere
multiple concentric spheres with up to 4 shells
boundary element model using dipoli, using external command-line executable
boundary element model using openmeeg, using external command-line executable
boundary element model using bemcp, using external mex files
all forward models supported by the Neuromag meg-calc toolbox

The following forward methods are implemented for computing the magnetic field (MEG):

single sphere
multiple spheres, one for each sensor
realistic single-shell model based on leadfield expansion (Nolte method)
all forward models supported by the Neuromag meg-calc toolbox

Supported methods for inverse estimation of the source parameters

The inverse methods for computing a source reconstruction can be divided into three categories: dipole fitting (using an overdetermined model with a few sources), dipole scaning (using a metric that can be computed independently on each point of a grid) and distributed source modelling (using an underdetermined distributed source model). The following source reconstruction methods are implemented

dipole fitting
- simultaneous optimisation of position, orientation and strength
- symmetry constrains and/or fixed position, with free orientation and strength
dipole scanning
- dynamic imaging of coherent sources (DICS)
- linear constrained minimum variance (LCMV)
- partial canonical coherence (PCC)
- multiple signal classification (MUSIC)
- scanning for residual variance
distributed source modeling
- minimum norm estimation without regularisation (MNE)

Definition of the function-calls (API)

To read in the volume conduction model and the definition of the sensor array (electrodes or gradiometers) from file, one would start with:

[vol]  = read_vol(filename)
[sens] = read_sens(filename)

If desired the volume conduction model and the sensor array can be spatially transformed using a 4×4 homogenous transformation matrix. E.g. the electrodes can be translated and rotated to align them with head coordinate system, or they can be translated and rotated to switch to another coordinate system.

[vol]  = transform_vol(transform, vol)
[sens] = transform_sens(transform, sens)

Prior to all forward and inverse computations, the following function should be called:

[vol, sens] = prepare_vol_sens(vol, sens, ...)

The only function that is subsequently required for computing the potential or field distribution is

[lf] = compute_leadfield(pos, sens, vol, ...)

The functions for the inverse computation of the source activity, i.e. for computing the source reconstruction are

[dipout] = dipole_fit(dip, sens, vol, dat, ...)
[dipout] = beamformer_dics(dip, sens, vol, dat, cov, ...)
[dipout] = beamformer_lcmv(dip, sens, vol, dat, cov, ...)
[dipout] = beamformer_pcc(dip, sens, vol, dat, cov, ...)
[dipout] = music(dip, sens, vol, dat, ...)
[dipout] = minimumnormestimate(dip, sens, vol, dat, ...)
[dipout] = residualvariance(dip, sens, vol, dat, ...)

The input array “pos” contains the dipole position (1×3 or Nx3).

The input structure “dip” contains the initial dipole model or dipole grid that is used for source reconstruction.

The input structure “sens” contains the electrode positions or the gradiometer positions and orientations.

The input structure “vol” contains the geometry and conductivity of the volume conductor model.

Most functions have additional optional input arguments that are specified as key-value pairs.

Recent changes to the forward code

2010-06-29 14:16  roboos

	* ft_prepare_vol_sens.m: also work for multisphere MEG volumeconductor in case it has
	  already been prepared before (i.e. if ncoils==nspheres)

2010-06-29 14:10  roboos

	* ft_senstype.m: improved detection of itab MEG system

2010-05-26 12:55  roboos

	* ft_apply_montage.m: fixed bug with freq/fourier input data, see
	  http://bugzilla.fcdonders.nl/show_bug.cgi?id=2
	  the test script that reproduced the bug (and after fixing it showed correct behaviour) is
	  testing/test_bugzilla_2

2010-05-20 08:41  tilsan

	* ft_senstype.m: comparative level for Yokogawa decreased to 0.4 to allow
	  a proper detection for mixed axial/planar gradiometer systems

2010-05-17 07:52  roboos

	* private/find_inside_vol.m: added all dependencies as externals to inverse/private

2010-05-09 11:15  roboos

	* apply_montage.m, compat/apply_montage.m, ft_apply_montage.m: renamed apply_montage to
	  ft_apply_montage, updated external in fileio/private

2010-05-09 11:12  roboos

	* apply_montage.m: moved apply_montage to forward

2010-05-03 12:31  stekla

	* private/meg_leadfield1.mexw64: Added .mexw64 files as provided by Guillaume Flandin, added
	  "blob" element to header in ft_write_data for the rt_fmriproxy -- this will be changed
	  again once properly formatted header information is contained in Fieldtrip buffer.

2010-05-03 08:36  roboos

	* ft_senslabel.m: changed internal flow of the code (switch-ladder instead of eval), no
	  functional change

2010-04-28 14:32  stekla

	* private: Added external "warp_apply" to pull this from "fileio/private". Not sure if
	  that's the correct location, but the corresponding external in "public" does the same.

2010-04-23 08:04  roboos

	* ft_compute_leadfield.m: implemented support for weighting the leadfield at each dipole
	  location, e.g. to compensate for varying triangle size in a cortical mesh

2010-04-21 17:51  roboos

	* ft_compute_leadfield.m, ft_convert_units.m, ft_estimate_units.m, ft_inside_vol.m,
	  ft_prepare_vol_sens.m, ft_senslabel.m, ft_senstype.m, ft_sourcedepth.m,
	  ft_transform_headshape.m, ft_transform_sens.m, ft_transform_vol.m, ft_voltype.m,
	  private/avgref.m, private/bounding_mesh.m, private/eeg_leadfield1.m,
	  private/eeg_leadfield4.m, private/eeg_leadfield4_prepare.m, private/eeg_leadfieldb.m,
	  private/elproj.m, private/find_innermost_boundary.m, private/find_inside_vol.m,
	  private/find_outermost_boundary.m, private/fitsphere.m, private/fixdipole.m,
	  private/inf_medium_leadfield.m, private/leadsphere_all.m, private/legs.m,
	  private/lmoutr.m, private/magnetic_dipole.m, private/meg_forward.m, private/meg_ini.m,
	  private/meg_leadfield1.m, private/normals.m, private/plgndr.m, private/project_elec.m,
	  private/ptriproj.m, private/solid_angle.m, private/sphfit.m, private/transfer_elec.m,
	  private/triangle4pt.m: added full GPL copyright statement and svn ID tag for forward and
	  forward/private functions
	  cleaned up the documentation for some functions
	  no functinoal change

2010-04-16 08:20  timeng

	* ft_senstype.m, ft_transform_sens.m: ft_ prefixes adapted in code for functionality without
	  compat.

2010-04-14 15:24  vlalit

	* private/eeg_leadfieldb.m: Changes to enable re-integration of Fieldtrip and SPM8. Mostly
	  changes in prefixes that have not been done before.

2010-04-14 10:49  roboos

	* compat/apply_montage.m, convert_units.m, estimate_units.m, ft_convert_units.m,
	  ft_estimate_units.m: re-added ft_ prefix to convert and estimate_units, removed
	  compat/apply_montage wrapper

2010-04-14 10:48  roboos

	* convert_units.m, estimate_units.m: moved from fieldtrip/public to forward

2010-04-14 10:47  roboos

	* .: removed externals (apply_montage, convert_units, estimate_units)

2010-04-09 13:47  timeng

	* ft_compute_leadfield.m, ft_inside_vol.m, ft_prepare_vol_sens.m, ft_senslabel.m,
	  ft_senstype.m, ft_sourcedepth.m, ft_transform_headshape.m, ft_transform_sens.m,
	  ft_transform_vol.m, ft_voltype.m: ft prefix added to help sections and in the codes only
	  for functions called within the preproc and forward module. Compat now still necessary
	  called from main FieldTrip functions

2010-04-09 10:33  roboos

	* ft_voltype.m: fixed bug, always remember the previous argin and argout, not only on first
	  call

2010-04-08 11:03  roboos

	* compat/apply_montage.m, compat/compute_leadfield.m, compat/convert_units.m,
	  compat/estimate_units.m, compat/inside_vol.m, compat/prepare_vol_sens.m,
	  compat/senslabel.m, compat/senstype.m, compat/sourcedepth.m, compat/transform_headshape.m,
	  compat/transform_sens.m, compat/transform_vol.m, compat/voltype.m, ft_compute_leadfield.m,
	  ft_inside_vol.m, ft_prepare_vol_sens.m, ft_senslabel.m, ft_senstype.m, ft_sourcedepth.m,
	  ft_transform_headshape.m, ft_transform_sens.m, ft_transform_vol.m, ft_voltype.m,
	  private/avgref.m, private/bounding_mesh.m, private/eeg_leadfield1.m,
	  private/eeg_leadfield4.m, private/eeg_leadfieldb.m, private/elproj.m,
	  private/find_innermost_boundary.m, private/find_inside_vol.m,
	  private/find_outermost_boundary.m, private/fitsphere.m, private/fixdipole.m,
	  private/inf_medium_leadfield.m, private/leadsphere_all.m, private/legs.m,
	  private/lmoutr.m, private/magnetic_dipole.m, private/meg_forward.m, private/meg_ini.m,
	  private/meg_leadfield1.m, private/normals.m, private/plgndr.m, private/project_elec.m,
	  private/ptriproj.m, private/solid_angle.m, private/sphfit.m, private/transfer_elec.m,
	  private/triangle4pt.m: removed the unix executable flag from all *.m files (thanks to
	  Guillaume)
	  see http://fieldtrip.fcdonders.nl/development/svn#keeping_the_svn_repository_tidy for
	  details

2010-04-07 14:32  roboos

	* COPYING, README: added and updated README and COPYING files

2010-04-07 14:08  roboos

	* ., compat, compat/apply_montage.m, compat/compute_leadfield.m, compat/convert_units.m,
	  compat/estimate_units.m, compat/inside_vol.m, compat/prepare_vol_sens.m,
	  compat/senslabel.m, compat/senstype.m, compat/sourcedepth.m, compat/transform_headshape.m,
	  compat/transform_sens.m, compat/transform_vol.m, compat/voltype.m, ft_compute_leadfield.m,
	  ft_inside_vol.m, ft_prepare_vol_sens.m, ft_senslabel.m, ft_senstype.m, ft_sourcedepth.m,
	  ft_transform_headshape.m, ft_transform_sens.m, ft_transform_vol.m, ft_voltype.m, private:
	  moved the forward computation functions (compute_leadfield etc.) from fieldtrip/forwinv to
	  fieldtrip/forward
	  and renamed them from xxx into ft_xxx for improved compatibility with spm8
	  added a forward/compat directory with backward compatibility wrappers

Recent changes to the inverse code

2010-07-06 08:42  roboos

	* private: cosmetic change to svn:externals in forward/private, no functional change

2010-05-17 07:52  roboos

	* private: added all dependencies as externals to inverse/private

2010-05-17 07:39  roboos

	* private: added private directory with a number of externals

2010-04-16 13:28  timeng

	* beamformer_dics.m, beamformer_lcmv.m, beamformer_pcc.m, dipole_fit.m,
	  minimumnormestimate.m, music.m, residualvariance.m: ft_ prefix adapted in code. In
	  particular inverse and fileio modules are now independentof compat

2010-04-08 11:03  roboos

	* beamformer_dics.m, beamformer_lcmv.m, beamformer_pcc.m, dipole_fit.m,
	  minimumnormestimate.m, music.m, residualvariance.m: removed the unix executable flag from
	  all *.m files (thanks to Guillaume)
	  see http://fieldtrip.fcdonders.nl/development/svn#keeping_the_svn_repository_tidy for
	  details

2010-04-07 14:32  roboos

	* README: added and updated README and COPYING files

2010-04-07 14:29  roboos

	* ., COPYING, README, beamformer_dics.m, beamformer_lcmv.m, beamformer_pcc.m, dipole_fit.m,
	  minimumnormestimate.m, music.m, residualvariance.m: moved the remaining functions for
	  source estimation from forwinv to the fieldtrip/inverse directory
	  at this time I have NOT renamed them into ft_xxx because the API of th efunctions will
	  also have to change, thereby breaking backward compatibility

Can I restrict the source reconstruction to the grey matter?	2009/02/17 15:18	Robert Oostenveld
How are the different head and MRI coordinate systems defined?	2009/02/17 15:16	Robert Oostenveld
How can I determine the anatomical label of a source?	2010/04/25 07:50	Robert Oostenveld
Is it important to have accurate measurements of electrode locations for EEG source reconstruction?	2009/02/17 15:18	Robert Oostenveld
What is the conductivity of the brain, CSF, skull and skin tissue?	2010/01/12 10:44
What kind of volume conduction models are implemented?	2009/02/17 15:15	Robert Oostenveld
Where can I find the dipoli command-line executable?	2009/02/26 22:06
Why is there a rim around the brain for which the source reconstruction is not computed?	2009/02/17 15:16	Robert Oostenveld

Align EEG electrode positions to BEM headmodel	2009/03/03 21:52
Analysing sources of evoked fields using an LCMV-beamformer	2009/02/26 22:06
Common filters in beamforming	2009/03/05 11:07	Saskia Haegens
Compute forward simulated data and apply a beamformer scan	2009/03/03 21:52
Compute forward simulated data and apply a dipole fit	2009/03/03 21:52
Create BEM headmodel for EEG	2009/05/20 14:57
Create MNI-aligned grids in individual head-space	2009/07/31 11:49
Example use of the compute_leadfield function	2010/07/21 11:04	Robert Oostenveld
Fit a dipole to the tactile ERF after mechanical stimulation	2009/05/20 14:57
Generate simulated data	2009/03/03 21:58
Make leadfields using different headmodels	2009/05/20 14:57
Plotting the result of source reconstructing on a cortical mesh	2010/04/22 08:59	Robert Oostenveld
Shift electrode positions into the same coordinate system as the corresponding MRI for using individual headmodels	2009/03/03 21:58
Source statistics	2009/03/05 16:56	Saskia Haegens
Use your own forward leadfield model in an inverse beamformer computation	2009/03/03 21:58

Localizing oscillatory sources using beamformer techniques	2009/05/20 14:57
Making analysis protocols	2009/02/17 15:02	Robert Oostenveld
Plotting data at the channel and source level	2010/01/07 14:10