RIAssigner 0.4.1

Python library for retention index calculation.

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 evironment.

conda install -c bioconda riassigner

(3) Install via pip in your existing evironment.

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.

Example

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.

Developer Documentation

Setup

Create your development conda environment using the provided file to install all required dependencies, including linter and testing frameworks.

conda env create -n riassigner-dev 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

Mermaid markup

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