Step 6: Command tremolo

Runs the spectral identification of a collection of consensus spectra against the In-Silico predicted MS/MS spectrum of Natural Products Database¹ (ISDB) for 170 602 Natural Products from the Universal Natural Products Database² (UNPD) using the tremolo tool³ to retrieve library annotations. This tool can only be executed in Unix OS and for data in positive ion mode.

The Step 6.1 corresponds to the GNPS2 Library Search and is described in the next section.

The NPClassifier⁴, NPAtlas⁵ and ClassyFire⁶ solutions were used to add origin and class information to the UNPD compounds. NP³ MS Workflow will retrieve this information together with the library annotations.

At the end of the spectral identification step, a curation is performed to select the best UNPD result from the top k identifications of each spectra and to score them with a personalized criteria. Additionally, a superclass grouping of the NPClassifier result was proposed by the NP³ team and is also applied here for the curated superclass.

Finally, the final identification curation is performed (more details in next section).

A binary version of the tremolo tool is freely available for download in the following link.

Parameters:

For the complete list of parameters run:

node np3_workflow.js tremolo --help

Parameters for the command tremolo:

• -o, --output_path : path to where the spectral library search results will be stored. This is usually the 'identifications' folder present in the final result.
• -g, --mgf : path to the input MGF file with the MS/MS spectra data to be searched and identified
• -c, --count_files [name] : optional paths to the count CSV files, separated by a comma and no space, as outputted by the NP³ MS workflow where the identifications should be added as new columns. The top_k search results for each msclusterID will be added in additional identification columns generated by tremolo, then the curated and best results will also be added in other columns. The count files header must be in the first row. (default: "")
• -z, --mz_tolerance : the tolerance for parent mass search in Daltons. Set a small tolerance for dereplication using parent ion mass as prefilter, keeping in mind the resolution of your data. Increase to the wanted range for variable dereplication search (ex: 100 or 200 Da) Caution as this will also increase calculation times! (default: 0.025)
• -s, --similarity : the similarity threshold that determines if two spectra are the same. Should be kept low when using in-silico DB, as recommended by the authors. Typically, 0.2 to 0.3 (default: 0.2)
• -k, --top_k : defines the maximal number of results returned by the tremolo tool, e.g. number of identifications by msclusterID
• -v, --verbose : for values X > 0 show the scripts output information (default: 0)
• -h, --help : output usage information

Results

Two files are created inside the 'output_path' folder (this folder is created if missing):

• 'logTremolo' a text file with the tremolo tool output information;
• 'tremolo_results.csv' a CSV file with the tremolo search results for each spectra SCANS present in the provided MGF file. Each top_k result is presented in a separated row in this table.

When the count_files are provided, the tremolo results are aggregated by spectra and the following columns are added to the tables:

