TITLE: Data Processing and Image Registration
AUTHORS: Elizabeth Neumann, Nathan Heath Patterson, Lukasz Migas, Jamie Allen, Carrie  Romer, Jeff Spraggins, Danielle Gutierrez

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block">Scope: </div><div class = "text-block">Annotate lipid species detected by MALDI IMS analysis, and register MALDI IMS images to different types of microscopy images.</div><div class = "text-block">Expected Outcome:</div><div class = "text-block">A list of lipid identifications with low mass errors (<5 ppm) that correlate to ion images produced by MALDI IMS analysis, and the ability to layer different images from different assays.</div></div>

[STEPS]
?. [Data Processing]
Extract peak intensity from the calibrated dataset using one of the available options: 1a. Extract ion images based on an untargeted feature list that has not been narrowed down by the previous step. 1b. Extract ion images based on the identified feature list generated using the previous step. Note: In either case, narrow 3-5 m/z bin extraction windows are created for each selected peak and the ion images are generated. The width of the extraction window is important because if it is too wide, several poorly resolved ions can be captured within one ion image.
?. [Data Processing]
Calculate ppm error associated with common lipids, such as [PC(32:0)+H]+ and [PC(34:1)+H]+, for mass errors.  If mass error is above 3 ppm, re-calibrate.
?. [Data Processing]
If LC-MS/MS has been performed, annotate each m/z value against the LC-MS/MS list, otherwise move to 7.1
?. [Data Processing]
Perform peak picking on the mean mass spectrum and use LIPIDMAPS database to annotate each m/z value with the following search criteria:https://www.lipidmaps.org/resources/tools/bulk_structure_searches.php?database=COMP_DB1a. Positive Mode Adducts: [M+H]+, [M+H-H2O]+, [M+Na]+, [M+K]+1b. Negative Mode Adducts: [M+H]-, [M+Cl]-, [M+HCOO]-, [M+OAc]-2.   Specify Mass Tolerance: 0.005 m/z3.   Specify Chains: Even Chains Only4.   Sort: Delta
?. [Data Processing]
Calculate ppm error associated with each assignment and remove assignments with errors larger than 5 ppm, although most have errors lower than 3 ppm.
?. [Data Processing]
Convert Bruker (.d) raw file into a custom binary data format in profile mode at native spectral resolution.
?. [Data Processing]
Convert Bruker (.d) raw file into custom binary data format in profile mode at native spectral resolution.
?. [Data Processing]
Perform mass alignment and calibration of the dataset.
?. [Data Processing]
Spectral misalignment is estimated for each pixel and corrected using PCHIP interpolation or linear shift. Alignment is carried out using a Python msalign package (https://github.com/lukasz-migas/msalign). All spectra are first aligned based on automatically selected peaks and then recalibrated using at least three of the following well-characterized lipids: 1. Positive mode: m/z 703.5748, 734.5694, 760.5851, 810.6001. 2. Negative mode: m/z 673.4814, 744.5549, 834.5291, 885.5499.
?. [Data Processing]
Create a mean mass spectrum by taking the mean of each mass bin in the dataset.
?. [Data Processing]
Compute total ion current (TIC)-based normalization factors for each pixel after alignment and calibration.
?. [Data Processing]
Export the extracted peak intensities to a columnar CSV file by concatenating the x and y-coordinates from the registration step with the preselected ions in the form: x, y, m/z 1, m/z 2 … m/z N.
?. [Data Processing]
Read-in the table into Python and export the peak intensities to an imzML file using the Python pyimzML library (https://github.com/lukasz-migas/pyimzML).
?. [Image Alignment and Registration]
Generate a MALDI imaging mass spectrometry (IMS) pixel map using regToolboxMSRChttps://github.com/nhpatterson/regtoolboxmsrc
?. [Image Alignment and Registration]
Using FIJI ImageJ, select corresponding laser ablation marks and IMS pixels in the post-acquisition autofluorescence (post-AF) and IMS pixel map, respectively.https://fiji.sc
?. [Image Alignment and Registration]
Use a "Landmark Correspondences" FIJI plugin to find an affine transformation between the two images, resampling the post-AF image to the IMS pixel map by selecting post-AF image as source image, and IMS pixel map as the template image within the plugin.
?. [Image Alignment and Registration]
Save the post-AF image.
?. [Image Alignment and Registration]
Using wsireg (https://github.com/nhpatterson/wsireg) to align other microscopy modalities, such as CODEX multiplexed IF, preIMS AF, PAS or any other associated microscopy image, to the newly saved post-AF image. wsireg will generate pyramidal OME-TIFF images for all images after registration.
?. [Image Alignment and Registration]
When complete, all images will be sampled in the same coordinates as the IMS pixel map and IMS can be overlaid onto microscopy by scaling the IMS data to the same resolution as the microscopy data.
?. [Data Processing]
Perform mass alignment and calibration of the dataset. Spectral misalignment is estimated for each pixel and corrected using PCHIP interpolation or linear shift. Alignment is carried out using a Python msalign package (https://github.com/lukasz-migas/msalign). All spectra are first aligned based on automatically selected peaks and then recalibrated using at least three of the following well-characterized lipids: 1. Positive mode: m/z 703.5748, 734.5694, 760.5851, 810.6001. 2. Negative mode: m/z 673.4814, 744.5549, 834.5291, 885.5499.
?. [Data Processing]
Create a mean mass spectrum by taking the mean of each mass bin in the dataset.
?. [Data Processing]
Calculate ppm error associated with common lipids, such as [PC(32:0)+H]+ and [PC(34:1)+H]+.  If mass error is above 3 ppm, re-calibrate the entire dataset with additional well-characterized ions.
?. [Data Processing]
Compute total ion current (TIC)-based normalization factors for each pixel after alignment and calibration has been performed.
?. [Data Processing]
If LC-MS/MS has been performed, annotate each m/z value against the LC-MS/MS list, otherwise move to 6.1
?. [Data Processing]
Use LIPIDMAPS database to annotate each m/z value with the following search criteria:https://www.lipidmaps.org/resources/tools/bulk_structure_searches.php?database=COMP_DB1a. Positive Mode Adducts: [M+H]+, [M+H-H2O]+, [M+Na]+, [M+K]+1b. Negative Mode Adducts: [M+H]-, [M+Cl]-, [M+HCOO]-, [M+OAc]-2.   Specify Mass Tolerance: 0.005 m/z3.   Specify Chains: Even Chains Only4.   Sort: Delta
?. [Data Processing]
Calculate the ppm error associated with each assignment and remove assignments with errors larger than 5 ppm, although most have errors lower than 3 ppm.
?. [Data Processing]
Extract peak intensity from the calibrated dataset using one of the available options: 1. Extract ion images based on an untargeted feature list that has not been narrowed down by the previous step. 2. Extract ion images based on the identified feature list generated using the previous step.Note: In either case, narrow 3-5 m/z bin extraction windows are created for each selected peak and the ion images are generated. The width of the extraction window is important because if it is too wide, several poorly resolved ions can be captured within one ion image.
?. [Data Processing]
Export the extracted peak intensities to a columnar CSV file by concatenating the x and y-coordinates from the registration step with the preselected ions in the form: x, y, m/z 1, m/z 2 … m/z N.
?. [Data Processing]
Read-in the table into Python and export the peak intensities to an imzML file using the Python pyimzML library (https://github.com/lukasz-migas/pyimzML).
?. [Image Alignment and Registration]
Generate a MALDI imaging mass spectrometry pixel map using regToolboxMSRC (https://github.com/nhpatterson/regtoolboxmsrc).
?. [Image Alignment and Registration]
Using FIJI ImageJ, select corresponding laser ablation marks and IMS pixels in the post-acquisition autofluorescence image map and IMS pixel map, respectively.
?. [Image Alignment and Registration]
Use a "Landmark Correspondences" FIJI plugin to find an affine transformation between the two images, resampling the post-AF image to the IMS pixel map by selecting post-AF image as source image, and IMS pixel map as the template image within the plugin.
?. [Image Alignment and Registration]
Save the transformed and registered post-AF image.
?. [Image Alignment and Registration]
Using wsireg (https://github.com/nhpatterson/wsireg) to align other microscopy modalities, such as CODEX multiplexed IF, preIMS AF, PAS or any other associated microscopy image, to the newly saved post-AF image. wsireg will generate pyramidal OME-TIFF images for all images after registration.
?. [Image Alignment and Registration]
When complete, all images will be sampled in the same coordinates as the IMS pixel map and IMS can be overlaid onto microscopy by scaling the IMS data to the same resolution as the microscopy data.