# RIAssigner
[](https://github.com/RECETOX/RIAssigner/actions/workflows/python-package.yml)
[](https://github.com/RECETOX/RIAssigner/actions/workflows/python-package-conda.yml)
[](https://github.com/RECETOX/RIAssigner/actions/workflows/anaconda.yml)
[](https://anaconda.org/bioconda/riassigner)
[](https://pypi.org/project/RIAssigner/)
[](https://doi.org/10.21105/joss.04337)
## Overview
RIAssigner is a python tool for retention index (RI) computation for GC-MS data developed at [RECETOX](https://www.recetox.muni.cz/en) and hosted on [Galaxy](https://umsa.cerit-sc.cz/).
The [retention index](https://goldbook.iupac.org/terms/view/R05360) 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](https://anaconda.org/bioconda/riassigner) in your existing evironment.
```
conda install -c bioconda riassigner
```
(3) Install via [pip](https://pypi.org/project/RIAssigner/) in your existing evironment.
```
pip install riassigner
```
## Usage
RIAssigner can be used to read data from `.msp` and `.mgf` files using [matchms](https://github.com/matchms/matchms) and `.csv`, `.tsv` and `.parquet` using [pandas](https://pandas.pydata.org/) 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](https://doi.org/10.1016/S0021-9673(01)80947-X) method or by using [cubic spline-based interpolation](https://doi.org/10.1021/ac50035a026).
### Example
```python
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](doc/example_usage.ipynb).
## Developer Documentation
### Setup
Create your development conda environment using the provided [file](conda/environment-dev.yml) 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](CHANGELOG.md) and to adhere to the [versioning](https://semver.org/spec/v2.0.0.html).
For more information see [here](CONTRIBUTING.md).
### Architecture
<!-- generated by mermaid compile action - START -->
<details>
<summary>Mermaid markup</summary>
```mermaid
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
```
</details>
<!-- generated by mermaid compile action - END -->
### Testing
All functionality is tested with the [pytest](https://docs.pytest.org/en/6.2.x/contents.html) 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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/RECETOX/RIAssigner",
"name": "RIAssigner",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<3.13",
"maintainer_email": "",
"keywords": "gas chromatography,mass spectrometry,retention index",
"author": "Helge Hecht",
"author_email": "helge.hecht@recetox.muni.cz",
"download_url": "https://files.pythonhosted.org/packages/cb/29/0138e72a4c80f3f5e3df31d14e0cead59e900c636256208ff4b000d987a8/riassigner-0.4.0.tar.gz",
"platform": null,
"description": "# RIAssigner\n[](https://github.com/RECETOX/RIAssigner/actions/workflows/python-package.yml)\n[](https://github.com/RECETOX/RIAssigner/actions/workflows/python-package-conda.yml)\n[](https://github.com/RECETOX/RIAssigner/actions/workflows/anaconda.yml)\n[](https://anaconda.org/bioconda/riassigner)\n[](https://pypi.org/project/RIAssigner/)\n[](https://doi.org/10.21105/joss.04337)\n\n## Overview\nRIAssigner is a python tool for retention index (RI) computation for GC-MS data developed at [RECETOX](https://www.recetox.muni.cz/en) and hosted on [Galaxy](https://umsa.cerit-sc.cz/).\n\nThe [retention index](https://goldbook.iupac.org/terms/view/R05360) 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.\nTo compute this index, a set of reference compounds - often an inert alkane series - is analyzed as part of the batch (on the same column).\nThe 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.\nThis can be done via piece wise linear interpolation or other mathematical methods.\n\nIf you use this software, please cite our paper!\n\nHecht 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\n\n## Installation\n\n(1) From source by cloning the repository and then installing the package with `pip`.\n```\ngit clone https://github.com/RECETOX/RIAssigner.git\ncd RIAssigner\npoetry install\n```\n(2) Install via [bioconda](https://anaconda.org/bioconda/riassigner) in your existing evironment.\n```\nconda install -c bioconda riassigner\n```\n(3) Install via [pip](https://pypi.org/project/RIAssigner/) in your existing evironment.\n```\npip install riassigner\n```\n\n## Usage\nRIAssigner can be used to read data from `.msp` and `.mgf` files using [matchms](https://github.com/matchms/matchms) and `.csv`, `.tsv` and `.parquet` using [pandas](https://pandas.pydata.org/) and to compute the retention indices for the data.\nA 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](https://doi.org/10.1016/S0021-9673(01)80947-X) method or by using [cubic spline-based interpolation](https://doi.org/10.1021/ac50035a026).\n### Example\n```python\nfrom RIAssigner.compute import Kovats\nfrom RIAssigner.data import MatchMSData, PandasData\n\n# Load reference & query data\nquery = PandasData(\"../tests/data/csv/aplcms_aligned_peaks.csv\", \"csv\", rt_unit=\"seconds\")\nreference = MatchMSData(\"../tests/data/msp/Alkanes_20210325.msp\", \"msp\", rt_unit=\"min\")\n\n# Compute RI and write it back to file\nquery.retention_indices = Kovats().compute(query, reference)\nquery.write(\"peaks_with_rt.csv\")\n```\nFor more details check out this [notebook](doc/example_usage.ipynb).\n\n## Developer Documentation\n### Setup\nCreate your development conda environment using the provided [file](conda/environment-dev.yml) to install all required dependencies, including linter and testing frameworks.\n```\nconda env create -n riassigner-dev python=3.10 poetry\nconda activate riassigner-dev\npoetry install --no-root\n```\n\n### Contributing\nWe appreciate contributions - feel free to open an issue on our repository, create your own fork, work on the problem and pose a PR.\nMake sure to add your contributions to the [changelog](CHANGELOG.md) and to adhere to the [versioning](https://semver.org/spec/v2.0.0.html).\nFor more information see [here](CONTRIBUTING.md).\n### Architecture\n<!-- generated by mermaid compile action - START -->\n\n<details>\n <summary>Mermaid markup</summary>\n\n```mermaid\nclassDiagram\n class MatchMSData{\n -List ~Spectra~ data\n }\n\n class PandasData {\n -DataFrame data\n }\n\n Data <|-- MatchMSData\n Data <|-- PandasData\n\n class Data{\n <<abstract>>\n +read(string filename)\n +write(string filename)\n +retention_times() List~float~\n +retention_indices() List~float~\n }\n\n\n class ComputationMethod{\n <<interface>>\n +compute(Data query, Data reference) List~float~\n\n }\n\n class Kovats {\n\n }\n class CubicSpline {\n\n }\n\n ComputationMethod <|-- Kovats\n ComputationMethod <|-- CubicSpline\n\n```\n\n</details>\n<!-- generated by mermaid compile action - END -->\n\n### Testing\nAll functionality is tested with the [pytest](https://docs.pytest.org/en/6.2.x/contents.html) 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.\n\nFor testing, install the package dependencies as follows:\n```\ngit clone https://github.com/RECETOX/RIAssigner.git\ncd RIAssigner\npoetry install --no-root\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for retention index calculation.",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/RECETOX/RIAssigner",
"Repository": "https://github.com/RECETOX/RIAssigner"
},
"split_keywords": [
"gas chromatography",
"mass spectrometry",
"retention index"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65a0194ff845d866baf05bf6cd4eb8029ee0b3d3883fabd63baec1d648e79d86",
"md5": "7c101167e46c8a1bd7f64c173037c170",
"sha256": "be378c9f55b5e55b29cb39af455bfdcc5147d36aae525a2514ac8cdef150e667"
},
"downloads": -1,
"filename": "riassigner-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c101167e46c8a1bd7f64c173037c170",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.13",
"size": 17837,
"upload_time": "2024-02-13T10:38:04",
"upload_time_iso_8601": "2024-02-13T10:38:04.481324Z",
"url": "https://files.pythonhosted.org/packages/65/a0/194ff845d866baf05bf6cd4eb8029ee0b3d3883fabd63baec1d648e79d86/riassigner-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb290138e72a4c80f3f5e3df31d14e0cead59e900c636256208ff4b000d987a8",
"md5": "36ad96bd68cdb89eb8feb4e4c0096f2b",
"sha256": "32d0306ba76feb7d470eb504b2bd382f0d78c85f7795bc275abad0c874ee7d61"
},
"downloads": -1,
"filename": "riassigner-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "36ad96bd68cdb89eb8feb4e4c0096f2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.13",
"size": 14196,
"upload_time": "2024-02-13T10:38:06",
"upload_time_iso_8601": "2024-02-13T10:38:06.250765Z",
"url": "https://files.pythonhosted.org/packages/cb/29/0138e72a4c80f3f5e3df31d14e0cead59e900c636256208ff4b000d987a8/riassigner-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 10:38:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RECETOX",
"github_project": "RIAssigner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "riassigner"
}
JSON
