RIAssigner

Overview

RIAssigner is a python tool for retention index (RI) computation for GC-MS data developed at RECETOX and hosted on Galaxy.

The retention index is a mapping of retention time, making the retention data of compounds comparable, i.e. two compounds might have different retention times in different experiments, but a very similar retention index. To compute this index, a set of reference compounds - often an inert alkane series - is analyzed as part of the batch (on the same column). The retention index of the alkanes are fixed (carbon number x 100) and any query compounds can be assigned a retention index depending on its retention time. This can be done via piece wise linear interpolation or other mathematical methods.

If you use this software, please cite our paper!

Hecht et al., (2022). RIAssigner: A package for gas chromatographic retention index calculation. Journal of Open Source Software, 7(75), 4337, https://doi.org/10.21105/joss.04337

Installation

(1) From source by cloning the repository and then installing the package with pip.

git clone https://github.com/RECETOX/RIAssigner.git
cd RIAssigner
poetry install

(2) Install via bioconda in your existing environment.

conda install -c bioconda riassigner

(3) Install via pip in your existing environment.

pip install riassigner

Usage

RIAssigner can be used to read data from .msp and .mgf files using matchms and .csv, .tsv and .parquet using pandas and to compute the retention indices for the data. A reference list of retention indexed compounds (traditionally an Alkane series) with retention times is used to compute the RI for a query dataset of retention time values using the van Den Dool and Kratz method or by using cubic spline-based interpolation.

Python API

from RIAssigner.compute import Kovats
from RIAssigner.data import MatchMSData, PandasData

# Load reference & query data
query = PandasData("../tests/data/csv/aplcms_aligned_peaks.csv", "csv", rt_unit="seconds")
reference = MatchMSData("../tests/data/msp/Alkanes_20210325.msp", "msp", rt_unit="min")

# Compute RI and write it back to file
query.retention_indices = Kovats().compute(query, reference)
query.write("peaks_with_rt.csv")

For more details check out this notebook.

Command Line Interface

RIAssigner provides a command-line interface for computing retention indices without writing Python code.

Compute retention indices

Use the compute command to calculate retention indices for a query dataset based on a reference dataset:

riassigner compute \
  --reference <path> <filetype> <rt_unit> \
  --query <path> <filetype> <rt_unit> \
  --method <kovats|cubicspline> \
  --output <output_path>

Parameters:

• --reference: Reference dataset with retention times and indices. Provide: path, filetype (msp/csv/tsv/parquet), and retention time unit (min/seconds)
• --query: Query dataset for which to compute retention indices. Provide: path, filetype (msp/csv/tsv/parquet), and retention time unit (min/seconds)
• --method: Computation method - either kovats (van Den Dool and Kratz) or cubicspline
• --output: Path for the output file with computed retention indices

Example:

riassigner compute \
  --reference reference_alkanes.msp msp min \
  --query query_peaks.csv csv seconds \
  --method kovats \
  --output peaks_with_ri.csv

Extract retention indices from comments

Use the ri-from-comment command to extract retention indices from the comment field of a dataset:

riassigner ri-from-comment \
  --query <path> <filetype> <rt_unit> \
  --ri-source <key> \
  --output <output_path>

Parameters:

• --query: Query dataset from which to read retention indices. Provide: path, filetype (msp/csv/tsv/parquet), and retention time unit (min/seconds)
• --ri-source: Key used in the comment field to identify the retention index value
• --output: Path for the output file

Example:

riassigner ri-from-comment \
  --query compounds.msp msp min \
  --ri-source "retention index" \
  --output compounds_with_ri.msp

Developer Documentation

Setup

conda create -n riassigner-dev -c conda-forge python=3.10 poetry

conda activate riassigner-dev

poetry install --no-root

Contributing

We appreciate contributions - feel free to open an issue on our repository, create your own fork, work on the problem and pose a PR. Make sure to add your contributions to the changelog and to adhere to the versioning. For more information see here.

Architecture

classDiagram
    class MatchMSData{
        -List ~Spectra~ data
    }

    class PandasData {
        -DataFrame data
    }

    Data <|-- MatchMSData
    Data <|-- PandasData

    class Data{
        <<abstract>>
        +read(string filename)
        +write(string filename)
        +retention_times() List~float~
        +retention_indices() List~float~
    }


    class ComputationMethod{
        <<interface>>
        +compute(Data query, Data reference) List~float~

    }

    class Kovats {

    }
    class CubicSpline {

    }

    ComputationMethod <|-- Kovats
    ComputationMethod <|-- CubicSpline

Testing

All functionality is tested with the pytest framework. Make sure to run your IDE in the riassigner-dev conda environment (or make sure to use the respective python interpreter when developing) to follow formatting guidelines and to be able to execute the tests.

For testing, install the package dependencies as follows:

git clone https://github.com/RECETOX/RIAssigner.git
cd RIAssigner
poetry install --no-root
pytest