trying to address #633

- I have made  a first pass over the headmodel_eeg_bem tutorial
- I updated some of the FAQs
- I updated the pipeline figures and added plotting at every step
- the plotting is not yet explicitly documented in the EEG BEM tutorial itself
- I also renamed (also on the download server) the folders with the tutorial data

_includes/shared/tutorial/headmodel_background.md

@@ -1,3 +1,3 @@
-In FieldTrip a volume conduction model is represented as a MATLAB structure which is usually indicated with the variable name **vol**. It describes how the currents flow through the tissue, not where they originate from. In general it consists of a description of the geometry of the head, a description of the conductivity of the tissue, and mathematical parameters that are derived from these. Whether and how the mathematical parameters are described depends on the computational solution to the forward problem either by numerical approximations, such as the boundary element and finite element method (BEM and FEM), or by exact analytical solutions (e.g., for spherical models).
+A volume conduction model of the head, also known as a head model, is represented in FieldTrip as a MATLAB structure. It describes how the currents flow through the tissue, not where they originate from. In general it consists of a description of the geometry of the tissue(s), a description of the conductivity of the tissue(s), and mathematical parameters that are derived from these. Whether and how the mathematical parameters are described depends on the computational solution to the forward problem either by numerical approximations, such as the boundary element and finite element method (BEM and FEM), or by exact analytical solutions (e.g., for spherical models).
 
 The more accurate the description of the geometry of the head or the source, the better the quality of the forward model. There are many types of head models which, to various degrees, take the individual anatomy into account. The different head models available in FieldTrip are listed [here](/faq/what_kind_of_volume_conduction_models_are_implemented).

_includes/shared/tutorial/sourcelocalization_background.md

