MSMLSDiscovery™ Software Manual

Introduction

MSMLSDiscovery™ is a software tool designed to streamline and simplify the tedious process of building authentic standard libraries for mass spectrometry. The program is tailored to work with the Mass Spectrometry Metabolite Library of Standards (MSMLS) distributed by IROA technologies. Future releases will allow for user-specified lists of compounds not restricted to MSMLS.

The layout of the software user interface is rather intuitive and the first section of this manual will concentrate on the recommended worfklow. This is followed by detailed descriptions of the user interface to help clarify the possible questions and explain options not previously mentioned.

MSMLSDiscovery user guide video can be used for additional instructions for operating the program. The video can be accessed using this link:

MSMLSDiscovery User Guide or by entering this address:

http://www.anymeeting.com/wyhfnkefitp/E151DC878346

Definitions

Note: the definitions below are intended to avoid misunderstanding and ambiguity within the scope of this manual only.

Experimental sample – solution of one or more compounds intended to be analyzed within a single LC-MS/LC-MSMS run; each sample may be analyzed by more than one chromatographic/MS method combination. Currently MSMLSDiscovery does not support mixed polarity files.

Multiplex plate – individual plate from the Mass Spectrometry Metabolite Library. The library is distributed in 96-well plate format together with a plate map specifying the location (plate number, row, and column) of each single authentic standard. Compound identifiers and descriptors such as CAS numbers are provided.  Please refer to the MSMLS product information sheet for further information.

NOTE: The plate map contain descriptors and represents information gathered from multiple databases. We work to ensure the accuracy of the data but due to the volume of data there may be errors.

Experiment design – library construction involves analysis of multiple mixtures of authentic standards, possibly by more than one LC-MS / LC-MSMS method. Experiment design is a definition of relationship between experimental samples, raw data files and analytical methods. It determines which samples contain which authentic standards and which raw data files correspond to analysis of specific samples by a specific method.

Starting the Program for the First Time

Installation of the software requires administrative privileges on the computer you wish to install it on. The installer will by default install and register the software, and leave a shortcut on the desktop.

To execute this software package, there are three links/folders that you need to be aware of:

  1. The first is the shortcut to the MSMLSDiscovery software itself that was placed on your desktop during the installation of the software.
  2. The second is a folder which you will create and where the project is stored so you may return to it at any time. As you will learn, a complete copy of the raw data files is saved within the project, as are the preferences and libraries you have extracted.
  3. The third is a folder where the data are stored.  All raw data files should be exported as Centroided data files. These are smaller and will process faster and more accurately.

The requirements of the program are that:

  1. The most recent version of Java 8 must be installed and callable
  2. The computer should have at least 8GB of RAM
  3. You are running Windows 7 or higher

When you start the program on your computer for the first time it will prompt you to specify the home directory – the place where it will save the projects by default and where it will look for the existing projects to open. Please consider the free disk space on your computer carefully when making this decision since projects will include copies of raw data files and may take considerable space. Projects may be created/copied/moved to any directory of your choice and default directory location may be changed at any time by editing program preferences.

Standard Workflow

The standard software workflow for creating a new compound library includes the following steps:

  • Creating new project
  • Creating experimental samples
  • Defining composition of each experimental sample (which authentic standards it contains)
  • Importing raw data for one or more LC-MS analysis methods
  • Associating samples with corresponding data files
  • Performing compound search
  • Curating search results
  • Exporting library data for use in subsequent experiments

User may interrupt the work at any stage and return to analysis at a later date.

Note: a complete copy of the raw data files are saved within the project, as are the preferences and libraries you have extracted.

Starting the program

The program is started by double clicking on the MSMLSDiscovery application (.exe) icon. The Installer will guide you through installation of the software on your computer. To proceed click “Next”. The Installer will ask if you wish to install this application for the current user only or anyone who uses the computer. Select one and click “Next”. Register the file extensions and click “Next”.

The installer will then ask where you would like the MSMLSDiscovery program file components to be installed. Select a destination folder and then click “Next”. The installer then identifies the program folder to which the program icons should be added. You can either type a new folder name or select one from the list of existing folders and then click “Next”. Now select any shortcuts you want to create and click “Next”. The installer is now ready to install MSMLS on your computer, click “Next”. All components will be copied to your computer, click “Finish” to complete. Locate the program in your computer’s program files under “IROAtech”. At this point you may wish to create a desktop shortcut (right click on “IROAtech” file and select “create shortcut”). A shortcut will now be visible on your desktop. Click on the application icon to start program.

