Merge pull request #78 from alan-jarmusch/master

adding documentation for MSMS-Chooser

docs/msmschooser.md

@@ -0,0 +1,106 @@
+# Open-source Protocol for Community-created Public MS/MS Reference Library (MSMS-Chooser)
+
+## Summary
+[MSMS-Chooser](https://proteomics2.ucsd.edu/ProteoSAFe/index.jsp?params=%7B%22workflow%22:%22MS-CHOOSER%22%7D) is a GNPS workflow and open-source protocol to empower the community to collect MS/MS reference data and contribute to the public MS/MS reference library.
+
+**This is a community effort and welcome everyone to participate!**
+  * We encourage individuals to implement the protocols in their own laboratory.
+  * Individuals with chemical standards without access to instrumentation are encouraged to contact the Dorrestein lab to inquire about running standards in collaboration (see contact information below).
+
+## Requirements for MSMS-Chooser Workflow and Subsequent Addition of Spectra to the GNPS Library
+  * Complete MSMS-Chooser Template
+  * Data containing MS/MS data convereted to open-file formats (.mzXML or .mzML)
+  * Validation of MSMS-Chooser output (using drag-and-drop validator) + visual inspection of MS/MS spectra
+  * Email contacting Dorrestein Lab with task ID (see contact information below)
+
+## Step-by-Step Instructions
+
+### Completion of [MSMS-Chooser Template](https://docs.google.com/spreadsheets/d/1C6bpcaC2b4KpXaimkpslH4whlqKlN4T9DB-BKNYshjQ/edit?usp=sharing)
+1. Make a copy of the **MSMS-Chooser Template** by selecting “File” and then “Make a copy” - continue working in Google Sheets
+2. Fill out the MSMS-Chooser Template in the **"MSMS-Chooser Template"** tab
+    * A readme tab is included that describes what should be entered as well as an example and additional information is in documentation (GitHub). ** Important: You must record the position of each chemical in the 96-well plate. **
+    * Only columns H-Q need to be complete if submitting samples to Dorrestein Lab - approval required before submitting samples.
+    * **Please complete one row for each chemical in the positive mode and then copy and paste rows below and update the “IONMODE” column from “Positive” to “Negative”.
+3. Download a copy of the **MSMS-Chooser Submission** tab.
+    * The MSMS-Chooser File required for submission is automatically generated in the "MSMS-Chooser Submission" tab
+4. Download a copy of the applicable Sequence Table using the **Sequence Table Generator** tab as a .csv from Google Sheets.
+  * Please double check the chemicals and well position match in the sequence table.
+
+### Sample Preparation - List of Required Materials
+  * HPLC grade solvents in all sample preparation steps (highly encouraged)
+  * 96-well plates and corresponding well plate covers (autosampler compatible)
+
+| Manufacturer | Item Number | Item | Recommended Pairing |
+|:------------- |:-------------:|:-----:|:------:|
+| Eppendorf       | 951040048 | Microplate 96/U-PP with white border | 1 |
+|-|-|-| 1 |
+| Thermo Scientific | 12565368 | Microplate U96 PP-0.5ml, natural | 2 |
+| Thermo Scientific | 12565560 | 96 well cap, natural | 2 |
+
+### Sample Preparation - Protocol
+1. Generate a solution of your sample (standard) at a concentration of 10 µM.
+2. Transfer 10 µL of your sample (standard) into a well in the 96 well plate recording the well position and chemical added.
+    * One sample should be added per well
+3. Repeat transfer of 10 µL into wells
+4. Record plate number, well position, etc. in the sample submission template.
+5. Once all standards have been added to the 96-well plate, completely dry all solutions.
+    * Evaporation of the liquid can be done using the following techniques:
+      * Nitrogen gas evaporation.
+      * Low pressure evaporation system (Centrivap systems are recommended)
+6. Seal plate using the previously mentioned 96 Well plate cover. 
+    * Important: The material in the plate must be dry.
+7. Store plate at -20 °C prior to shipping.
+
+### Data Acqusition 
+Please select the following link:
+
+| Vendor | Instrument | Version | Revision Date| Method Files|
+|:---:|:---:|:---:|:---:|:---:|
+|Thermo|[QExactive](msmschooserdataacquisitionQE.md)|v1.0|Sept 4, 2019| [Link](massive_link_here)|
+|-|-|-|-|-|
+|-|-|-|-|-|
+
+
+### Post-Data Acqusition 
+1. It is recommended to completely dry all solutions.
+    * Evaporation of the liquid can be done using the following techniques:
+      * Nitrogen gas evaporation.
+      * Low pressure evaporation system (Centrivap systems are recommended)
+2. Place plates into a -20C freezer
+3. Convert raw data to .mzXML
+
+| Vendor | Instrument | Recommended Software| Settings |
+|:---:|:---:|:---:|:---:|
+|Thermo|QExactive|[MSconvert](http://proteowizard.sourceforge.net/tools.shtml)| mzXML and binary encoding precision as 32-bit|
+|-|-|-|-|
+|-|-|-|-|
+
+4. Create a GNPS/MassIVE Dataset
+  * Upload the files to your GNPS account using an FTP client (preferred clients are WinSCP, CoreFTP, and CoffeeCup Free FTP)
+  * Name the MassIVE data set using the following format: “GNPS - Chemical Standard to GNPS Library - [insert barcodes]”
+  * Upload all .raw files into the RAW folder and all .mzXML files into the PEAKS folder
+  * Upload the **MSMS-CHOOSER Submission** file (.tsv) from the NAS folder, download as .tsv, place in SUPPLEMENTAL folder
+  * Make data public
+
+### MSMS-Chooser (v1.0)
+1. Navigate to [ProteoSAFe](https://proteomics2.ucsd.edu/ProteoSAFe/index.jsp?params=%7B%22workflow%22:%22MS-CHOOSER%22%7D).
+  * Select all .mzXML files, negative and positive, from MassIVE
+  * Select the **"MSMS-Chooser Submission"** file (.tsv) from MassIVE
+2. Launch the Job
+3. Download result file and test using the following [Validator](http://dorresteinappshub.ucsd.edu:5020/).
+4. Send completed Job Link to Contacts (detailed below)
+
+## Contacts
+Morgan Panitchpakdi([email protected]) and Mingxun Wang ([email protected])
+
+## Data Availability
+All public MS/MS spectra are avaliable for download and browsing in GNPS.
+
+## Citation
+<br>
+
+## Issues and Suggestions
+Please submit any issues or suggestions via [GitHub](https://github.com/CCMS-UCSD/GNPS_Workflows). The use of the [GNPS forum](https://groups.google.com/forum/#!forum/molecular_networking_bug_reports) is encouraged.
+
+## Page Contributions
+Alan K. Jarmusch (UCSD)

docs/msmschooserdataacquisitionQE.md

@@ -0,0 +1,46 @@
+# MSMS-Chooser: Data Acquisition - QExactive (v1.0)
+
+## Summary
+ **This document details an open-source protocol for the Thermo QExactive mass spectrometer coupled to the Thermo Vanquish UHPLC** used to combination with [MSMS-Chooser](https://proteomics2.ucsd.edu/ProteoSAFe/), a GNPS workflow and open-source protocol to empower the community to collect MS/MS reference data and contribute to the public MS/MS reference library.
+
+1-5 μL of sample is introduced into a flow of MeOH-Water (1:1) with ~0.1% formic acid at 0.5 mL/min via injection from the autosampler. The needle is washed for 3 s prior to injection, flow rate of 10 μL/sec. Data acquisition for each injection is 0.3 minutes with the majority of the sample arriving ~0.05 - 0.1 min after injection. Data-dependant acquisition is used to collect data on the top 5 precursors at a resolution of 35,000. MS/MS data are collected using an isolation width of m/z 1.7 and stepped normalized collision energy of 20, 30, and 40. Separate positive and negative ionization mode methods were created with differences in the ionization source parameters. Further details can be found in the method files.
+
+Data acquisition takes 0.3 min followed by 0.3 - 0.4 min of needle washing and drawing of the next sample before the next sample. The total processes taking ~45 - 50 s for one injection sequence. The flow continues during the needle washing and drawing time, effectively flushing the line for ~30 s in between samples. 
+
+## Required Materials
+1. Vanquish UHPLC
+    * Solvent A - water (HPLC grade) w/ ~0.1% formic acid (v/v) = 4 L of water (HPLC grade) + 4 mL of formic acid using glass syringe, mix by inverting bottle 15 times.
+     * Solvent B - methanol (HPLC grade) w/ ~0.1% formic acid (v/v) = 4 L of methanol (HPLC grade) + 4 mL of formic acid using glass syringe, mix by inverting bottle 15 times.
+   * Associated fittings and tubing
+2. QExactive
+3. Syringe pump and required fitting for instrument calibration (see instrument calibration SOP)
+4. MS calibration solution specific to calibration protocol
+5. MS tune and MS method files can be downloaded from [MassIVE](link here).
+
+## Step-by-Step Instructions
+### Data Acquisition
+1. Create a folder on the local computer following this standard “D:\SOPGNPSChemicaltoLibrary\[insert barcode]”
+2. Obtain the **MSMS-Chooser sequence table** and copy it to a folder on the local computer.
+   * If you are analyzing more than one plate, open the corresponding .csv files and copy and merge  them together in a spreadsheet editor. You will need to change the plate positions.
+3. Double check the barcode, the number of samples, and the plate position used (e.g. “red”; “RA1”).
+4. Calibrate the QExactive following instrument manufacturer directions in both negative and positive ion modes (using the appropriate tune file and source position).
+5. After calibration passes, load the “20190520_SOP_chemicalreferencetoGNPSlibrary_positive.meth”.
+   * the path to the tune file may need to be updated in the methods
+6. Place Solvent A and Solvent B onto the LC and purge the lines.
+7. Check all other solutions (e.g. needle wash) and ensure solvent level is sufficient.
+8. Place a zero-dead volume union (stainless steel) in the column compartment.
+9. Turn the instrument from “standby” to “on”.
+10. Flow the solvent 50% Solvent A and 50% Solvent B @ 0.5 mL / min.
+    * The backpressure was observed to be between 30-50 bar depending on the temperature of the column compartment.
+11. Import the appropriate sequence table (.csv) into Xcalibur, and double check the following:
+    * The barcode matches
+    * The amount of rows in the sequence table matches the number of wells.
+    * The plate is positioned in the correct tray, (e.g. red if the injection position starts with “R:”)
+    * Ensure that the positive and negative mode methods are appropriately selected.
+12. Save the sequence file and start data collection
+
+## Issues and Suggestions
+Please submit any issues or suggestions via [GitHub](https://github.com/CCMS-UCSD/GNPS_Workflows). The use of the [GNPS forum](https://groups.google.com/forum/#!forum/molecular_networking_bug_reports) is encouraged.
+
+## Page Contributions
+Alan K. Jarmusch (UCSD)

mkdocs.yml

@@ -43,6 +43,9 @@ pages:
         - Reference Spectral Library Curation: spectrumcuration.md
         - Reference Spectral Library Batch Addition: batchupload.md
         - Downloading Reference Spectral Libraries: downloadlibraries.md
+        - Open-source Method for Reference Library Generation:
+            - Data Acqusition - Thermo QExactive (v1.0): msmschooserdataacquisitionQE.md
+            - Computational Selection of MSMS to Include in Library (MSMS-Chooser): msmschooser.md
     - Public Datasets:
         - Dataset Creation/Sharing: datasets.md
         - Continuous Identification: continuousid.md