@@ -1,18 +1,18 @@
 The EEG/MEG signals measured on the scalp do not directly reflect the location of the activated neurons. To reconstruct the location and the time-course or spectral content of a source in the brain, various source-localization methods are available. You can read more about the different methods in review papers suggested [here](/references_to_implemented_methods#references_to_review_papers).
 
-The level of the activity at a source location is estimated from
+The activity in the brain responsible for the EEG or MEG signals is estimated from
 
 1.  the EEG/MEG activity measured on or around the scalp
 2.  the spatial arrangement of the electrodes/gradiometers (**sensor positions**),
 3.  the geometrical and conductive properties of the head (**head model**)
 4.  the location of the source (**source model**)
 
-Using this information, source estimation comprises two major steps: (1) Estimation of the potential or field distribution for a known source and for a known model of the head is referred to as **forward modeling**. (2) Estimation of the unknown sources corresponding to the measured EEG or MEG is referred to as **inverse modeling**.
+Using this information, source estimation comprises two major steps: (1) Estimation of the EEG potential or MEG field distribution for a known source is referred to as **forward modeling**. (2) Estimation of the unknown sources corresponding to the measured EEG or MEG is referred to as **inverse modeling**.
 
-The forward solution can be computed when the head model, the sensor positions and the source is given. For distributed source models and for scanning approaches (such as beamforming), the source model is discretizing the brain volume into a volumetric or surface grid. When the forward solution is computed, the **lead field matrix** (= channels X source points matrix) is calculated for each grid point taking into account the head model and the sensor positions.
+The forward solution can be computed when the head model, the sensor positions and the model for the source are given. For distributed source models and for scanning approaches (such as beamforming), the source model consists of a discrete description of the the brain volume or of the cortical sheet in many voxels or vertices. When the forward solution is computed, the **lead field matrix** (= channels X source points matrix) is calculated for each point, taking into account the head model and the sensor positions.
 
-A prerequisite of forward modeling is that the geometrical description of all elements (sensor positions, head model and source model) is registered in the same coordination system with the same units. There are different "conventions" how to define a coordinate system, but the precise coordinate system is not relevant, as long as all data is expressed in it consistently (i.e. in the same coordinate system). [Here](/faq/coordsys) read more about how the different head and mri coordinate systems are defined. The MEG sensors by default are defined relative to anatomical landmarks of the head (the fiducial coils), therefore when the anatomical images are also aligned to these landmarks, the MEG sensors do not need to be re-aligned. EEG data is typically not aligned to the head, therefore, the electrodes have to be re-aligned prior to source-reconstruction (see also [this faq](/faq/how_to_coregister_an_anatomical_mri_with_the_gradiometer_or_electrode_positions) and [this example](/example/electrodes2bem)).
+A prerequisite of forward modeling is that the geometrical description of all geometrical elements (sensor positions, head model and source model) is registered in the same coordination system and expressed with the same units (mm, cm, or m). There are different conventions for coordinate systems. The precise coordinate system is not relevant, as long as all data is expressed consistently. [Here](/faq/coordsys) you can read more about how the different head and MRI coordinate systems are defined. For most MEG systems, the gradometer sensors are by default defined relative to head localizer coils or anatomical landmarks, therefore when the anatomical MRI are aligned to the same landmarks, the position of the MEG sensors matches the MRI. EEG data is typically not explicitly aligned relatively to the head, therefore, the EEG electrodes also have to be re-aligned prior to source reconstruction (see also [this faq](/faq/how_to_coregister_an_anatomical_mri_with_the_gradiometer_or_electrode_positions) and [this example](/example/electrodes2bem)).
 
-{% include image src="/assets/img/shared/tutorial/sourcelocalization_background/figure1.png" width="500" %}
+{% include image src="/assets/img/shared/tutorial/sourcelocalization_background/figure1.png" width="600" %}
 
-_Figure 1. Major steps in source reconstruction_
+_Figure 1. Overall outline of the pipeline used for source reconstruction_

faq/homogenous.md

@@ -5,12 +5,19 @@ tags: [faq, coordinate]
 
 # How do homogenous coordinate transformation matrices work? Or how do I get the coordinates for a specific voxel?
 
-The documentation of the [AIR](http://air.bmap.ucla.edu/AIR5) software by Roger P. Woods provides a very nice description of [homogenous coordinates](http://air.bmap.ucla.edu/AIR5/homogenous.html). Another, perhaps more accessible description can be found on the [brainvoyager website](https://www.brainvoyager.com/bv/doc/UsersGuide/CoordsAndTransforms/SpatialTransformationMatrices.html).
+A coordinate system specifies the interpretation of how points are expressed in 3D space. This makes use of the three numbers (x, y, z) that represent the point, relative to a known origin (0,0,0), and making use of cardinal x-, y-, and z-axes that are pointing into a specific direction such as towards the nasion, or from the [posterior to the anterior commissure](/faq/acpc/).
 
-The long story short is, that a homogen(e)ous transformation matrix allows you to toggle between 3-dimensional points in space that are expressed in different coordinate systems (i.e. the points are expressed relative to an origin (with coordinate (0,0,0)), and where the three (orthogonal) coordinate axes are pointing into a specific direction). The conversion is achieved by simple matrix multiplication, as described in detail by one of the links above.    
+A homogenous transformation matrix allows you to transform 3D points from one coordinate system to another. The conversion is achieved by simple matrix multiplication, as described in detail in the documentation of the [AIR](http://air.bmap.ucla.edu/AIR5) software by Roger P. Woods. This provides a very complete description of [homogenous coordinates](http://air.bmap.ucla.edu/AIR5/homogenous.html). Another, perhaps more accessible description can be found on the [brainvoyager website](https://www.brainvoyager.com/bv/doc/UsersGuide/CoordsAndTransforms/SpatialTransformationMatrices.html).
 
-In FieldTrip, as in many other software packages that deal with volumetrically defined data, we use a homogen(e)ous coordinate transformation matrix to describe the relation between voxels in the volumetric image, and real world coordinates (typically a coordinate system that is defined based on the anatomy of the experimental subject). In FieldTrip, a **[volume data object](/reference/utilities/ft_datatype_volume)** always contains a `transform` field that maps from voxel indices to the coordinate system, which, if it is known, is specified in the `coordsys`. You can read more about coordinate systems [here](/faq/coordsys). The convention is that the indexing of the voxels starts with 1, i.e. the first voxel in the volume is described by the indices [1,1,1]. Thus, if you want to obtain the real world coordinate of a voxel with indices (i,j,k), you have to perform the following multiplication:
+In FieldTrip, as in many other software packages that deal with volumetrically defined data, we also use a homogen(e)ous coordinate transformation matrix to describe the relation between voxels in the volumetric data, and real-world or "head" coordinates. The [real-world coordinates](/faq/coordsys) are usually related to anatomical landmarks and the voxel coordinates are directly related to the 3D array with the grey-scale numbers that represent the MRI images.
 
-    coord = T * [i;j;k;1];
+The FieldTrip data structure that describes **[volumetric data](/reference/utilities/ft_datatype_volume)** includes a `transform` field with the homogenous 4x4 trasformation matrix that maps from voxel indices to the head (or device) coordinate system. If the head coordinate system is known, it is specified in the `coordsys` field.
 
-The variable `T` is the transform field of the data structure, and the first 3 elements of the `coord` vector are the (x,y,z) coordinates of the voxel-of-interest.
+Indexing of numerical arrays in MATLAB starts with 1, i.e., the first voxel in the volume is described by the indices (1,1,1). Thus, if you want to obtain the real world coordinate of a voxel with indices (i,j,k), you have to perform the following multiplication:
+
+    voxpos = [i j k 1]'
+    headpos = transform * voxpos
+
+The first 3 elements of the resulting `headpos` vector correspond to the (x,y,z) coordinates in the head coordinate system.
+
+Note that, if the MRI comes directly from the scanner, it still is expressed in DICOM or in NIFTI scanner coordinates, and not relative to actual anatomical landmarks of the individual participant whose data is represented in the MRI.

faq/how_to_coregister_an_anatomical_mri_with_the_gradiometer_or_electrode_positions.md

@@ -5,10 +5,24 @@ tags: [faq, eeg, meg, mri, headmodel, source, coordinate]
 
 # How to coregister an anatomical MRI with the gradiometer or electrode positions?
 
-In general, anatomical volumes are represented in FieldTrip as a MATLAB-structure, containing the anatomical (and if applicable also the functional) information in a 3D numeric matrix, and a [4x4] affine transformation matrix. The 4x4 homogenous transformation matrix specified how to go from voxel space to source space. When the anatomical image is read in using **[ft_read_mri](/reference/fileio/ft_read_mri)**, a transformation is attached to the data structure. This transformation matrix is extracted from the file. If this is not possible, FieldTrip assumes the transformation to be an identity matrix. Importantly, the assumption is that the transformation matrix and the voxel coordinate system are consistent between one another. Typically, when doing source reconstruction, we work with real world coordinate systems that are defined relative to the participant's head. When the anatomical images are coming off the scanner, they lack such a coordinate system, so this needs to be added to the data. Most MEG systems come with software to convert DICOM files to a MEG-system specific MRI file format. That software then also takes care of aligning the MRI with the helmet location. e.g., for CTF this is done with MRIConverter and MRIViewer. FieldTrip can read the MRI files that are generated using the MEG-system specific software, and if you use those, the alignment is taken care of outside FieldTrip. In case the alignment is not done with external software, or if you want to read the DICOM files directly, the **[ft_volumerealign](/reference/ft_volumerealign)** function can be used after **[ft_read_mri](/reference/fileio/ft_read_mri)**.
+In general, volumetric data such as anatomical MRIs are represented in FieldTrip as a MATLAB-structure, containing the anatomical (and if applicable also the functional) information in a 3D numeric matrix, combined with a 4x4 affine transformation matrix. The 4x4 transformation matrix specified how to go from voxel space to source space, as explained in this [frequently asked question](/faq/homogenous).
+
+When reading anatomical data with **[ft_read_mri](/reference/fileio/ft_read_mri)**, the transformation is extracted from the MRI file. In the case that the MRI has not been processed, it is likely that the coordinate system corresponds to DICOM or in NIFTI scanner coordinates, which do _not_ relate the coordinates to the actual anatomy represented in the data.
+
+You can read more about how the different coordinate systems relate to the anatomy and/or to the scanner hardware in this [frequently asked question](/faq/coordsys).
+
+## MEG
+
+When reading MEG data from the original files, the gradiometer sensor data is automatically read along with the channel timeseries. With most MEG systems the sensor positions are automatically expressed relative to head localization coils that are placed on the head relative to well-defined anatomical landmarks. The `coordsys` option in **[ft_read_sens](/reference/fileio/ft_read_sens)** also allows you to get the sensor positions relative to the device or dewar.
+
+For source reconstruction we need to express all geometrical data in a consistent coordinate system that is defined relative to the participant's head. In FieldTrip it is common to do MEG source reconstruction in the coordinate system of the MEG acquisition device. Consequently, the MRI needs to be updated using **[ft_volumerealign](/reference/ft_volumerealign)** so that it is expressed relative to the same anatomical landmarks as the MEG data.
 
 {% include markup/danger %}
-In its default behavior **[ft_volumerealign](/reference/ft_volumerealign)** creates a transformation matrix from fiducials/landmarks using a right-handed convention. If the input data is defined in a left-handed coordinate system, the resulting transformation matrix may be incorrect (when supplying only 3 fiducial locations). However, it is possible to define a 4th point in ft_volumerealign (using the 'z' key) that should be a point in the positive z-direction. Using this information, the correct transformation can be constructed.
+Other MEG analysis software may use other conventions. For example in MNE-Python it is common to do MEG source reconstruction in a coordinate system that is the result of the Freesurfer pipeline which is used to extract the cortical sheet. That means that, rather than aligning the MRI to the MEG, it aligns the MEG to one of the Freesurfer outputs.
 {% include markup/end %}
 
-EEG acquisition systems typically do not come with software to deal with anatomical MRIs, so you should read the MRI file(s) with **[ft_read_mri](/reference/fileio/ft_read_mri)** and use **[ft_volumerealign](/reference/ft_volumerealign)** to specify the position of the fiducials. The same fiducials should then be specified in **[ft_electroderealign](/reference/ft_electroderealign)** to ensure that both electrodes and anatomical MRI are expressed in the same head-coordinate system. See also the FAQ on the [definition of the various head and MRI coordinate systems](/faq/coordsys).
+## EEG
+
+EEG systems typically do not include an integrated way to record ans store EEG electrode positions. Although separate 3D tracking systems (e.g., Polhemus, Optotrack, Structure Sensor) can be used to record the electrode positions, the electrode positions are usually not stored directly along with the EEG data. So when reading the EEG data from disk, the position of the EEG electrodes is usually not known.
+
+For EEG it is therefore common to use **[ft_read_mri](/reference/fileio/ft_read_mri)** and **[ft_volumerealign](/reference/ft_volumerealign)** to place the anatomical  MRI in a well-defined coordinate system, and to use **[ft_read_sens](/reference/fileio/ft_read_sens)** and **[ft_electroderealign](/reference/ft_electroderealign)** to place the electrodes in the same coordinate system.