Kovats retention index extraction and assignment

Kovats Retention Index Extraction and Assignment

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Extract experimental Kovats retention indices (RI) from NIST reference files and assign them to combined EI spectral library records based on GC column polarity, using median RI values and filtering by column type and variance thresholds to improve library metadata quality for MS-DIAL.

When to use

You have compiled a multi-source EI library (NIST, RIKEN, MoNA, SWGDRUG) into a single msp object and want to enrich it with experimental retention index metadata. Apply this skill when you have access to NIST library installation files (ri.dat and USER.DBU) and need to assign RI values stratified by GC column polarity (semi-polar, non-polar, or polar) before writing the final MS-DIAL-ready msp file.

When NOT to use

• NIST library is not installed or ri.dat/USER.DBU files are not available on your system
• Library records are MS2 (tandem MS) rather than EI spectra; MS2 records do not use Kovats RI
• Column polarity of your target GC method is unknown or does not match the available RI references (semi-polar, non-polar, polar)

Inputs

• combined EI library object (mspcompiler lib object containing NIST, RIKEN, MoNA, and/or SWGDRUG records)
• ri.dat file (NIST RI database, typically at ~/Programs/nist14/mssearch/nist_ri/ri.dat)
• USER.DBU file (NIST user RI database, typically at ~/Programs/nist14/mssearch/nist_ri/USER.DBU)
• column polarity specification (semi-polar | non-polar | polar)

Outputs

• combined EI library object with assigned Kovats RI field enriched with experimental values
• RI records stratified by column polarity and filtered for capillary columns only
• median RI values per compound with variance thresholding applied

How to apply

First, extract experimental RI data from NIST reference files (ri.dat and USER.DBU) using the extract_ri() function, which parses the NIST RI database. Second, call assign_ri() on the combined library object, specifying the target column polarity (typically 'semi-polar' for capillary GC columns). The function filters to retain only capillary column records, removes Lee RI values, computes the median RI when multiple records exist for a single compound, and discards median values with standard deviation > 30 to ensure quality. This multi-step filtering ensures that only robust, polarity-matched RI annotations are assigned to each spectral record.

Related tools

• mspcompiler (R package providing extract_ri() and assign_ri() functions for RI extraction, filtering, and assignment) — https://github.com/QizhiSu/mspcompiler
• NIST Library Installation (source of ri.dat and USER.DBU files containing experimental RI data indexed by compound name and GC column polarity)
• MS-DIAL (target software that consumes the RI-enriched msp file for spectral library matching and peak annotation) — http://prime.psc.riken.jp/compms/msdial/main.html

Examples

nist_ri <- extract_ri("D:/MS_libraries/ri.dat", "D:/MS_libraries/USER.DBU")
combine_ei <- assign_ri(combine_ei, nist_ri, polarity = "semi-polar")

Evaluation signals

• Output library object contains RI values assigned to all or most compound records without duplication or missing values for the target polarity
• RI assignments are stratified correctly by the specified GC column polarity (semi-polar, non-polar, or polar)
• Records with RI standard deviation > 30 are discarded; remaining RI values are robust median estimates
• Only capillary column RI records are retained; Lee RI and other column types are removed
• Final msp file is readable and accepted by MS-DIAL without parse errors related to RI field format or range

Limitations

• RI assignment requires NIST library installation and ri.dat/USER.DBU file access; not available for open-source EI libraries lacking these files
• RI values are filtered by column polarity; if your GC method uses a non-standard or hybrid column polarity, RI assignment may fail or yield few matches
• Median RI and standard deviation filtering (SD > 30 threshold) may result in loss of RI annotations for compounds with high variability across NIST records
• RIKEN EI library records already contain Kovats RI; re-assigning RI from NIST may override pre-existing RIKEN annotations if not handled carefully

Evidence

• [methods] Extract experimental RI from NIST ri.dat and USER.DBU files using extract_ri(): "Extract experimental RI from the "ri.dat" and "USER.DBU" files."
• [methods] Assign experimental RI depending on column polarity with filtering for capillary columns and variance threshold: "Assign experimental RI to the combined library depending on the column polarity. The polarity can be "semi-polar", "non-polar", or "polar". Providing that "capillary" GC columns are commonly used."
• [readme] mspcompiler goal is to compile EI and tandem mass spectral libraries from various sources and organize them into a neat and up-to-date msp file: "The goal of mspcompiler is to offer ways to compile either EI or tandem mass spectral libraries from various sources"
• [methods] RIKEN EI library already contains Kovats RI; read with remove_ri=FALSE to retain existing RI: "As it contains Kovats RI, we can set remove_ri to FALSE to keep original RI in this file."
• [methods] Workflow step to assign RI after reading and organizing all libraries: "assign_ri(combine_ei, nist_ri, polarity = "semi-polar")"