Spectral library polarity separation

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"