OpenMSI Arrayed Analysis Toolkit: Analyzing spatially defined samples in mass spectrometry imaging

Transcription

1 OpenMSI Arrayed Analysis Toolkit: Analyzing spatially defined samples in mass spectrometry imaging Introduction This is the accompanying notebook of the manuscript OpenMSI Arrayed Analysis Toolkit: Analyzing spatially defined samples in mass spectrometry imaging (link to manuscript) in Analytical Chemistry, volume x, issue y, pages a-z. This tutorial notebook will demonstrate the basic features of OMAAT, with step by step guidance on how to run the Jupyter Notebook. A normal version, without the turtorial markdown, is also available (OMAAT (link to notebook in reposetory)). Furthermore, a version showcasing advanced capabilities and no mardown is also available (OMAAT_advanced ( OMAAT requires Jupyter version 4.1+ and Python version 2.7+ or Further information on Jupyter and Python instalation can be found in the [README] ( file For this tutorial, an OpenMSI account is **not** required. However, in order to analysis the users' own files, an OpenMSI account is required. An OpenMSI account can be obtained through the OpenMSI team and NERSC ( at no cost Users don't have to provide a MSI data file. For this tutorial, we have selected the usage of the _nimzyme ( file=%2fproject%2fprojectdirs%2fopenmsi%2fomsi_data_private%2fbpb%2f _nimzyme.h5&dataind MSI data set (as used in the manuscript (link to paper), which is publicly available. How to use this Jupyter Notebook An interactive demo for new users of Jupyter/iPython notebooks can be found at Nature ( In this tutorial, there are 2 types of content, namely text and code. This content is placed in boxes called "cells". If you click around on this page, you'll see different cells highlighted. To execute each cell (regardless of content), you hit on your keyboard SHIFT+ENTER or press the play button. If the cell contains text, the content will be displayed directly. If the cell contains code, the code will be executed. Cell 1. Loading Arrayed Analysis Tool Execute the cell below to load the OpenMSI Arrayed Analysis Toolkit. It should load in about 15 seconds --When succesful, the message "Completed loading OpenMSI Arrayed Analysis Toolkit" will appear-- file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 1/13

2 In [1]: import omaat_lib as omaat %matplotlib notebook /Users/markus_de_raad/anaconda/lib/python2.7/site-packages/IPython/kern el/ init.py:13: ShimWarning: The `IPython.kernel` package has been d eprecated. You should import from ipykernel or jupyter_client instead. "You should import from ipykernel or jupyter_client instead.", ShimWa rning) Cell 2. Log into OpenMSI --Log in is not required for this tutorial and this cell can be skipped. However, in order to analysis the users' own files, logging into OpenMSI is required-- Execute the cell below. When the cell is executed, the user is asked to put in their NERSC/OpenMSI username. After entering their username, the user is asked to put in their NERSC/OpenMSI password. --If login is succesful, the message "Login appears to be successful!" will appear-- In [2]: openmsisession = omaat.login() Password for user "" was likely wrong, re-run this cell to try again file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 2/13

3 Cell 3. File and ion selection After a successful login, executing the file selector cell will prompt a list of the users available OpenMSI files. --If not logged into OpenMSI, only the publicly available OpenMSI files will be displayed, including the file used in this tutorial-- Next, select the file ' _nimzyme' by clicking on the file name. Then, put in the corresponding Experiment Index and Data Index to the file you want to analysie. For this tutorial, put in '0' for both indexes. Next, provide the m/z values of the ions for analysis. Insert the m/z value in the 'Add an ion' box, and click the 'Add Ion" button. The value will appear in the box 'Select which ions you want to load'. For the tutorial, add the following m/z values: , , , and Ions can be removed be first clicking on the m/z value in the 'Select which ions you want to load' box and then on the 'Remove Ion' button. Then, put in the value for the integrate at +/- this amount of the inserted m/z values. Users can choose between 'absolute m/z values' or '% of m/z'. For this tutorial select the 'absolute m/z values' and set it at 0.2. Next, a mass range reduction strategy can be selected. Users can choose between 'Sum of all data points in mass range (i.e., area under the curve)', 'Max data point in range (i.e. peak height)' or 'n data points around the max'. For this tutorial select the 'Max data point in range (i.e. peak height)'. Last, using the given parameters, a base image has to generated. To do this, the user has to click on the 'Load Image!' button. --After clicking on the 'Load Image!' button, the line "Loading image... " will appear. The progress of loading the separate ions will be displayed, in the form of "loading ion 1 of x. m/z = x"-- --When loading has completed, the message "Image has been loaded." will appear-- In [3]: if "openmsisession" not in locals(): openmsisession=omaat.openmsisession() openmsisession.imageloader_with_dialogs() #once loaded the image will be stored in the "img" variable Loading image... loading ion 1 of 4. m/z = / Time to load ion: seconds loading ion 2 of 4. m/z = / Time to load ion: seconds loading ion 3 of 4. m/z = / Time to load ion: seconds loading ion 4 of 4. m/z = / Time to load ion: seconds Image has been loaded. file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 3/13

4 Cell 4. Display base image In order to display the generated base image, execute the cell below. The base image will be displayed below. The base image is the ion-intensity vizualization of all selected ions and will be used for mask placement. In [4]: from matplotlib import pyplot as plt import numpy as np Zzoom=1 #set this to a higher number to see a narrower range of values (useful if one pixel is way brighter than the rest) plt.figure(num = 'Base Image') plt.imshow(openmsisession.img.baseimage,cmap='gray',clim=(0.0,np.amax(op enmsisession.img.baseimage)/zzoom)) plt.colorbar() # putwindowontop() plt.show() file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 4/13

5 Cell 5. Placing trapezoidal mask By executing the cell below, a trapezoidal mask containing individual markers will be generated. The size of the trapezoid and the number of markers is determined by number of rows and columns. For this tutorial, generate a trapezoid with 16 rows and 24 columns and a Hexagonal Offset of 0. When the cell is executed, the base image with the trapezoidal mask will be displayed below. Then, the trapezoidal mask is roughly placed over the arryaed samples; optimization of positioning of the individual markers will be performed in the next cells. The mask can be moved by dragging the corner markers of the trapezoid (highlighted with red halos) to the prefered position. For this tutorial, place the trapezoidal mask by dragging the corner markers of the trapezoid to the corner samples. Since the top right corner doesn't contain samples, roughly position the top right marker so that the top row and right column markers allign with the samples. The Hexagonal Offset, which can be a decimal number, moves every other row that many spots to the right. If you want a traditional hexagonally tiled mask, set the Hexagonal Offset to 0.5 to move every other row to the right, or set it to -0.5 to move every other row to the left. file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 5/13

6 In [5]: openmsisession.img.roughposition_with_dialogs() Number of columns? leave blank for default ("24") 24 Number of rows? leave blank for default ("16") 16 Hexagonal Offset? This shifts every other line by this many spots. leav e blank for default (" ") 0 file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 6/13

7 Cell 6. Automatic spot optimization In the next cell, the Jupyter notebook will optimze the marker position. For detials on the optimization algorithm, see the method section in the manuscript (link to paper). For this tutorial, perform the automatic spot optimization. First, put in the integration radius for the individual markers in the mask. For the tutorial, put in 2. Then, put in the number of rounds of optimization. For this tutorial, put in 3. Next, put in the number of pixels how far away from the current location should the algorithm searches. For this tutorial, put in 2. Then, if you don't want that the markers will overlap after optimalization, check the box. For this tutorial, check the box. Next, give weighting values for each ion. For this tutorial, put in 1 for all ions. You can calculate the scores for the current marker locations, by clicking on the 'Calculate scores for current spot locations' button. For this tutorial, you can skip this step. Then, put in the minimum score necessary to move a marker. For this tutorial, put in 1. Last, using the given parameters, the marker position can be optimized. To do this, the user has to click on the 'Optimize Spots!' button. --After clicking on the button, the progress of the optimization will be displayed. When optimization is completed, the message "optimization routine completed. new spot x and y positions saved." will appear-- --Performing the spot optimization is optional. Individual markers can be positioned manually in the cell 'Displaying optimized marker(s) positioning'-- In [6]: #automagically optimize the spot centers to correspond to the actual spo ts on the image openmsisession.img.optimizespots_with_dialogs() done with optimization round 1 of 3 done with optimization round 2 of 3 done with optimization round 3 of 3 optimization routine completed. new spot x and y positions saved. file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 7/13

8 Cell 7. Displaying and finetuning optimized marker positioning In order to view the optimized marker postioning, execute the cell below. The base image will be displayed below. Individual markers can be moved by dragging the markers to the preferred postion. The radius of the circular spot markers in this tool is not necessarily the same as your actual integration radius, though we have tried our best to make it a reasonable approximation. Use the "Calculating spot areas" cell below to see the shapes of your actual calculated spots. If no automatic spot optimization was performed, the trapezoidal mask will be at same postion as it was. Still, individual markers can be moved by dragging the markers to the preferred postion. In [7]: #check the positions of the spots and manually adjust them if need be radius=omaat.get_default_params()['arrayed_analysis_radius'] openmsisession.img.finetuneposition(markerradius=radius,colormap='gray',m ercolor='blue') file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 8/13

9 Cell 8. Saving Arrayed Image If needed, the arrayed image, including the coordinates of the spots, can be stored in a 'pickle' file. First, enter a name between the parentheses, replacing name_pickle_file. Then execute the cell to save the file. --For this tutorial, saving the mask position is optional-- In [ ]: #Optional: Save the ArrayedImage into a pickle file. filename="filename.arrayed_img" import pickle pickle.dump(openmsisession.img, open(filename,"wb")) print("done saving.") Cell 9. Loading saved mask position Saved arrayed images can be loaded from a pickle file. Enter the name of the saved pickle file between the parentheses, replacing name_saved_pickle_file. Then, execute the cell to load the file. --For this tutorial, this step is optional-- In [ ]: #Optional: Load an ArrayedImage from a pickle file. This way you can wor k off-line filename="filename.arrayed_img" import pickle img=pickle.load(open(filename,"rb")) print(img) Cell 10. Calculating the spot areas, and final inspection Execute the cell below, to calculate which pixels belong to which spot. The integration radius of the markers can be adjusted, but if you leave it as-is, the same number you used in the optimization stage will be used. A visual representation of the marker size and positioning will be genreated for visiual inspection. --The message "x spots generated. number of spots with N pixels:{x: x, x: x}" will appear--_ file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 9/13

10 In [8]: #You'll need to call this function. It returns a list of spots (where ea ch spot is a list of pixels), #which is also stored inside the object. # line 536 # see if default_params overwrites parameters specified as kwargs radius = omaat.get_default_params()['arrayed_analysis_radius'] #this is the same integration radius that you set in the optimization st ep spots=openmsisession.img.generatespotlist(integrationradius=radius) openmsisession.img.showmaskedimage(spotlist=spots,alpharows=true) 384 spots generated. number of spots with N pixels:{10: 2, 11: 17, 12: 61, 13: 250, 14: 54} Cell 11. Exporting results into a comma-separated text file The next cell is used to save the results of the arrayed analysis tool as a table into a.csv file. It will name the file after the current date and time, but if you want to give the file a specific name, enter the name between the quotes after filename=. The file will be a comma-separated file (.csv file) which you could open in Excel to do further data anlysis. file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 10/13

11 In [ ]: #Write results to a file #if you don't pass it an explicit spotlist it will use the spot set stor ed in the ArrayedImage filename="" #If you want a specific filename, enter it here..csv exten sion will be automatically added openmsisession.img.writeresulttable(filename=filename,alpharows=true) Cell 12. Using pandas to perform programmatic data analysis If you prefer to use Pandas over Excel to do data analysis, the resultsdataframe method returns a Pandas dataframe with the same kind of information that the writeresulttable method gives. In this example, we compute the first ion as a percentage of all ions loaded, and plot those percentages, from small to large, using matplotlib. In [ ]: df=openmsisession.img.resultsdataframe(minpixelintensity=0,alpharows=tru e) #generate the dataframe # IPython.display.display(df) sums_df=df.loc[:,(slice(none),'sum')] #get the sums from the dataframe sums_df.columns = sums_df.columns.get_level_values(0) #name the columns to make indexing easier later percentage_firstion=100.0*sums_df[openmsisession.img.ions[0]]/sums_df.su m(axis=1) #calculate the percentage percentage_firstion.sort() #rank the data from low to high. Using sort() instead of sort_values(inplace=true) for backward compatibility plt.figure() plt.bar(range(len(percentage_firstion)),percentage_firstion,edgecolor='b' #define a bar chart plt.xlabel('spot rank') #set x axis label plt.ylabel("% m/z={:.1f} of all loaded ions".format(openmsisession.img.i ons[0])) #set y axis label plt.xlim(0,len(percentage_firstion)-1) #set x axis range plt.show() df Cell 13. Viewing and manipulating spot spectra You can request the average spectra for your spots from the OpenMSI server. The toolkit can return the spectral data as a dataframe, which makes plotting straight-forward Quite a lot of data needs to be transferred between the server and this script, so allow some time for this example to run file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 11/13

12 In [ ]: spectra_df=openmsisession.getspotspectra(openmsisession.img,verbose=true) #Loads the spectra from the OpenMSI server #It's lot of data, so save the desulting dataframe #so that you dont have to run this method repeatedly. A01_spectrum=spectra_df["A01"] # get only the spectrum for the spot at l ocation A01 A01_spectrum.plot() #plot the entire spectrum for spot A01 plt.figure() plt.xlabel("m/z") plt.ylabel("intensity") plt.show() A01_spectrum[900:1950].plot() #plot only the m/z values between 900 and 1200 plt.xlabel("m/z") plt.ylabel("intensity") plt.show() spectra_df.plot() # plot ALL the spectra that are loaded on top of each other. #Depending on how many spots are in your image, this c an be #a LOT of data, if you don't have a good computer this might crash. plt.xlabel("m/z") plt.ylabel("intensity") plt.show() file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 12/13

13 file:///users/markus_de_raad/downloads/analchem_2016_deraad.html 13/13