The first time the MSMLSDiscovery program is run on your computer, it will ask you to:

  1. locate the folder you will use to store your projects (use a folder anywhere you wish on your computer)
  2. provide a user name and email address.

Thereafter these bits will be retained and it will not need to ask you again. (Should you need or wish to change them in the future, these identifiers are accessible through the Preferences dialogue box).

Creating a New Library Generation Project:

At program startup the user is presented a window which allows the creation of a new project or to open an existing one (Figure 1).  Specify the name and email address.

To initiate new project click “Create new project” button () which will bring up the first page of a New Project Wizard (Figure 2).

Figure 1.

Startup Task Chooser

Startup Task Chooser

Figure 2.

Project Set-up Wizard - Project Definition

Project Set-up Wizard - Project Definition

Under Project class, select “Library generation”. Specify the Project name and description of the experiment, change the project home directory if required, and click the “Next” button to move to the method definition screen (Figure 3)

 

Figure 3.

Project Setup - Method Definition

Project Setup - Method Definition

Specify Method name, Method description, Method polarity and MS depth for each analysis method used to collect raw data. Use “Add method” button to add specified method to the project (it will show up in the “Defined methods” table as seen in figure 3). Method information may be edited, along with adding new and deleting existing methods later. When finished click “Next” to move to sample definition (Experiment design) screen (Figure 4).

 

Figure 4.

Project setup – sample definition

Project setup – sample definition

For the sake of simplicity sample definition in wizard is limited to specifying the sample name prefix and number of multiplex samples. Once complete click on “Finish and close wizard”.

Creating Experimental Samples

When you clicked on “finish and close wizard” it should take you to the “multiplex designer” page. The experimental design definition is completed using the tools on the “Multiplex designer” panel (Figure 5).

The samples you created will be listed in the “Multiplex samples” table (Figure 5B). Next you must identify the Mass Spectrometry Library which was used to create the data files. Click the “Edit program preferences” button ()on the window toolbar and select the “Create Library” tab.

From the pull-down menu associated with MSMLS Library, select the correct library. If you are not sure which library version you have, contact your supplier or use your plate map (provided to you at time of purchase) to verify compounds in the “Selected sample composition” (window “C”, see next paragraph for further information on how to activate window.)

After selecting the correct library, click on the () button to apply changes.

Figure 5.

Multiplex Designer Panel Overview

Multiplex Designer Panel Overview

The samples created will be listed in the “Multiplex samples” table (Figure 5B). To associate the sample with authentic standard it contains, highlight the sample in the table then select desired standards in the “Compound plate map” table below and click “Add selected compounds to sample” button () on the toolbar at the top of the compound plate map window. Selected compounds will be linked to the sample and show up in the “Selected sample composition” table in the upper right part of the window (Figure 5C).

Figure 6

Plate Map Table

Plate Map Table

There are two ways to select compounds – using the plate map table (Figure 6) or using the plate compound table (Figure 7). Both tables are located in the lower middle portion of the multiplex designer window (Figure 5D) and user may switch between them by clicking the appropriate tab.

 

Figure 7.

Plate Compound Table

Plate Compound Table

The plate map table mimics the layout of the 96-well plate used to supply MSMLS. Individual compounds are selected by marking the corresponding checkboxes, or entire rows by marking the checkboxes in the first column. The tooltip will display the compound name when you point the mouse to a particular table cell; clicking inside the cell will bring up the compound structure and other information in the lower right portion of the window (Figure 5E).

The plate compound table (Figure 7) allows single row selection only, clicking on each row also brings up the selected compound structure and details. To add the selected compounds click on the button.

To switch between different multiplex plates use the “Plate” dropdown menu at the top of the compound plate map window (Figure 5D).

Importing Raw Data

To import raw data click the “Load raw data” bar of the accordion panel (Figure 5A) to open the data import panel (Figure 8).

If more than one analytical method has been defined for the current project, select the corresponding tab of the panel and load the files by drag-and-drop on the “Filename” portion of the table or by clicking “Add raw data files” button () on a panel toolbar and navigating to the directory containing the raw data. During file import the “Task monitor” section is activated to show operation progress (Figure 9).

 

Figure 8.

Load Raw Data Panel

Load Raw Data Panel

 

Figure 9.

Task Monitor Panel

Task Monitor Panel

Associating Samples with Corresponding Data Files

