= CTF + pos coil orientation bug correction =
''Author: Marc Lalancette''

There existed a bug until recently ([[https://github.com/brainstorm-tools/brainstorm3/commit/500da9f2d8b4df02940da85a5fb0d9e2e8f8b503|fixed on Dec 6, 2018]]) when reading CTF recordings __with a headshape .pos file__ that would introduce an error in MEG coil orientations on the order of 1%. These errors would propagate to the forward and inverse solutions and thus affect any results in source space.

For users currently analyzing data where the bug is present, we created a process (available since [[https://github.com/brainstorm-tools/brainstorm3/commit/96c5ca14e4ce77aea06ebd1b96d4fff4fa4dfb5f|Feb 16, 2019]]) that can reset a channel file while keeping existing projectors and history, to avoid having to restart analysis from zero.  This short tutorial shows how to fix data already read and pre-processed in Brainstorm.

If you choose to proceed with fixing your data, understand that all existing data including and past computing a forward model will have to be discarded and recomputed.

== Correction steps ==
 * First, make sure your copy of Brainstorm is up to date.

When manually selecting files and folders, raw and imported data cannot be processed at the same time, so if you wish to keep some imported data as well, you can either process them separately, or use a file selection process.  The latter option allows you to process your entire protocol at once.

 * Click Run with an empty Process1 box
 * Add the process ''File > Select files: recordings''

 . {{attachment:CoilBug_Select.png||height="277",width="347"}}

The process will work best if the original raw data is still available in the same location as when it was first read into Brainstorm. If this is no longer the case and the raw files cannot be put back in their original location for some reason, the process will prompt you to select each distinct channel file once manually.  This is another reason to prefer processing all files at once since many raw and imported files can point to the same original channel file.

 * Add the ''Standardize > Adjust coordinate system'' process to the pipeline and select the first option: Reset coordinates...  Also specify the file format.

 . {{attachment:CoilBug_Adjust.png||height="300",width="509"}}

The other options are described in the [[https://neuroimage.usc.edu/brainstorm/Tutorials/HeadMotion#Adjust_the_reference_head_position|Head Motion tutorial]]. While you can select other options like Adjust head position and Refine MRI coregistration, note that if a file fails these extra steps (e.g. because of missing head coil channels or head points file - which would be the case for a noise recording), then that channel file is not modified at all, even if the reset step would have succeeded on its own.  It is thus important to pay attention to errors in the pipeline report to ensure all files were fixed.

 * Run the pipeline.

If the original data is no longer in the same location and you get prompted to select a channel file, the original file name and location and the subject and condition to which it refers will be indicated in a text box at the top of the screen.

 . {{attachment:CoilBug_ManualSelect.png||height="443",width="481"}}

== Verification ==
First recall that this bug only affects CTF recordings that had a Polhemus head points file (.pos) associated with it at the moment of reading.  Other than going by the Brainstorm version and data import dates, one way to verify if a specific channel file was affected by the bug is to link the same raw data again (after updating Brainstorm) and to compare coil orientations with the data that was linked or imported previously. This can be done by exporting the two channel files to Matlab and comparing the structures.

To verify if a specific channel file was reset successfully after following the instructions above, you can look at the history field. Right-click on the channel file and select ''File > View file history''. There should be a line containing: "import  | Reset from: ..."