Identification Columns	Description
tremolo_UNPD_IDs	the UNPD IDs of the top_k identified spectra concatenated with a ';'
tremolo_SMILES	the SMILES of the top_k identified spectra concatenated with a ','. A comma is used here to allow including this information in cytoscape to visualize the nodes annotated identified structure. This column must be quoted ""
tremolo_chemicalNames	the chemical names of the top_k identified spectra concatenated with a ';'
tremolo_InChIKey	the InChIKey of the top_k identified spectra concatenated with a ';'
tremolo_molecularFormula	the molecular formula of the top_k identified spectra concatenated with a ';'
tremolo_molecularWeight	the molecular weight of the top_k identified spectra concatenated with a ';'
tremolo_CAS	the CAS number of the top_k identified spectra concatenated with a ';'
tremolo_MQScore	the MQ score computed by tremolo of the top_k identified spectra concatenated with a ';'. Similarity score, evaluates the quality of the match
tremolo_mzErrorPPM	the m/z error in PPM for the top_k identified spectra concatenated with a ';'. Mass error, evaluates the quality of the match and signalizes analogs
tremolo_numSharedPeaks	the number of shared peaks with the top_k identified spectra concatenated with a ';'. Shared peaks in the match, evaluates the quality of the match
tremolo_NPClassifier_superclass	the chemical superclass from NPClassifier and ClassyFire separated by a pipe '|' for the top_k identified spectra concatenated with a ';'. In some cases it was assigned more than one superclass from NPClassifier or ClassyFire, and they are separated by a ':'
tremolo_NPClassifier_class	the chemical class from NPClassifier and ClassyFire separated by a pipe '|' for the top_k identified spectra concatenated with a ';'. In some cases it was assigned more than one class from NPClassifier or ClassyFire, and they are separated by a ':'
tremolo_ClassyFire_subclass	the chemical subclass from ClassyFire of the top_k identified spectra concatenated with a ';'
tremolo_NPClassifier_pathway	the chemical pathway from NPClassifier of the top_k identified spectra concatenated with a ';'. In some cases it was assigned more than one pathway from NPClassifier and they are separated by a ':'
tremolo_NPClassifier_isglycoside	the chemical is glycoside tag from NPClassifier of the top_k identified spectra concatenated with a ';'
tremolo_NPAtlas_id	the NPAtlas ID of the top_k identified spectra concatenated with a ';'
tremolo_NPAtlas_compound_names	the compound names from NPAtlas of the top_k identified spectra concatenated with a ';'
tremolo_NPAtlas_origin_type	the biological origin type from NPAtlas of the top_k identified spectra concatenated with a ';'
tremolo_NPAtlas_genus	the biological genus from NPAtlas of the top_k identified spectra concatenated with a ';'
tremolo_NPAtlas_origin_species	the biological origin species from NPAtlas of the top_k identified spectra concatenated with a ';'
tremolo_best_position	the index position of the best tremolo result among the top_k identifications following the criteria defined in Section 4.6.4
tremolo__best	some of the previous identification columns with the best result from index tremolo_best_position
tremolo_NPClassifier_superclass_clean_best	the superclass assigned by NPClassifier when the result from ClassyFire is also present and separated by a '
tremolo_UNPD_category_best	the tremolo UNPD category of the best result following the criteria define in Section 4.6.4
tremolo_UNPD_score_best	the corresponding score of the tremolo_UNPD_category_best
tremolo_curated_superclass	the result of the tremolo_NPClassifier_superclass_clean_best for the spectra that have tremolo_UNPD_score_best > 0 (or tremolo_UNPD_category_best != 'out')
tremolo_curated_superclass_grouping	the superclass group from the mapped tremolo_curated_superclass following the proposed groups in Section 4.6.4
tremolo_curated_superclass_GR_\<curated superclass group>	0 or +1 values indicating if the respective curated superclass group appears in the tremolo_curated_superclass_grouping zero, one or more times as detailed in Section 4.6.4
curated_lib_annotation_origin	the database library origin of the final curated identification, which have the greater score. It receives 'UNPD' if tremolo_UNPD_score_best > 0 or 'GNPS' if gnps_score > 0 and gnps_score >= tremolo_UNPD_score_best. Detailed in Section 4.6.5.
curated_lib_annotation_ID	the library ID of the final curated identification from the best origin. Equals to tremolo_UNPD_IDs_best where origin is UNPD, equals to gnps_SpectrumID where origin is GNPS, and equals '' otherwise
curated_lib_annotation_compoundName	the compound name of the final curated identification from the best origin. Equals to tremolo_chemicalNames_best where origin is UNPD, equals to gnps_Compound_Name where origin is GNPS, and equals '' otherwise
curated_lib_annotation_SMILES	the SMILES of the final curated identification from the best origin. If curated_lib_annotation_origin == UNPD it receives the value of the tremolo_SMILES_best, if curated_lib_annotation_origin == GNPS it receives the value of the gnps_Smiles, otherwise ''
curated_lib_annotation_superclass	the NPClassifier superclass of the final curated identification from the best origin. Equals to tremolo_curated_superclass where origin is UNPD, equals to gnps_curated_superclass where origin is GNPS, and equals '' otherwise
curated_lib_annotation_superclass_grouping	the superclass group from the mapped curated_lib_annotation_superclass following the proposed groups in Section 4.6.4
curated_lib_annotation_superclass_GR_ \<final curated superclass group>	0 or +1 values indicating if the respective curated superclass group appears in the curated_lib_annotation_superclass_grouping zero, one or more times as detailed in Section 4.6.4
curated_lib_annotation_score	the corresponding score of the final curated identification from the best origin. Equals to tremolo_UNPD_score_best for UNPD, or gnps_score for GNPS, or 0 otherwise.
curated_lib_annotation_quality	a quality group for the final curated identification. Equals to '1' if curated_lib_annotation_score >= 50, or '2' if curated_lib_annotation_score < 50 and curated_lib_annotation_score > 0, or '0' otherwise (curated_lib_annotation_score == 0).

