= Tutorial - Head Motion =
''Authors: Marc Lalancette''

All efforts should be made to avoid any movements and in particular head movements during a MEG recording, as it can cause various issues such as blurring of signals and loss of amplitude, mis-localization of source activity, and possibly motion artefacts.  Yet it is important to evaluate and account for any head motion at the time of analysis.  This is possible because the positions of the head tracking coils are saved in channels along the MEG data.  It is important to note however that most analysis software, including Brainstorm, assume a single fixed position for the head for most computations.  This "reference" position is the one that is measured just before the recording starts and that is saved separately from the continuous head localization channels.

This tutorial will explore different options on how to deal with head motion, using the example dataset from the tutorial: [[Tutorials/RestingOmega|MEG resting state & OMEGA database (CTF)]]. See there for details on how to download the dataset and load it in Brainstorm.  Note that importing all the subjects can take a while; for this tutorial, you can only import sub-0007.

<<TableOfContents(2,2)>>

== Motion visualization ==
First, in order to evaluate the level of motion, we will display a special montage based on the head localization coils.  This calculates the distance at each point in time with respect to the initial/reference head position. That distance is based on a sphere (approximating the head) attached to these head coils, thus accounting for all types of motion of all parts of the head equally.

 * After reviewing the raw data for subject sub-0007, right-click on the task-rest run > Switch epoched/continuous.

 * Right-click on the run again > HLU > Display time series.

 . {{attachment:HLUDisplay1.png||width="389",height="314"}}

 * On the Record tab, make sure DC is not selected (or you'll get a warning) and select the Head Distance montage.
 . {{attachment:HLUDisplay2.png||width="197",height="122"}}

 * Set the Page settings duration to 300 seconds to see a good part of the recording at once. It may take a little time for the data to load.
 . {{attachment:HLUTimeseries.png||width="637",height="280"}}

== Adjust the reference head position ==
Given that the default reference position is measured at the very beginning of the recording, we can improve co-registration by replacing it with one that better represents the position throughout.  For more details on how Brainstorms coregisters various files and their coordinate systems, see [[CoordinateSystems|Coordinate Systems]].

 * Drag the raw recording to the Process1 tab and click Run.  Select Process > Import > Channel file > Adjust coordinate system.  Select the Adjust head position and Display options, as below:

 . {{attachment:Adjust1_new.png|Adjust1.png|width="509",height="274"}}

 * '''Reset coordinates using original channel file''': This option will re-import the original channel file for this data if it is still present (or prompt for the file if missing), resetting all channel coordinates.  It thus removes any manual adjustment, head position adjustment or head point alignment.  This is the cleanest and recommended way to undo transformations when a manual adjustment or multiple transformations were previously performed.  Note that while most of the channel information is reset, it keeps existing projectors (SSP, ICA) and history.

 * '''Adjust head position to median location''': This will adjust the co-registration between the MEG sensors and the digitized head coil positions.  In Brainstorm terms, it is the "Dewar=>Native" transformation that is adjusted, but the adjustment is saved in the channel file as a separate "AdjustedNative" transformation properly placed right after "Dewar=>Native" and before any additional transformations such as the one created by "Refine using head points".  The new reference head position is based on the geometric median of each localization coil positions throughout the recording. Note that it is safe to run this process multiple times.  The correction will only be applied once.

 * '''Refine MRI coregistration using digitized head points''': See the [[Tutorials/ChannelFile#Automatic_registration|Automatic Registration]] tutorial. This option is repeated here for convenience and because this process also allows to remove this transformation (see next option).

 * '''Remove selected adjustments (if present) instead of adding them''': This will undo the "Adjust head position" or "Refine using head points" transformations if they are selected above and if they were previously applied.

 * '''Display "before" and "after" alignment figures''': This will open the same figure as "MRI registration > Check", both before and after the change selected above to visualize the adjustment.

 * Run the process.

The figures don't show much difference for this recording, but we can notice a small drop looking at the LPA point and the head point near the back edge of the helmet. A message in the Matlab command window also tells us that the position changed by 3.7 mm.

 . {{attachment:Adjust2.png||width="740",height="387"}}

 * Display the HLU time series again.  The distance to the reference position is now reduced and closest in the middle of the recording.
 . {{attachment:HLUTimeseries_Adjusted.png||width="614",height="261"}}

== Mark head motion events ==
For long recordings, such as is typical for epilepsy, or when a large movement is present, a single head position may not be appropriate for the entire duration.  In these cases, it may be preferable to split the recording in smaller segments where the head is stable and reject segments where too much motion is present.  To do this, we first need to detect and mark these segments.  Note that this process does not depend in any way on the reference position, so there is no need to adjust it first as we did.

There is not much motion in this dataset, so we will use extremely conservative thresholds to illustrate this process.

 * With the recording still in the Process1 tab, click Run.  Select Process > Events > Detect head motion (CTF).  Use these settings:

 . {{attachment:MarkEvents.png||width="347",height="265"}}

 * '''Movement threshold''': For each segment, the head position distance from the first sample of the segment is measured.  As soon as it exceeds this threshold, a new segment is created.

 * '''Minimum split length''': If a segment is smaller than this length, it will be marked as BadHeadMotion.  It represents segments where the displacement was too large and too fast.

 * '''Detect head coil fit errors''': Along with their position, the head coil localization fit error is recorded.  If this error is large, the position cannot be trusted.  In practice, a bad fit often happens along with movement or a coil being too far from the helmet, i.e. a bad head position. However, it could also indicate that a head coil fell off of the subject, in which case the data might still be good.

 * '''Fit error tolerance''': Segments where the error goes above this threshold will be marked as BadHeadFit.

 * Run the process.
 * Display the HLU time series one more time.
 . {{attachment:HLUTimeseries_Marked.png||width="554",height="256"}}

In this first half of the dataset, we see one bad segment and three stable segments that correspond well with the jumps in the distance time series. We can also see these two new event groups in the Record tab. Note that it took a few tries with different thresholds and minimum durations to get the segments to fit that well.

== Split the recording ==
We now can proceed to splitting our raw recording into segments with a stable head position, based on the head motion events.

 * Again, with the recording in the Process1 pane, click Run.  Select Process > Import > Import recordings > Split Raw File.  Use the StableHead events we just created.

 . {{attachment:SplitEvents.png||width="347",height="191"}}

 * '''Event name''': Name of the extended event group to extract from the raw recording.

 * '''Keep segments outside of continuous event?''': If this is selected, it will also produce files for any segment of the raw recording that is not included in one of the extended event selected.  In our case, it would also extract the BadHeadMotion segments, which we don't need.

 * Run the process.

A new condition appears in the database explorer for each extracted segment.

 . {{attachment:SplitEvents2.png||width="314",height="208"}}

We now should correct the reference position for each new raw file, otherwise the splitting would not achieve much.

 * Clear the Process1 tab and add the 5 new raw conditions.
 * Run the Adjust coordinate system process, again selecting only Adjust head position.

Note that the process will detect and replace the previous head position adjustment we made (no need to remove it first).

 * Select the recording of the first segment and display the HLU distance montage.
 . {{attachment:HLUTimeseries_Stable.png}}

We now see the head distance stays below half a mm until the end of the segment where it jumps to about 1.5 mm, close to our threshold.  You can check that the other segments have similarly low remaining motion.

== Fixing swapped head coils ==
If head coils were plugged incorrectly during the recording, the MEG co-registration will be completely off.  Manually editing the .hc file would prevent the other head motion tools described here from working properly.

The first step for fixing this is to identify which coils were swapped.  You can determine this by opening the dataset .hc file (in any text editor) and comparing the coordinates of the standard positions with those of the measured positions "relative to dewar", or even just the signs of the x and y coordinates.  For example, if the standard (x, y) signs are: nasion (+, +), left ear (-, +), right ear (+, -), and the measured signs are: nasion (+, -), left ear (+, +), right ear (-, +), then all three coils were swapped in a cycle.

 * Select Process > Import > Channel file > Swap head coils (CTF)
 * Put a check mark next to the coils you identified as swapped.  In our example, we'd select all three coils.

If the 3 coils were wrong, there are two ways they could be ordered.  The "Reverse order" check box allows specifying which one.  In our example, you should not check "Reversed order".  But if you try one and it doesn't fix your case, you can simply reset the channel file (Process > Import > Channel file > Adjust coordinate system), and then try the other order.

Note that this swap process also adjusts the reference head position as described above, after the swap.

== Dealing with a missing or bad head coil [Under construction] ==
If only 3 head coils are used and one falls off or is defective, and if this issue is present both in the reference and the continuous head positions, there is no way to exactly know the head position relative to the MEG sensors for the affected recording(s), preventing precise source space analysis.  However, if 2 of the 3 coils are well localized and another recording for the same participant and same session is available that has good localization of all 3 coils, we can correct the bad coil with a best guess as to its likely position, assuming the head was positionned in a similar way in the helmet.  It is important to remember that this is only a best guess and that in theory, having only 2 coils leaves an undetermined head rotation.

Our fix is applied at each time sample assuming the missing coil is in the direction perpendicular to the plane spanned by the line through the 2 good coils and the head coordinate system z-axis of the provided "good head position" (typically from another recording). This gives us a position for the coil relative to the helmet.

 * Select the Process2 tab and drag the bad recording to "Files A" and the good recording to "Files B".
 * Select Process > Import > Channel file > Fix bad head coil (CTF)
 * [TO DO: option to provide the "good head position" manually, in dewar coordinates.]
 * Run the process.

[TO DO: add example screenshots]

== Head motion correction with SSS [TO DO] ==
Signal Space Separation (SSS) is a data cleaning technique that uses a spherical harmonic decomposition of the MEG signal to separate it into components originating from inside or outside the sensor shell.  By reconstructing the signal with only the "inside" components, environmental interference is reduced.

The same spherical harmonic expansion can be used to correct for head motion by reconstructing the signal with new sensor locations adapted to the head position at each instant.  (In the head coordinate system, head motion translates to motion of the sensor array.)  In other words, we correct for head motion by interpolating the field at new sensor locations, using spherical harmonics for the interpolation.

The SSS process can therefore be used both for motion correction and signal cleaning, but here we will use it only for motion correction.  In that case, the process takes care of selecting the expansion orders for inside and outside harmonics, using in total as many harmonics as sensors.

== Additional documentation ==
==== Articles ====
 * Taulu, S., Kajola, M. & Simola, J. <<BR>>[[https://doi.org/10.1023/B:BRAT.0000032864.93890.f9|Suppression of Interference and Artifacts by the Signal Space Separation Method]] <<BR>>Brain Topogr. (2004) 16:269

 * Taulu, S. & Kajola, M.<<BR>>[[https://doi.org/10.1063/1.1935742|Presentation of electromagnetic multichannel data: The signal space separation method]]<<BR>> J. Appl. Phys. (2005) 97:124905

 * Taulu, S. & Simola, J. <<BR>>[[https://doi.org/10.1088/0031-9155/51/7/008|Spatiotemporal signal space separation method for rejecting nearby interference in MEG measurements]]<<BR>>Phys. Med. Biol. (2006) 51:1759