After importing the raw data files it is necessary to assign them to the corresponding samples to let the software know which compounds to look up in which data file. This is done by choosing the files from the dropdown menus in a “Sample to data files map” (Figure 10). Click the “Assign files to samples” bar in the accordion plate (Figure 5A) to display the mapping table.

 

Figure 10.

Samples to Raw Data Files Mapping Table

Samples to Raw Data Files Mapping Table

Specify Search Parameters

After file assignment is completed you are ready to specify search parameters and run the search. To examine and modify the search parameters open the “Preferences” window by clicking “Edit program preferences” button () on the window toolbar and switch to “Find library compounds” tab (Figure 11).

 

Figure 11.

Compound Library Search Preferences Panel

Compound Library Search Preferences Panel

Most of the parameter names are self-explanatory, except smoothing width, which is specified as a fraction of the total run time (duration of chromatographic separation in LC-MS). It also should be noted that minimum peak intensity filter is applied to the highest (usually monoisotopic) peak of the adduct, not to any mass peak in general.

Performing Compound Search

After search parameters are specified you may start the search by clicking “Find library compounds” button () on the window toolbar. The button is available both on “Multiplex designer” and “Data analysis” panels. When the “Find library compounds” button is selected you will be asked “Are you sure you want to discard existing search results?” Select “yes”. The view will switch to “Data analysis” panel and task monitor window will appear to show the progress of the search. The program will search for compounds, fragments and adducts.

Masses of adducts are calculated in the following way:

  1. From the molecular formula of the free compound in neutral form (when no innate charge is present like in choline), calculate number of atoms for each element; take into account whether adduct is a monomer, dimer, etc.
  2. Calculate the numbers of atoms added when adduct is formed (e.g., if adduct is with formate (HCOO-), then 1 hydrogen, 1 carbon and two oxygens are added to the element counts obtained from the free compound on step 1).
  3. Calculate the numbers of atoms lost (e.g., if there is a water loss subtract 2 hydrogens and 1 oxygen from the total counts for respective elements obtained in step 2); at this stage the software checks if the loss is possible (total count for the element can’t be negative after the loss. If it is, the adduct is not created); if there is no loss this step is omitted.
  4. Calculate the mass of adduct as a neutral molecule based on the element count from step 3.
  5. Correct the mass from step 4 for the charge by adding/subtracting the mass of the electron multiplied by the charge and then dividing by the charge, this is the expected M/Z.

Curating Search Results

Once the search is completed results are displayed in a tree format and are ready for curation (Figure 12A).

 

Figure 12.

Data Analysis Panel

Data Analysis Panel

By default all compounds found in data files for all analytical modes are listed in the alphabetical order. Compound names are color coded (red for positive mode, blue – for negative). The icon of the compound indicates whether it was detected or not (green tick mark () for detected, warning sign () for not detected). Clicking on the compound in the tree will bring up the following information in the corresponding panels:

  • Extracted ion chromatograms for base peaks of the detected adduct(s) - Figure 12B
  • Mass spectrum in a table format with mass and relative intensity errors comparative to theoretical values - Figure 12C
  • MSMS (M/Z and intensity values table) – if available for any of the MS1 adduct base peaks - Figure 12C, “MS2 scan data” tab
  • Average mass spectrum plot (MS1) across the compound peak and detected adduct(s) mass spectrum plot - Figure 12D
  • MSMS plot, if data available for MSMS - Figure 12E

“Method” drop down menu in the window toolbar allows to switch feature list for individual analytical methods (e.g. show only positive mode or only negative) or display all the features in a single list.

Exporting Library for Use in Subsequent Research Experiments

After the data curation process is completed the library may be exported in tab delimited (TSV, plain text) format or Chemical Exchange Format (CEF, developed by Agilent Technologies, XML-based). Export is possible only for all analytical modes simultaneously and data can be saved separately for each method (recommended) or coming for all methods.

To export the library click “Export compound library” button () which will bring up a new window with a toolbar allowing users to choose the export format - tab-delimited or CEF. Location defaults to the “Libraries” folder within current project folder. 

To combine and export combined libraries, click on the “Show Library Merging Panel” button, under the multiplex design tab. The “Merge Existing Libraries” window presents with a panel of icons on the top left side.  Here the user can:

  1. Append libraries ()
  2. Remove appended libraries ()
  3. Eport Library ()
  4. Export filtered libraries ()