For more details about the Tremolo tool see the src/ISDB_tremolo_NP3/README.md file and its documentation at src/ISDB_tremolo_NP3/Data/doc/Workflow_062016.pdf.

Examples

Fake example to execute the Tremolo command:

node np3_workflow.js tremolo --output_path "/path/to/the/output/dir/test_np3/outs/test_np3/identifications" --mgf 
"/path/to/the/output/dir/test_np3/outs/test_np3/mgf/test_np3_all.mgf"

Concatenate tremolo results in the count files:

node np3_workflow.js tremolo -o "/path/to/the/output/dir/test_np3/outs/test_np3/identifications" 
-g "/path/to/the/output/dir/test_np3/outs/test_np3/mgf/test_np3_all.mgf" -c 
"/path/to/the/output/dir/test_np3/outs/test_np3/test_np3_spectra_clean_ann.csv,/path/to/the/output/dir/test_np3/outs/test_np3/test_np3_peak_area_clean_ann.csv"

UNPD Identification Curation

A curation of the identification results was proposed to score and rank the best identification from the UNPD-tremolo. The curation is executed after the library annotations are merged to the count_files tables. Some chemical criteria were defined to automatically select the best annotations from the top_k results. Additionally, a chemical grouping of the NPClassifier superclass were proposed by the NP³ team to ease the chemical understanding of the best identifications.

The curation starts by selecting the best result among the top_k identifications for each identified spectra in UNPD and then extract its value for each identification column, as follows:

1. The best result is defined as the library annotation with the higher tremolo_MQScore which have
2. tremolo_mzErrorPPM < 20 if any, otherwise it is defined equals to the identification with the smaller
3. tremolo_mzErrorPPM rounded in the first decimal place which have the higher tremolo_MQScore;
4. The best result position is set in a new column named 'tremolo_best_position' which will store the index of the
5. best result among the top_k library annotations of each spectra;
6. New identification columns are created with only the best selected result (from the 'tremolo_best_position') and
7. are named equal to the identification column names plus a suffix equals to '_best'.
   • Additionally, it is created the column 'tremolo_NPClassifier_superclass_clean_best' with only the superclass
   • assigned by NPClassifier when the result from ClassyFire is also present and separated by a pipe '|' (only the
   • best result before the pipe).

UNPD Score Criteria

After the best UNPD result were selected and their information extracted, the curation proceeds to a categorization and scoring of the best result. Ten categories and scores were defined to group the best results according to the reliability of their matches or to put them out of the analysis, using the criteria presented below:

Tremolo UNPD Category	Score	Criteria
Top1|mqs>=0.5	100	mzE <= 20 and nsP >= 6
Top2|0.4<=mqs<0.5	80	mzE <= 20 and nsP >= 6
Top3|sp<6 mqs>=0.5	60	mzE <= 20 and nsP < 6
Top4|sp<6 0.4<=mqs<0.5	50	mzE <= 20 and nsP < 6
Top5|mqs>=0.2	45	mzE <= 20 and nsP >= 6 and mqs<0.4
Analog1|mqs>=0.5	40	mzE > 20 and nsP >= 6
Analog2|0.4<=mqs<0.5	30	mzE > 20 and nsP >= 6
Analog3|sp<6 mqs>=0.5	20	mzE > 20 and nsP < 6
Analog4|sp<6 0.4<=mqs<0.5	10	mzE > 20 and nsP < 6
Analog5|mqs>=0.2	5	mzE > 20 and nsP >= 6 and mqs<0.4
out	0	did not passed in any category - unreliable identification

• Where mqs is the tremolo_MQScore_best, nsP is the tremolo_numSharedPeaks_best and mzE is the tremolo_mzErrorPPM_best values.

The defined category of each final best UNPD identification is stored in the column 'tremolo_UNPD_category_best' and its corresponding score is stored in the column 'tremolo_UNPD_score_best'.

Superclass grouping

Finally, the curation of the UNPD identification also defines and creates 10 groupings of the superclasses from the NPClassifier. In UNPD, there are 94 superclasses from the NPClassifier, which is a very large number for a fast analysis. Here the NP³ team proposed a groupings with 10 major superclasses using a chemical reasoning to group related superclasses in a Drug Discovery perspective. The major superclasses groupings are presented in the table below:

Major Superclass Group	NPClassifier Superclasses
Aminoacids_and_Peptides_and_OtherNComp	"Amino acid glycosides", "Mycosporine derivatives", "Oligopeptides", "Small peptides", "Aminosugars and aminoglycosides", "Diazotetronic acids and derivatives", "Mitomycin derivatives", "Organic nitrogen compounds", "Nucleosides, nucleotides, and analogues", "Nucleosides"
Alkaloids_and_Lactams	"Alkaloids and derivatives", "Anthranilic acid alkaloids", "Lysine alkaloids", "Guanidine alkaloids", "Histidine alkaloids", "Ornithine alkaloids", "Peptide alkaloids", "Proline alkaloids", "Pseudoalkaloids", "Tetramate alkaloids", "Miscellaneous alkaloids", "Nicotinic acid alkaloids", "Serine alkaloids", "Tryptophan alkaloids", "Tyrosine alkaloids", "$\beta$-lactams", "$\gamma$-lactam-$\beta$-lactones"
Terpenes_and_Carotenoids	"Diterpenoids", "Meroterpenoids", "Monoterpenoids", "Sesterterpenoids", "Triterpenoids", "Steroids", "Sesquiterpenoids", "Apocarotenoids", "Carotenoids (C40)", "Carotenoids (C45)", "Carotenoids (C50)"
Fatty_Acids_and_Lipids	"Fatty Acids and Conjugates", "Fatty acyl glycosides", "Fatty acyls", "Fatty amides", "Fatty esters", "Lipids and lipid-like molecules", "Docosanoids", "Eicosanoids", "Glycerophospholipids", "Glycerolipids", "Octadecanoids", "Sphingolipids", "Hydrocarbons", "Hydrocarbon derivatives"
Polyketides	"Aromatic polyketides", "Cyclic polyketides", "Macrolides", "Linear polyketides", "Miscellaneous polyketides", "Polycyclic aromatic polyketides", "Polyethers"
Benzenoids	"Benzenoids", "Diarylheptanoids", "Naphthalenes", "Phenanthrenoids", "Stilbenoids", "Terphenyls", "Diphenyl ethers (DPEs)", "Fluorenes"
Flavonoids_and_Phenolic_derivatives	"Alkylresorcinols", "Flavonoids", "Isoflavonoids", "Phenolic acids (C6-C1)", "Phenylethanoids (C6-C2)", "Phenylpropanoids (C6-C3)", "Phloroglucinols", "Phenylpropanoids and polyketides"
Organohalogen_and_Organometallic	"Organohalogen compounds", "Organometallic compounds", "Acetylides"
Lignans_and_Other_Ocompounds	"Chromanes", "Coumarins", "Organic oxygen compounds", "Polyols", "Polyprenols", "Saccharides", "Styrylpyrones", "Xanthones", "Lignans", "Lignans, neolignans and related compounds", "Tropolones"
Organic_Acids_and_OthersGenerals	"Homogeneous non-metal compounds", "Organic 1,3-dipolar compounds", "Organic acids and derivatives", "Organoheterocyclic compounds", "Organosulfur compounds"
Not_Annotated	"not_annotated"

