HolobiomicsLab spectral-library-polarity-separation
Summary
Separate mixed-polarity tandem mass spectral (MS2) libraries into positive and negative ionization mode files for MS-DIAL compatibility. This skill is essential when compiled libraries from sources like NIST or GNPS contain both polarities in a single MSP or MGF file but downstream analysis requires polarity-specific spectral databases.
When to use
Apply this skill when you have loaded an MS2 library (from NIST, GNPS, or other sources via read_lib()) that contains both positive and negative ionization modes mixed in a single file, and you need to produce two separate, polarity-specific MSP files for use in MS-DIAL or similar tandem MS analysis software.
When NOT to use
- Library is already separated into distinct positive and negative files
- Input is an EI (electron ionization) library, which does not use ionization polarity
- You need to preserve mixed-polarity records in a single file for deconvolution or comparative analysis
Inputs
- MS2 library object (loaded via read_lib with type='MS2')
- MGF-format spectral library (loaded via read_lib with format='mgf')
- Library with both positive and negative ionization modes
Outputs
- Positive-mode MS2 library object (polarity='pos')
- Negative-mode MS2 library object (polarity='neg')
- MSP file for positive mode (written via write_MS2_msp)
- MSP file for negative mode (written via write_MS2_msp)
How to apply
After reading the MS2 library (using read_lib() with type='MS2' or format='mgf'), call separate_polarity() twice—once with polarity='pos' and once with polarity='neg'—to partition the library object into positive and negative subsets. For NIST MS2, this step follows structure assignment (assign_smiles()) and precedes final writing. For GNPS libraries in MGF format, call complete_mgf() first to calculate molecular formula from SMILES where missing, then separate_polarity(). The separation logic filters records by the ionization mode field; verification is performed by confirming no mixed polarities remain within a single output file and that all records are retained across the two outputs.
Related tools
- mspcompiler (R package that implements separate_polarity() function for partitioning MS2 libraries by ionization mode) — https://github.com/QizhiSu/mspcompiler
- MS-DIAL (Downstream software that consumes polarity-separated MSP files as spectral databases)
- read_lib (mspcompiler function to load MS2 libraries from MSP or MGF files before polarity separation) — https://github.com/QizhiSu/mspcompiler
- write_MS2_msp (mspcompiler function to write polarity-separated libraries to MS-DIAL-compatible MSP format) — https://github.com/QizhiSu/mspcompiler
- complete_mgf (mspcompiler function to compute molecular formula from SMILES in GNPS MGF libraries before polarity separation) — https://github.com/QizhiSu/mspcompiler
Examples
nist_ms2_pos <- separate_polarity(nist_ms2, polarity = "pos")
nist_ms2_neg <- separate_polarity(nist_ms2, polarity = "neg")
write_MS2_msp(nist_ms2_pos, "D:/MS_libraries/nist_ms2_pos.msp")
write_MS2_msp(nist_ms2_neg, "D:/MS_libraries/nist_ms2_neg.msp")
Evaluation signals
- Output MSP files contain no records with mixed ionization polarities (all records in positive file marked '+', all in negative file marked '−' or 'neg')
- Record count across both output files equals the input library record count (no loss or duplication)
- Output files conform to MS-DIAL MSP specification for header, polarity field, and spectral peak format
- Each output file header contains correct polarity annotation readable by MS-DIAL import functions
Limitations
- Separation depends on correct polarity annotation in the source library; mislabeled or missing polarity fields will cause misclassification
- GNPS libraries in MGF format require prior call to complete_mgf() to calculate molecular formula; separation alone does not fill missing MF values
- Large libraries (hundreds of thousands of records) processed without parallel computing may be time-consuming; mspcompiler examples use future and future.apply for parallelization
Evidence
- [readme] MS2 libraries can be processed in a similar way, but positive and negative modes are normally separated into 2 msp files.: "positive and negative modes are normally separated into 2 msp files"
- [readme] The exported msp file has both positive and negative modes mixed in a singled file, so we have to separated them by the separate_polarity function.: "both positive and negative modes mixed in a singled file, so we have to separated them by the separate_polarity function"
- [other] separate_polarity() with polarity='pos' and polarity='neg'. Combine all four sources (NIST, RIKEN, MoNA, GNPS) into two polarity-specific objects using c(). Write polarity-separated libraries to MSP format using write_MS2_msp()...: "Separate both NIST and GNPS libraries into positive and negative modes using separate_polarity() with polarity='pos' and polarity='neg'"
- [other] Validation: output MSP files conform to MS-DIAL format specification and contain no mixed polarities within a single file.: "output MSP files conform to MS-DIAL format specification and contain no mixed polarities within a single file"
- [other] For GNPS library in MGF format, use complete_mgf() to calculate Molecular Formula from SMILES where missing.: "use complete_mgf() to calculate Molecular Formula from SMILES where missing"