Libraries can be imported into different software programs or used in other independent library search products, for example, Agilent’s “Personal Compound Database Library” (PCD). Libraries can also be used directly in the MSMLSDiscovery software program to analyze samples.  See next section titles “Sample Analysis” to analyze your samples.  Libraries can also be directly imported into IROA ClusterFinder™ software program for metabolomic profiling.

Close the program and the entire project is saved, which can be opened up at any time.

Sample Analysis

Now that you have built the library using the MSMLS authentic compounds and MSMLSDiscovery software, they may now be used for sample analysis.

Locate the saved libraries generated in the previous section. Libraries will be in either Chemical Exchange Format (CEF) or tab-delimited (TSV, plain text) format.

Initiating a Sample Analysis Project - To begin sample analysis, either open the program again or to initiate a new project by clicking “Create new project” button () which will bring up the first page of a New Project Wizard (Figure 13).

 

Figure 13.

Startup task chooser

Startup task chooser

On the “Project selection screen” (Figure 14), specify Project class by using the arrow to select “Sample analysis”. Specify the Project name and description of the experiment, change the project home directory if required and click the “Next” button to move to the “Method definition” screen (Figure 15).

 

Figure 14.

Project Selection

Project Selection

 

Figure 15.

Project setup – Method definition

Project setup – Method definition

On the method definition screen, specify Method name, Method description, Method polarity, and MS depth for each analysis method you have used to collect the raw data of the samples you wish to analyze. Use “Add method” button to add specified method(s) to the project (it will show up in the “Defined methods” table). You may edit method information, add new methods and delete existing methods later as well. When finished click “Next” to move to the sample definition screen (Figure 16).

 

Figure 16.

Experiment design – sample definition

Experiment design – sample definition

On the experimental design screen, specify the number of samples and the sample name prefix. Sample names can be modified on the next screen after you select “Finish and close wizard”.

A new screen will come up, when “Finish and close wizard” has been selected. Choose the Assign files to samples bar (Figure 17).

 

Figure 17.

Assign files to samples

Assign files to samples

Upon selecting the Assign files to samples bar, you will be brought to the Assign files to samples screen (Figure 18), you can modify the sample name by clicking on the name and selecting the Load raw data tab.

 

Figure 18.

Assign files to samples screen

Assign files to samples screen

Modify sample names as desired by clicking on the name and select the Load raw data tab (Figure 19).

 

Figure 19.

Load raw data screen

Load raw data screen

Load data by clicking “Add raw data files” button () on the panel toolbar and navigating to the directory containing the raw data. Be sure to load Centroided mxXML files. During the file import the Task monitor section is activated to show the data load progress (Figure 20). Click on each method and repeat to add all data files for each acquisition method.

 

Figure 20.

Data Monitoring Screen

Data Monitoring Screen

After importing the raw data files, assign the files to their corresponding samples by selecting the “Assign files to samples tab” and choosing the files from the dropdown menus for each of the defined methods (Figure 21).

 

Figure 21.

Assign files to samples

Assign files to samples

Load Compound Libraries Created During Library Generation:

Select the Load compound library button () to select and load the compound libraries that were created in the library generation using the MSMLS kit (Figure 22).

 

Figure 22.

Load Compound Libraries

Load Compound Libraries

Once the libraries have been selected click on the “Load selected libraries” button.

Click on () to specify the search parameters. Most of the parameter names are self-explanatory, except smoothing width, which is specified as a fraction of the total run time (duration of chromatographic separation in LC‑MS). It also should be noted that minimum peak intensity filter is applied to the highest (usually monoisotopic) peak of the adduct, not to any mass peak in general.

After search parameters are specified you may start the search by clicking “Find library compounds” () button on the window toolbar. The button is available both on the “Multiplex designer” and “Data analysis” panels. When the “Find library compounds” button is selected you will be asked “Are you sure you want to discard existing search results?” Select “yes”. The view will switch to “Data analysis” panel and the task monitor window will appear to show the progress of the search. Once the search has been completed the results will be displayed in a tree format (Figure 23).

 

Figure 23.

Data Analysis Panel

Data Analysis Panel

Results can be exported by clicking on the “Export results” () button on the window toolbar. This will produce a “Save file” dialog prompting for the destination of the file with quantitative data for every detected library compound in every sample analyzed (Figure 24). Provide a filename for the project and click “open”.

 

Figure 24.

Set results export file

Set results export file

We hope the MSMLSDiscovery program is useful and welcome any feedback. Please send your comments and suggestions to info@irotach.com.

 

MSMLS, MSMLSDiscovery, and ClusterFinder are trademarks of IROA Technologies, LLC.