Next, it is created the column 'tremolo_curated_superclass' that receives the result of the best tremolo superclass for the spectra that have tremolo_UNPD_score_best > 0 (or tremolo_UNPD_category_best != 'out'). This column is then mapped to the superclasses grouping defined above and stored in column 'tremolo_curated_superclass_grouping'. If multiple superclasses were assigned to a spectra, they are separated by a ':'. Finally, for each curated superclass grouping, it is created a column named 'tremolo_curated_superclass_GR_\<curated superclass grouping>' with 0 or +1 values that counts how many times the curated library annotation from UNPD-tremolo appeared in the corresponding curated superclass grouping (zero, one or more times).

At the end, the final identification curation is performed (next section). And then, the final chemical reports are created.

References

---

1. Allard PM, Péresse T, Bisson J, Gindro K, Marcourt L, Pham VC, Roussi F, Litaudon M, Wolfender JL. Integration of Molecular Networking and In-Silico MS/MS Fragmentation for Natural Products Dereplication. Anal Chem. 2016 Mar 15;88(6):3317-23. doi: 10.1021/acs.analchem.5b04804. Epub 2016 Mar 1. PMID: 26882108 (ISDB) ↩

2. Gu J, Gui Y, Chen L, Yuan G, Lu H-Z, Xu X (2013) Use of Natural Products as Chemical Library for Drug Discovery and Network Pharmacology. PLoS ONE 8(4): e62839. https://doi.org/10.1371/journal.pone.0062839 (UNPD) ↩

3. Mingxun Wang and Nuno Bandeira. Spectral Library Generating Function for Assessing Spectrum-Spectrum Match Significance. Journal of Proteome Research 2013 12 (9), 3944-3951. DOI: 10.1021/pr400230p (tremolo) ↩

4. Kim HW, Wang M, Leber CA, Nothias LF, Reher R, Kang KB, van der Hooft JJJ, Dorrestein PC, Gerwick WH, Cottrell GW. NPClassifier: A Deep Neural Network-Based Structural Classification Tool for Natural Products. J Nat Prod. 2021 Oct 18. doi: 10.1021/acs.jnatprod.1c00399. Epub ahead of print. PMID: 34662515. (NPClassifier) ↩

5. van Santen, J. A.; Poynton, E. F.; Iskakova, D.; McMann, E.; Alsup, T. A.; Clark, T. N.; Fergusson, C. H.; Fewer, D. P.; Hughes, A. H.; McCadden, C. A.; Parra Villalobos, J.; Soldatou, S.; Rudolf, J. D.; Janssen, E. M.-L.; Duncan, K. R.; Linington, R. G.* "The Natural Products Atlas 2.0: A Database of Microbially-Derived Natural Products", Nucleic Acids Research, 2021, ASAP. 10.1093/nar/gkab941 (NPAtlas) ↩

6. Djoumbou Feunang Y, Eisner R, Knox C, Chepelev L, Hastings J, Owen G, Fahy E, Steinbeck C, Subramanian S, Bolton E, Greiner R, and Wishart DS. ClassyFire: Automated Chemical Classification With A Comprehensive, Computable Taxonomy. Journal of Cheminformatics, 2016, 8:61. DOI: 10.1186/s13321-016-0174-y (ClassyFire) ↩