Overview
chromConverter provides a simple way to read chromatography data into R from a variety of vendor formats. It includes parsers implemented directly in R as well as interfaces to various external tools including Entab, rainbow, the ThermoRawFileParser, and RaMS.
We aim to support open science and reproducible research by reducing dependence on proprietary vendor software. Since most of the supported file formats are not publicly documented, many of the parsers are developed through reverse engineering. If you run into a file that doesn’t parse correctly (or at all), please open an issue.
For downstream analysis of chromatographic data, see the companion package chromatographR.
Installation
chromConverter can be installed from CRAN:
install.packages("chromConverter")However, it’s recommended to install the development version, either from GitHub:
if (!require("pak", quietly=TRUE)) install.packages("pak")
pak::pak("ethanbass/chromConverter")or from R Universe:
install.packages("chromConverter", repos="https://ethanbass.r-universe.dev/")Some parsers require additional software. See Optional Dependencies for details.
Quick start
library(chromConverter)
# Read a folder of Agilent ChemStation UV files
dat <- read_chroms("path/to/files", format_in = "chemstation_uv")Formats
ChromConverter (internal parsers)
- ‘Agilent ChemStation’ & ‘OpenLab’
.uvfiles (versions 131, 31) - ‘Agilent ChemStation’ & ‘OpenLab’
.chfiles (versions 30, 130, 8, 81, 179, 181) - ‘Agilent ChemStation’
.msand.csvfiles - ‘Agilent OpenLab’
.dx,.acaml,.amx, and.Ddirectories - ‘Agilent OpenLab’
.rsltsequence directories - Allotrope® Simple Model (ASM) 2D chromatograms (
.json) - ANDI (Analytical Data Interchange) Chromatography & MS formats (
.cdf) - mzML (
.mzml) & mzXML (.mzxml) (via RaMS) - ‘Shimadzu LabSolutions’ ascii (
.txt) - ‘Shimadzu GCsolution’ data files (
.gcd) - ‘Shimadzu GCMSsolution’ data files (
.qgd) - ‘Shimadzu LabSolutions’
.lcd(PDA, QTOF, TLM (triple quadrupole MS), TIC, chromatogram, and peak table streams) - ‘Lumex’
.mdffiles - ‘Thermo Scientific Chromeleon’ ascii (
.txt) - ‘Varian Workstation’ (
.SMS) - ‘Waters Empower’ ascii (
.arw) - ‘Waters MassLynx’
.rawdirectories (2D chromatograms only) - Chromatotec
.Chromfiles.
External Libraries
Entab (Entab requires separate installation, see instructions below)
- Agilent ChemStation (
.ch,.fid,.ms,.mwd, &.uv) - Agilent MassHunter DAD (
.sp) - Thermo RAW (
.raw)
ThermoRawFileParser (requires separate installation, see instructions below)
- Thermo RAW (
.raw)
Usage
Importing chromatograms
The central function of chromConverter is read_chroms, a wrapper around all of the supported parsers. To convert a set of files, call read_chroms, specifying the paths to a vector of directories or files and the appropriate file format (format_in), such as chemstation_uv, shimadzu_lcd, cdf or mzml. See ?read_chroms for the full list of values and Formats above for what each parser covers.
library(chromConverter)
dat <- read_chroms(path, format_in = "chemstation_uv")read_chroms chooses a parser and works out whether you’ve provided directories or files. To be explicit, set the parser and find_files arguments: find_files = FALSE means paths are files, and find_files = TRUE means they are directories to search.
Exporting files
To export the files as they are read, give the file format (export_format) and the directory to write them to (path_out). Reading Thermo RAW files or using parser = "openchrom" also writes files, so read_chroms asks for path_out in those cases too; if it is not given, you are offered a temp folder in the working directory.
library(chromConverter)
dat <- read_chroms(path, find_files = FALSE, path_out = "temp",
export_format = "csv")Choosing between multiple parsers
For formats where multiple parsers are available, you can choose between them using the parser argument. For example, ‘Agilent’ files can be read by parsers from several external libraries, including Entab and rainbow. Some of these parsers must be installed manually as described in the installation instructions.
Extracting metadata
chromConverter can extract metadata from the files it reads. If read_metadata = TRUE, metadata will be extracted and stored as attributes of the associated object. The metadata can then be accessed using the attributes or attr functions on individual chromatograms, or extracted into a data.frame or tibble from a list of chromatograms using the extract_metadata function.
Importing peak lists
The read_peaklist function imports peak lists from ‘Agilent ChemStation’ REPORT files, ‘Shimadzu’ ascii, .lcd and .gcd files, and ‘Chromatotec’ .Chrom files. The syntax is similar to read_chroms. In the simplest case, you can just provide paths to the files or directory you want to read in along with the format (format_in), e.g.
Optional dependencies
Some of the parsers rely on external software libraries that must be manually installed.
Entab
Entab is a Rust-based parsing framework for converting a variety of scientific file formats into tabular data. To use parsers from Entab, you must first install Rust and Entab-R. After following the instructions to install Rust, you can install Entab from GitHub as follows:
pak::pak("bovee/entab/entab-r")ThermoRawFileParser
Thermo RAW files can be converted by calling the ThermoRawFileParser on the command-line. To install the ThermoRawFileParser, follow the instructions here. If you are running Linux or macOS, you will also need to install mono, following the instructions provided at the link. In addition, when you use chromConverter to convert Thermo RAW files for the first time you will be asked to enter the path to the program.
OpenChrom
Note: Support for the command-line interface was removed from OpenChrom in version 1.5.0. Version 1.4, which is required for command-line use, is no longer available for download. The instructions below are preserved for users who already have it installed.
OpenChrom is free chromatography software containing a large number of file parsers, which can be called from R. Configuring OpenChrom for command-line use deactivates its graphical user interface (GUI), so keep a second copy of OpenChrom if you also want the GUI. To use the OpenChrom parsers, follow the steps below:
- OpenChrom version ≤ 1.4 is no longer available from Lablicate. If you have version 1.4 and use the command-line interface, keep a backup of it.
- If you intend to use the GUI in the future, make a separate copy of OpenChrom for command-line use.
- Call
read_chromswithparser = "openchrom". The first time you call the parser, you may be asked to provide the path to your local installation of OpenChrom. The path will then be saved for future use. If the command-line interface is disabled, you will be given the option to automatically activate the command-line. Alternatively, the command-line option can be activated from R by callingconfigure_openchrom(cli = "true")or following the instructions to manually activate the CLI. This process can be reversed using the same function: e.g.configure_openchrom(cli = "false"). To specify an OpenChrom executable in a non-standard location, callconfigure_openchromwith thepathargument, e.g.configure_openchrom(cli = "true", path = "path_to_openchrom_executable"). - Specify the detector category with
format_in, since the OpenChrom parsers are organized by detector type rather than by file format:csdfor current selective detectors (e.g. FID, ECD, NPD),msdfor mass selective detectors, orwsdfor wavelength selective detectors (e.g. DAD, UV/VIS).
Further analysis
For downstream analyses of chromatographic data, see chromatographR. For interactive visualization of chromatograms, see ShinyChromViewer (alpha release). There is also a vignette providing an introduction to some basic syntax for plotting mass spectrometry data returned by chromConverter in various R dialects (e.g., base R, tidyverse, and data.table).
Contributing
Contributions of source code, ideas, or documentation are always welcome. Please get in touch (preferably by opening a GitHub issue) to discuss any suggestions or to file a bug report. Some good reasons to file an issue:
- You think you’ve found a bug.
- You’re getting a cryptic error message that you don’t understand.
- You have a file format you’d like to read that isn’t currently supported by chromConverter. (Please make sure to attach example files or a link to the files).
- There’s another new feature you’d like to see implemented.
Note: Before filing a bug report, please make sure to install the latest development version of chromConverter from GitHub, in case your bug has already been patched. After installing the latest version, you may also need to refresh your R session to remove the older version from the cache.