Package {chromConverter}

Title:	Chromatographic File Converter
Version:	0.11.2
Maintainer:	Ethan Bass <ethanbass@gmail.com>
Description:	Reads chromatograms from binary formats into R objects. Currently supports conversion of 'Agilent ChemStation', 'Agilent MassHunter', 'Agilent OpenLab', 'Shimadzu LabSolutions', 'ThermoRaw', 'Varian Workstation', and 'Waters Empower' files as well as various other formats. In addition to its internal parsers, chromConverter contains bindings to parsers in external libraries, such as 'Aston' https://github.com/bovee/aston, 'Entab' https://github.com/bovee/entab, 'rainbow' https://rainbow-api.readthedocs.io/, and 'ThermoRawFileParser' https://github.com/compomics/ThermoRawFileParser. The suggested packages 'entab' and 'chromConverterExtraTests' are not on CRAN: both are available from the repository given in 'Additional_repositories', and the latest test fixtures can also be installed from https://github.com/ethanbass/chromConverterExtraTests.
License:	GPL (≥ 3)
URL:	https://ethanbass.github.io/chromConverter/, https://github.com/ethanbass/chromConverter/
BugReports:	https://github.com/ethanbass/chromConverter/issues/
Depends:	R (≥ 4.1.0)
Imports:	bitops, fs, purrr, readxl, reticulate (≥ 1.41.0), stringr, tidyr, utils, RaMS, tibble, xml2, bit64, data.table, base64enc, jsonlite, digest
Suggests:	entab, ncdf4, pbapply, testthat (≥ 3.1.7), mzR, chromConverterExtraTests, withr, knitr, rmarkdown
VignetteBuilder:	knitr
Encoding:	UTF-8
Language:	en-US
Additional_repositories:	https://ethanbass.github.io/drat/
Config/testthat/edition:	3
Config/Needs/website:	rmarkdown, ggplot2, dplyr
Config/roxygen2/version:	8.1.1
NeedsCompilation:	no
Packaged:	2026-10-25 03:05:13 UTC; ethanbass
Author:	Ethan Bass [aut, cre], James Dillon [ctb, cph] (Author and copyright holder of source code adapted from the 'Chromatography Toolbox' for parsing 'Agilent' FID files.), Evan Shi [ctb, cph] (Author and copyright holder of source code adapted from 'rainbow' for parsing 'Agilent' UV files.), Roderick Bovee [ctb, cph] (Author and copyright holder of source code adapted from 'Aston' for parsing 'Agilent ChemStation' register files.)
Repository:	CRAN
Date/Publication:	2026-10-25 14:30:19 UTC

Subset a chrom_list object

Description

Extracts a subset of a chrom_list while preserving its class, so the result remains a chrom_list rather than a plain list. Of the list's own attributes, only warped, which chromatographR's correct_rt sets on aligned chromatograms, is kept, since a subset of aligned chromatograms is still aligned.

Usage

## S3 method for class 'chrom_list'
x[i, ...]

Arguments

Value

A chrom_list containing the selected elements.

Add metadata to a list of chromatograms

Description

Attaches the columns of a table to the chromatograms of a chrom_list as metadata fields, matching each row to a sample by name. The new fields can then be used by subset.chrom_list and requested from extract_metadata. Where an element holds several chromatograms, such as the traces read_agilent_d returns for each .D directory, every one of them gets the sample's values.

Usage

add_metadata(chrom_list, metadata, by = "name", overwrite = FALSE)

Arguments

Value

chrom_list with the columns of metadata attached to its chromatograms, and their names recorded in an added_metadata attribute, from which chromatographR's get_peaktable fills its sample_meta. A sample without a row in metadata is left unchanged, with a warning.

See Also

extract_metadata, subset.chrom_list

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
chroms <- read_chroms(path, format_in = "chemstation_ch", pattern = "dad1A",
                      parser = "chromconverter", progress_bar = FALSE)
meta <- data.frame(name = c("MEOH", "BENZOS_1000PPM", "BENZOS_500PPM",
                            "BENZOS_250PPM", "BENZOS_125PPM",
                            "BENZOS_62,5PPM", "BENZOS_31,25PPM",
                            "BENZOS_16PPM", "BENZOS_8PPM", "BENZOS_4PPM"),
                   ppm = c(0, 1000 / 2^(0:8)))
chroms <- add_metadata(chroms, meta)
extract_metadata(chroms, what = "ppm")
names(subset(chroms, ppm >= 250))

Shimadzu GC-FID alkane ladder

Description

An ASCII export from 'Shimadzu LabSolutions' of a GC-FID run (GC-2014) of an n-alkane ladder with nonadecane (C19) added, sampled by solid-phase microextraction, holding its peak table of 83 peaks and the chromatogram, recorded every 40 ms for 44 minutes. Find it with system.file("extdata", "alkane_ladder.txt", package = "chromConverter").

License

Released under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/).

Source

Andrew W. Legan (https://orcid.org/0000-0001-7049-9837). The binary file of the same run is FS19_214.gcd in 'chromConverterExtraTests'.

Benzoxazinoid standards

Description

A calibration series of a mixed benzoxazinoid standard, run by HPLC with an 'Agilent' diode array detector (G1315A), as ten 'ChemStation' .D directories in extdata. Find them with system.file("extdata", "benzoxazinoid_standards", package = "chromConverter").

Details

• BENZOS_1000PPM.D to BENZOS_4PPM.D: nine twofold dilutions from 1000 ppm, injected between 20 and 22 June 2023. The names round the last three, which are 15.625, 7.8125 and 3.90625 ppm.

• MEOH.D: a methanol blank, run with the same method on 15 June 2023.

Each directory holds the 254 nm trace (dad1A.ch) and the 'ChemStation' report (Report.TXT). BENZOS_250PPM.D also holds the traces at 230, 320, 360 and 210 nm (dad1B.ch to dad1E.ch), and the pump's pressure, flow and solvent composition through the run (LCDIAG.REG), which read_agilent_d returns with what = "instrument".

The standard gives four peaks at 254 nm, eluting in the 250 ppm run at 12.5 (DIBOA), 19.1 (DIMBOA), 21.0 (BOA) and 28.2 minutes (MBOA).

License

These files are released under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/).

See Also

vignette("chromConverter"), which works through these files.

Combine chrom_list objects

Description

Combines chrom_list objects, or a mix of chrom_list objects and plain lists of chromatograms, into a single chrom_list, preserving the class.

Usage

## S3 method for class 'chrom_list'
c(...)

Arguments

Value

A chrom_list containing all elements.

Call Entab

Description

Converts chromatography data files using entab parsers. 'entab' detects the file format itself. Mass spectra are always returned in long format.

Usage

call_entab(
  path,
  data_format = c("wide", "long"),
  format_out = c("matrix", "data.frame", "data.table"),
  format_in = "",
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw")
)

Arguments

Value

A chromatogram in the format specified by the format_out and data_format arguments.

See Also

Other external parsers: call_openchrom(), call_rainbow(), read_thermoraw(), sp_converter(), uv_converter()

Examples

## Not run: 
call_entab("path/to/file.uv", format_in = "chemstation_uv")

## End(Not run)

Parse files with OpenChrom

Description

Converts files with the OpenChrom command-line interface, then reads the converted files back into R. OpenChrom removed the command-line interface in version 1.5.0, and Lablicate no longer distributes older versions, so this function works only with an existing installation of OpenChrom 1.4 or earlier. It is deprecated for that reason.

Usage

call_openchrom(
  files,
  path_out = NULL,
  format_in,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  export_format = c("mzml", "csv", "cdf", "animl"),
  return_paths = FALSE,
  verbose = getOption("verbose")
)

Arguments

Details

The call_openchrom function works by creating an xml batchfile and feeding it to the OpenChrom command-line interface. OpenChrom batchfiles consist of InputEntries (specifying the files you want to convert) and ProcessEntries (specifying what you want to do to the files). The parsers are organized into broad categories by detector-type and output format. The detector-types are msd (mass selective detectors), csd (current selective detectors, e.g., FID, ECD, NPD), and wsd (wavelength selective detectors, e.g., DAD, and UV/VIS). Thus, when calling the OpenChrom parsers, one of these three options must be specified using the format_in argument.

Value

If return_paths is FALSE, a list with one chromatogram per file, read back with read_mzml, read_cdf or read.csv according to export_format. format_out and data_format apply only to cdf files, except that format_out = "matrix" also converts csv files. animl files cannot be read back, so use return_paths = TRUE for them. If return_paths is TRUE, a character vector of paths to the newly created files.

Side effects

Chromatograms are exported in the format specified by export_format to the folder specified by path_out.

Note

Activating the OpenChrom command-line deactivates the graphical user interface (GUI). To keep using the GUI, install a second copy of OpenChrom and call that one from R.

Author(s)

Ethan Bass

References

Wenig, Philip and Odermatt, Juergen. OpenChrom: A Cross-Platform Open Source Software for the Mass Spectrometric Analysis of Chromatographic Data. BMC Bioinformatics 11, no. 1 (July 30, 2010): 405. doi:10.1186/1471-2105-11-405.

See Also

Other external parsers: call_entab(), call_rainbow(), read_thermoraw(), sp_converter(), uv_converter()

Examples

## Not run: 
call_openchrom("path/to/file.RAW", format_in = "msd", export_format = "mzml")

## End(Not run)

Call 'rainbow' parsers

Description

Parse 'Agilent' or 'Waters' files with rainbow parsers.

Usage

call_rainbow(
  path,
  format_in = c("agilent_d", "waters_raw", "masshunter", "chemstation", "chemstation_uv",
    "chemstation_fid", "chemstation_ms"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  by = c("detector", "name"),
  what = NULL,
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE,
  precision = 1,
  sparse = TRUE,
  bin_width = NULL,
  centroid = FALSE,
  hrms = FALSE
)

Arguments

Details

Uses rainbow parsers to read in Agilent (.D) and Waters (.raw) files. For agilent_d, waters_raw and masshunter, path is the data directory (.D or .raw), and the result is a list grouped according to by. For the chemstation formats, path is a single file (e.g. .uv), the result is a single chromatogram, and by and what are ignored. Otherwise, data can be filtered by detector type using the what argument.

Value

A (nested) list of chromatograms, or a single chromatogram for the chemstation formats, in the class given by format_out. The list is grouped according to the value of by.

Author(s)

Ethan Bass

See Also

Other external parsers: call_entab(), call_openchrom(), read_thermoraw(), sp_converter(), uv_converter()

Examples

## Not run: 
call_rainbow("path/to/file.D", format_in = "agilent_d")

## End(Not run)

Configure 'OpenChrom' parser

Description

Configures OpenChrom to use command-line interface. Requires OpenChrom version prior to 1.5.0.

Usage

configure_openchrom(cli = c("null", "true", "false", "status"), path = NULL)

Arguments

Value

If cli is "status", the string "true" or "false", saying whether the command-line interface is enabled. Otherwise, the path to the OpenChrom command-line application.

Author(s)

Ethan Bass

See Also

call_openchrom

Examples

## Not run: 
configure_openchrom(cli = "status")

## End(Not run)

Configure python environment

Description

Creates a dedicated python virtual environment (or conda environment) with the packages required by the parsers that have python dependencies. This should not be necessary in most cases, since (starting with reticulate v1.41.0) chromConverter declares its python requirements with reticulate::py_require and they are provisioned automatically the first time a python parser is called. It can still be useful if you need a persistent environment, e.g. to work offline or to avoid re-resolving packages. It is an error if an environment named envname already exists.

Usage

configure_python_environment(
  what = c("venv", "conda"),
  envname = "chromConverter",
  parser = c("all", "aston", "rainbow", "olefile"),
  python = NULL,
  ...
)

Arguments

Value

The name of the environment, invisibly.

Side effects

Creates and configures either a python virtual environment or conda environment (according to the value of what) with the packages required for running the specified chromConverter parsers.

Author(s)

Ethan Bass

Extract metadata

Description

Extract metadata as a data.frame, data.table or tibble from a list of chromatograms.

Usage

extract_metadata(
  chrom_list,
  what = chrom_metadata_fields(),
  detector = NULL,
  format_out = c("data.frame", "data.table", "tibble"),
  collapse = FALSE,
  expand = FALSE,
  by = c("sample", "chromatogram"),
  digits = NULL
)

Arguments

Value

A data.frame, tibble, or data.table (according to the value of format_out), with one row per sample or chromatogram (see by) and the specified metadata elements as columns, or NA if none of the specified elements could be found. For a list, the first column, name, identifies each row: by the sample's name, or with by = "chromatogram" by the chromatogram's path through the list (e.g. blue.UV).

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
chroms <- read_chroms(path, format_in = "chemstation_ch", pattern = "dad1A",
                      parser = "chromconverter", progress_bar = FALSE)
extract_metadata(chroms, what = c("sample_name", "run_datetime", "time_range"))

Generic return (2D)

Description

Generic return (2D)

Value

A 2D chromatogram in the format specified by data_format and format_out. If data_format is wide, the chromatogram will be returned with retention times as row names and a single column for the intensity. If long format is requested, two columns will be returned: one for the retention time and one for the intensity. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached to the chromatogram as attributes if read_metadata is TRUE.

Generic return (3D)

Description

Generic return (3D)

Value

A 3D chromatogram in the format specified by data_format and format_out. If data_format is wide, the chromatogram will be returned with retention times as row names and wavelengths as columns. If long format is requested, three columns will be returned: one for the retention time, one for the wavelength and one for the intensity. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached to the chromatogram as attributes if read_metadata is TRUE.

Get one element of each sample

Description

Extracts the same element from every sample of a chrom_list whose samples are themselves lists, such as the output of read_chroms with several what values (e.g. c("dad", "instrument")). The result has one chromatogram per sample, which packages that expect a list of chromatograms, such as chromatographR, accept as is.

Usage

get_element(x, what)

Arguments

Value

A list of the extracted chromatograms, with the names and class of x.

See Also

read_chroms, extract_metadata

Examples

path <- system.file("extdata", "benzoxazinoid_standards", "BENZOS_250PPM.D",
                    package = "chromConverter")
run <- read_chroms(path, format_in = "agilent_d",
                   what = c("chroms", "instrument"), progress_bar = FALSE)
pressure <- get_element(run, "instrument:PMP1, Pressure")
head(pressure[[1]])

Print a chrom_list object

Description

Prints a summary of a chrom_list without displaying the underlying chromatographic data. Attributes that are constant across all chromatograms are collapsed into a single header line, while varying attributes are shown as a table truncated to the first n rows. When a sample holds more than one chromatogram, its traces are printed as a block headed by the sample, and any attribute they all share is shown in that block's header rather than repeated down it.

Usage

## S3 method for class 'chrom_list'
print(
  x,
  n = 10,
  cols = chrom_summary_cols(),
  digits = getOption("digits"),
  ...
)

Arguments

Value

Invisibly returns x.

See Also

extract_metadata

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
chroms <- read_chroms(path, format_in = "chemstation_ch", pattern = "dad1A",
                      parser = "chromconverter", progress_bar = FALSE)
print(chroms)

Read 'Agilent' ACAML files

Description

Extracts injection metadata from 'Agilent Common Analytical Markup Language' (ACAML) files into a table.

Usage

read_acaml(
  path,
  find_files,
  format_out = c("data.frame", "data.table", "tibble"),
  progress_bar = FALSE,
  cl = 1
)

Arguments

Details

ACAML is an XML-based format used by Agilent OpenLab to store sequence and sample metadata. This function extracts information from the InjectionMetaData nodes embedded in the InjectionMetaDataItems custom field files, which do not seem to be readily accessible through other means.

Value

A data.frame, data.table or tibble (according to the value of format_out) with one row per injection, and a SourceFile column naming the ACAML file it came from.

Examples

## Not run: 
read_acaml(path)

## End(Not run)

Read Agilent AMX method file

Description

Parses an Agilent .amx method archive, extracting instrument parameters from one or more of its driver sub-files.

Usage

read_agilent_amx(
  path,
  what = c("dad", "pump", "comp", "sampler"),
  path_out = NULL,
  format_out = c("data.frame", "tibble", "data.table"),
  gradient_format = c("wide", "long")
)

Arguments

Value

A named list with one element per parsed module, plus "metadata". A module the archive has no driver file for is left out with a warning, and it is an error if none of the requested modules has one. The comp module is returned as column and sampler as autosampler. See below for the structure of each.

metadata — a list with scalar elements:

method_name

Original method name.

version

Method version string.

status

Approval state.

created

Creation timestamp (POSIXct, UTC).

created_by

Username of creator.

modified

Last-modified timestamp (POSIXct, UTC).

modified_by

Username of last modifier.

pump — a list with scalar elements flow_mL_min, stop_time_min, post_time_min, pressure_low_bar, pressure_high_bar, plus:

solvents

A table of active solvent channels: channel (e.g. "A"), percentage and solvent (its name, or NA).

gradient

A table of timetable entries. Wide format (default): time_min plus one ⁠pct_<channel>⁠ column per active channel, and a flow_mL_min column if the timetable changes the flow. Long format: time_min, channel, percent, where a flow channel holds the flow in mL/min.

dad — a list with scalar elements peakwidth_code, slitwidth_nm, uv_lamp_required, vis_lamp_required, spectra_from_nm, spectra_to_nm, spectra_step_nm, plus:

signals

A table of active signals: id (e.g. "A"), wavelength_nm, bandwidth_nm, reference_nm and reference_bandwidth_nm (NA without a reference).

peakwidth_code is the stored code for the detector's peak width setting, which sets its data rate and response time; for example, 4 is "> 0.1 min". It is not decoded, since detector models offer different settings.

column — a list with scalar element post_time_min, plus:

temp_controls

Two-row table (Left/Right): side, temperature_C, not_ready_limit_C, equilibration_time_min.

autosampler — a list with scalar elements: thermostat_installed, draw_speed_uL_min, eject_speed_uL_min, wait_after_draw_min, injection_volume_uL, wash_time_s.

Examples

## Not run: 
read_agilent_amx(path)

## End(Not run)

Read files from 'Agilent ChemStation' .D directories

Description

Reads the .ch, .uv, Report.TXT (or Result.xml) and LCDIAG.REG files in an 'Agilent' .D directory. Other files in the directory are ignored.

Usage

read_agilent_d(
  path,
  what = c("dad", "chroms", "peak_table", "MS1", "TIC", "BPC"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE
)

Arguments

Details

Instrument traces are named from LCDIAG.REG, so the names differ between 'ChemStation' revisions and/or instruments (e.g. "PMP1, Pressure" and "PMP1, PMP1A, Pressure"). Parts of the file that cannot be read are skipped with a warning.

Mass spectra are read from the AcqData folder of a 'MassHunter' .d directory. Its MSScan.bin and MSScan.xsd describe every scan, as in read_agilent_dx, and the spectra are in MSPeak.bin, or in MSProfile.bin for profiles. Each profile starts with its first m/z and the step between points, as two doubles or two 32-bit floats, followed by the intensities as 32-bit floats or integers respectively. The points are spaced by the scan's SamplingPeriod rather than the stored step, which can be slightly smaller. Only spectra at MS level 1 can be read, and only from unit-resolution instruments such as single quadrupole GC-MS and LC-MS. The TIC and BPC come from the record of every scan, so they are also returned for runs whose spectra cannot be read, such as triple quadrupole MRM. For high-resolution spectra, try parser = "rainbow" with centroid or hrms.

Value

A list with one element per type found, each a chromatogram or a list of them named by file, in the format specified by format_out and data_format. If data_format is wide, the chromatograms will be returned with retention times as rows and columns containing signal intensity for each signal. If long format is requested, retention times will be in the first column. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame or data.table. Peak tables are returned in the chromatographr layout described in read_peaklist, named by wavelength (e.g. "254"), and keep the report's name for the signal as signal_descriptor. They are read from Result.xml where the directory has one, since unlike Report.TXT it records where each peak starts and ends. Mass spectra and the BPC are always in long format, with rt, mz and intensity columns, and are returned as a data.table when format_out is matrix. Metadata are attached as attributes if read_metadata is TRUE. With collapse = TRUE, a list of one element is replaced by that element.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

path <- system.file("extdata", "benzoxazinoid_standards", "BENZOS_250PPM.D",
                    package = "chromConverter")
run <- read_agilent_d(path)
names(run$chroms)
pump <- read_agilent_d(path, what = "instrument")
names(pump)

Read 'Agilent' DX files

Description

Reads 'Agilent' .dx files.

Usage

read_agilent_dx(
  path,
  what = c("chroms", "dad"),
  path_out = NULL,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE
)

Arguments

Details

The archive is extracted to path_out, or to a temporary directory that is deleted afterwards, and its .ch, .uv and .it files are read with read_chemstation_ch, read_chemstation_uv and an internal reader for .it files.

The mass spectra of an MS injection are not in the archive. They are in the .MSScan.bin and .MSPeak.bin files of the same name beside it. The first is needed for MS1, TIC and BPC, the second for MS1. MSScan.bin holds one record per scan, laid out as the archive's MSData/MSScan.xsd describes, which gives the retention time, TIC and base peak of the scan and the location of its spectrum in MSPeak.bin. Each spectrum there is the scan's m/z values followed by as many intensities, as 32- or 64-bit floats or 32-bit integers depending on the scan's spectrum format and size. Only scans at MS level 1 are read into MS1, while the TIC and BPC cover every scan.

Where the archive holds an injection.acmd file, the run_datetime and sample_injection_volume attributes are taken from it. Its run time records the offset from UTC, while the .ch and .uv headers give only the local time.

Value

A list with one element per type in what, each a chromatogram or a list of chromatograms named by signal, in the format specified by format_out and data_format. Mass spectra and the BPC are always in long format, with rt, mz and intensity columns, and are returned as a data.table when format_out is matrix. With collapse = TRUE, a list of one element is replaced by that element.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

## Not run: 
read_agilent_dx(path)

## End(Not run)

Read files from 'Agilent' .rslt directories

Description

Reads a sequence of injections from an 'Agilent' .rslt directory. Combines raw chromatogram data from .dx files with injection-level metadata parsed from the accompanying .acaml file.

Usage

read_agilent_rslt(
  path,
  what = c("chroms", "dad"),
  path_out = NULL,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE,
  sample_names = c("basename", "sample_name"),
  progress_bar = FALSE,
  cl = 1
)

Arguments

Details

Currently this function only reads .dx chromatogram files. To read the peak tables stored in .rx files, use read_peaklist with format_in = "openlab".

Value

A list of chromatograms (one read_agilent_dx-style result per injection in the sequence), in the format specified by data_format and format_out. If read_metadata is TRUE, injection-level metadata parsed from the .acaml file is attached to each chromatogram as attributes.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

## Not run: 
read_agilent_rslt("path/to/sequence.rslt")

## End(Not run)

Read 'Allotrope Simple Model' (ASM) files

Description

Reads chromatograms, mass spectra and peak lists from 'Allotrope Simple Model' chromatography files into R.

Usage

read_asm(
  path,
  what = c("chroms", "MS1"),
  data_format = c("wide", "long"),
  format_out = c("matrix", "data.frame", "data.table"),
  peaktable_format = c("chromatographr", "original"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE
)

Arguments

Details

Retention times in seconds are converted to minutes. Other units, such as retention volumes (mL), are returned as the file declares them. The unit is recorded in the time_unit attribute.

A file can hold several injections, such as a sequence exported from a chromatography data system. Each injection is then returned as a separate sample, named by its sample name, and read_chroms adds each one to the list of samples it returns.

Mass spectra have so far only been tested against the example files published by the Allotrope Foundation.

Value

A 2D chromatogram in the format specified by format_out and data_format, or a list of them named by detection type if the file holds more than one (or collapse = FALSE). Mass spectra are returned as a data.frame (or data.table) with columns rt, mz and intensity, and peak tables as a data.frame (or data.table) per measurement. Instrument traces are returned as 2D chromatograms named by trace. Where more than one of these is returned, they are combined in a list named by what. A file with several injections returns a chrom_list with one such element per injection. Metadata are attached as attributes if read_metadata is TRUE.

Author(s)

Ethan Bass

Examples

## Not run: 
read_asm("path/to/file.json")
read_asm("path/to/file.json", what = "peak_table")

## End(Not run)

Read CDF

Description

Reads 'Analytical Data Interchange' (ANDI) netCDF (.cdf) files.

Usage

read_cdf(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  what = NULL,
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE,
  peaktable_format = c("chromatographr", "original"),
  ...
)

Arguments

Details

Retention times are returned in minutes, converted from the unit the file declares. An ANDI chrom file declares it in its retention_unit attribute, which also governs the peak table. Seconds is both what the template uses and what all but one of its conformance files declare, so a file that declares no unit is read as seconds, unless chromConverter wrote it, in which case it is read as minutes.

An ANDI MS file has no mandatory unit attribute, since the specification never formally defined its axes units, so scan_acquisition_time is read as seconds, the only unit the specification suggests, unless a raw_data_time_units attribute says otherwise.

Either kind of file warns about a unit it does not recognize and reads it as seconds.

Some writers that do not record peak heights fill peak_height with -1 or 0 for every peak. A chromatographr peak table returns NA heights in these cases.

Value

A chromatogram in the format specified by the format_out and data_format arguments.

Author(s)

Ethan Bass

Examples

## Not run: 
read_cdf("path/to/file.cdf")

## End(Not run)

Read 'Agilent ChemStation' CH files

Description

Reads 'Agilent ChemStation' .ch files.

Usage

read_chemstation_ch(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  scale = TRUE,
  source_file = NULL
)

Arguments

Details

'Agilent' .ch files come in several formats. This parser detects the version from the file and reads versions 8, 30, 130, 81, 179 and 181 from 'Agilent ChemStation' and 'Agilent OpenLab'; any other version is an error. Versions 30 and 130 are generally produced by ultraviolet detectors, and 81, 179 and 181 by flame ionization detectors (FID).

Value

A 2D chromatogram in the format specified by data_format and format_out. If data_format is wide, the chromatogram will be returned with retention times as row names and a single column for the intensity. If long format is requested, two columns will be returned: one for the retention time and one for the intensity. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached to the chromatogram as attributes if read_metadata is TRUE.

Note

This function was adapted from the Chromatography Toolbox (© James Dillon 2014).

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

read_chemstation_ch("tests/testthat/testdata/chemstation_130.ch")

Read 'Agilent ChemStation' CSV files

Description

Reads 'Agilent ChemStation' .csv files.

Usage

read_chemstation_csv(
  path,
  format_out = "matrix",
  data_format = "wide",
  read_metadata = TRUE
)

Arguments

Details

'Agilent ChemStation' CSV files are encoded in UTF-16.

Value

A chromatogram in the format specified by format_out and data_format.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

read_chemstation_csv("tests/testthat/testdata/dad1.csv")

Read 'Agilent ChemStation' log files

Description

Reads the event log 'Agilent ChemStation' writes to the folder of each sequence, or the RUN.LOG it writes to each .D folder when that file is named in paths. These record instrument errors, aborted runs and routine readings such as pump pressure and column temperature.

Usage

read_chemstation_logs(
  paths,
  what = c("injections", "problems", "events"),
  format_out = "data.frame"
)

Arguments

Details

Directories in paths are searched, including their subdirectories, for sequence logs: every .LOG file outside a .D folder. RUN.LOG files are left out, since the sequence log holds their events. A file found this way that is not a 'ChemStation' log is skipped with a warning; a file named in paths that is not one is an error.

Tested on logs from 'ChemStation' revisions A.10.02, B.01.03 and B.04.02.

Value

A data.frame or data.table. For injections, one row per injection, with columns:

• sequence: the name of the 'ChemStation' sequence, taken from the log's own sequence events or, failing those, from the name of the file. NA for a RUN.LOG, which has neither.

• folder: the folder the sequence's data are in, which can differ from sequence. This is the folder holding the log, or for a RUN.LOG the folder holding its .D folder.

• injection: numbers the injections in the order the log starts them.

• data_file: the .D folder the log names for the injection. The log records it only once the run's data are analyzed, so an aborted injection has none, and its case can differ from the folder on disk.

• sample: the sample, as the log names it.

• start: POSIXct, UTC. The run_datetime of the traces and reports in a .D folder is instead the instrument's local time labeled as UTC, so match injections to them by data_file rather than by time.

• minutes: from the injection's first event to its last.

• status: completed, aborted, ⁠stopped by user⁠ or incomplete.

• pressure_start, pressure_end: the first and last reading of pump 1, in bar.

• problems: the injection's problem messages, separated by "; ".

For events, one row per event, with sequence, folder, injection and data_file as above, and:

• time: POSIXct, UTC, as recorded in the event's header. The local time printed in the log's text is not returned.

• problem: whether the event reports an alarm from an instrument module (any event from a module with a non-zero event_code, such as a leak or a shutdown), a method that was aborted, timed out, stopped by an instrument error or stopped by the user, or a sequence that was terminated or stopped.

• event_code, module_id: hexadecimal strings, since 'Agilent' does not document them. The same module always carries the same module_id (for example, ⁠1da6⁠ for the pump in 'Agilent 1100' logs).

• source: e.g. "1100 PMP 1", "Method" or "Sequence".

• message: the event's text. The log splits a message longer than 45 characters over several events, which are joined, but stores a message of exactly 45 characters without its last character.

Events of the sequence itself, events between injections such as loading the next method, and method runs that acquire no data, such as a data-analysis-only re-run of the sequence, have no injection or data_file.

For problems, the events marked as a problem, without that column and with incident, which numbers the runs of problem events in the same log that are less than a minute apart, such as a leak and the shutdowns that follow it.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

read_chemstation_logs("tests/testthat/testdata/chemstation_sequence.LOG")
read_chemstation_logs("path/to/sequences", what = "problems")

Read an 'Agilent ChemStation' method

Description

Reads the pump, diode array detector, autosampler and column thermostat settings from the module register files (LPMP1.REG, LDAD1.REG, LALS1.REG or LWLS1.REG, and LTHM1.REG) of a 'ChemStation' .M method directory. Revisions that store a module's settings as 'RapidControl' XML (e.g. AgilentPumpDriver1.RapidControl.MethodXML.xml) instead are read as 'OpenLab CDS' methods are by read_agilent_amx.

Usage

read_chemstation_method(
  path,
  what = c("pump", "dad", "sampler", "column"),
  format_out = c("data.frame", "tibble", "data.table"),
  gradient_format = c("wide", "long")
)

Arguments

Details

Depending on how 'ChemStation' is configured, a .D directory may hold a copy of the method it was acquired with, in ACQ.M or, in older revisions, RUN.M. path can then be the .D directory itself. Its DA.M holds the data analysis method instead, whose pump settings may not be those the run was acquired with; reading it gives a warning.

The gradient follows the pump's timetable, with each parameter changing linearly between the times it is set. Channel A is the pump's primary channel and delivers whatever the other channels leave, so it is always included and its share is computed rather than read.

Value

A named list with one element per module read. A module the method has no settings for is left out with a warning, and it is an error if none of the requested modules are present. The sampler module is returned as autosampler. The elements are those of read_agilent_amx, with NA for a setting the method does not record:

pump: a list with scalar elements flow_mL_min, stop_time_min, post_time_min, pressure_low_bar and pressure_high_bar, plus:

• solvents: a table of the channels in use, with columns channel, percentage (at the start of the run) and solvent (the name entered for it, or NA).

• gradient: the timetable. Wide format: time_min and a ⁠pct_<channel>⁠ column per channel in use, plus flow_mL_min if the timetable sets the flow. Long format: time_min, channel and percent, where a flow channel holds the flow in mL/min. An empty timetable gives the starting composition at time 0.

dad: a list with scalar elements peakwidth_code, slitwidth_nm, uv_lamp_required, vis_lamp_required, spectra_from_nm, spectra_to_nm and spectra_step_nm, plus signals, a table of the stored signals with columns id, wavelength_nm, bandwidth_nm, reference_nm and reference_bandwidth_nm (NA without a reference). peakwidth_code is the stored code for the detector's peak width setting, which sets its data rate and response time; for example, 4 is "> 0.1 min". It is not decoded, since detector models offer different settings.

autosampler: a list with scalar elements thermostat_installed, draw_speed_uL_min, eject_speed_uL_min, wait_after_draw_min, injection_volume_uL and wash_time_s. Register files record only the speeds and the injection volume.

column: a list with scalar element post_time_min (NA when off), plus temp_controls, a two-row table (Left, Right) with columns side, temperature_C, not_ready_limit_C and equilibration_time_min. A temperature stored below absolute zero (e.g. -274) is NA; this may mean no temperature was set.

Author(s)

Ethan Bass

See Also

read_agilent_amx for 'OpenLab CDS' methods, and read_agilent_d with what = "instrument" for the pump's record of what it delivered.

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_ms(), read_chemstation_reports(), read_chemstation_uv()

Examples

## Not run: 
method <- read_chemstation_method("path/to/METHOD.M")
method$pump$gradient

## End(Not run)

Read 'Agilent ChemStation' MS files

Description

Reads 'Agilent ChemStation MSD Spectral Files' beginning with x01/x32/x00/x00.

Usage

read_chemstation_ms(
  path,
  what = c("MS1", "BPC", "TIC"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = "long",
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE
)

Arguments

Value

A list of the streams in what, in the format specified by format_out. In wide format, the BPC and TIC have retention times as rows and a single intensity column; in long format, a retention time column and an intensity column. MS data will always be returned in long format. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached as attributes if read_metadata is TRUE. With collapse = TRUE, a list of one stream is replaced by that stream.

Note

Many thanks to Evan Shi and Eugene Kwan for providing helpful information on the structure of these files in the rainbow documentation.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_reports(), read_chemstation_uv()

Examples

## Not run: 
read_chemstation_ms(path)

## End(Not run)

Read 'Agilent ChemStation' register files

Description

Reads the instrument traces, the keys and values describing each module, and the tables, such as a pump's timetable, from 'Agilent ChemStation' register (.REG) files. Users reach it through read_agilent_d with what = "instrument" and through read_chemstation_method; this page documents the file format.

Usage

read_chemstation_reg(path)

Arguments

Details

Objects that cannot be parsed are skipped with a warning. Tested on LCDIAG.REG files from revisions A.10.02, B.01.03, B.04.02, B.04.03, C.01.03, C.01.07 and C.01.10, and on method register files from four revision B and C instruments and two revision A instruments.

Value

A list of:

• traces: one row per point of each instrument trace, with columns trace (its title, e.g. "PMP1, Pressure"), unit, time (in minutes) and value.

• conditions: the keys and values stored in every object of the file, with columns object (its title), key and value (as character). Each module's ⁠Start/Stop Conditions⁠ object (e.g. "PMP1, Start/Stop Conditions") records its state at the start and end of the run, such as StartPressure and StopPressure for the pump or ActInjVolume for the autosampler. Every object records the start of the run as DateTime, and the object of a solvent trace gives the solvent's name, where one was entered, as Description.

• tables: a list of data frames, one per table, named by the key holding it, such as TIMETABLE for a pump's timetable.

File format

All integers are little-endian and offsets are counted from 0.

Header. Bytes ⁠02 33 32 00⁠, then the length-prefixed string ⁠REGISTER FILE⁠ at 0x04 and a length-prefixed container version at 0x18: notused in files from revisions B and C, A.xx.xx in files from revision A. At 0x22 is a u32 offset of the object index and at 0x26 a u16 object count. The index holds one 8-byte entry per object, starting with the u32 offset of the object; the index itself begins where the last object ends.

Revision B and C objects. A 12-byte preamble, whose contents differ by revision, then a stream written by the 'MFC' CArchive class. Each object starts with a u16 tag: FFFF introduces a new class (u16 schema, u16 name length, ASCII name); 8000 plus an index refers to a class already read; ⁠7FFF⁠ is followed by a u32 tag for large indices. Class indices restart in every object. The classes are:

• CHPUserObject and CHPLCObject: two objects (the second a list of keys and values), then a flag byte and, if it is set, a data object.

• CHPList: one object. CObArray: a u16 count (FFFF then a u32 count when large) followed by that many objects.

• CHPNdrDouble, CHPNdrString and CHPNdrObject: a key, 6 bytes, then a float64, a string or a flag byte and object. Strings are a u16 length followed by UTF-16LE; a length of C000 is instead followed by a u16 id naming a standard key (0 ObjClass, 1 Title), and 8000 by a u16 index, counted from 0, into the non-empty keys and table column names already read in the object. String values are not counted.

• CHPDatLongSliced and CHPDatDoubleSliced: 6 bytes, then the y row and the x row.

• CHPDatLongRow and CHPDatDoubleRow: 14 bytes, the unit string, u16 7, u16, u32 point count n and a u8 flag marking an implicit row. Unless implicit, n int32 (Long) or float64 (Double) values follow. Then u32, float64 first value, u8, u32 flag marking scaled values, float64 scale and float64 offset. Values are raw x scale + offset if scaled and raw otherwise; an implicit row is first + i x scale.

• CHPTable: a header holding a u16 row size at byte 2, a u16 row count n at byte 4, and the u16 counts of data and extra columns at bytes 20 and 22 (16 and 18 for schema 11). Then an 18-byte descriptor per column (u16 offset in the row, u16 size, u16 type and u16 flags, then 10 bytes); (n + 1) x row size - 4 bytes holding a default row, less its first 4 bytes, then the n rows, followed by the value of each extra column with flag 40; and each column's name, a string whose length counts a terminator. A data column of type 3 with flag 40 is followed by its default and n strings. Type 4 is float32, with -10000 for an empty cell, and type 5 int32. The extra columns are not returned.

• CHPAnnText is read past but not returned.

In LCDIAG.REG each trace is an object whose Title names it. Revision B.01 stores traces as CHPLCObject with CHPDatLong rows and an implicit time axis; B.04 does the same but writes a space before the comma in trace names ("PMP1 , Pressure"), which is removed; revision C stores them as CHPUserObject with unscaled CHPDatDouble rows and explicit, possibly uneven, times. The other objects, titled ⁠Start/Stop Conditions⁠, hold only keys and values.

Revision A objects. One byte, a u32 record count n, n 16-byte record headers (u16, u16 type, u32 size, u32, u32 id), 4n further bytes, then the data of each record in turn. Records refer to one another by id. Types 8001 and 8003 are Latin-1 strings and 8006 a string after 2 bytes; 8002 holds a numeric array; 0602 (43 bytes) a key at byte 14 and float64 at byte 35; 0601 a key and the u32 id of its value at byte 35; 0603 the key of a table and the u32 id of its 0701 record at byte 35. A 0701 record holds a u16 row size at byte 2, a u16 row count n at byte 4, the u32 offset of its rows at byte 6 and a u16 count of data columns at byte 16, then a 30-byte descriptor per column: a 16-byte name, then the u16 offset in the row, size, type and flags, as in revision B and C. The rows are (n + 1) x row size bytes, the first a default row. Types 0501 and 0503 (161 bytes) describe a trace: u32 point count at byte 9, then the u32 ids of the x unit and data and the x scale at bytes 27, 31 and 61, and those of y at bytes 94, 98 and 128. An array id with no record denotes an implicit axis of i x scale.

Not known: the meaning of the skipped bytes, and whether the scale or the offset comes first in a row (every file seen has an offset of 0).

Note

The reader for revision A files was adapted from read_reg_file in Aston (Copyright 2011-2020 Roderick Bovee, BSD 3-clause license).

Author(s)

Ethan Bass

Read 'Agilent ChemStation' report files

Description

Reads peak tables from 'Agilent ChemStation' Report.TXT files, or from the Result.xml files 'ChemStation' writes when set up to export its results. Only Result.xml records where each peak starts and ends, so it is read in preference to a Report.TXT in the same directory.

Usage

read_chemstation_reports(
  paths,
  peaktable_format = c("chromatographr", "original"),
  metadata_format = c("chromconverter", "raw"),
  data_format = NULL
)

Arguments

Value

A peak_list: a list with one element per report, named by its .D directory, each holding one peak table per signal, named by wavelength.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_uv()

Examples

path <- system.file("extdata", "benzoxazinoid_standards", "BENZOS_250PPM.D",
                    "Report.TXT", package = "chromConverter")
read_chemstation_reports(path)

Read 'Agilent ChemStation' DAD files

Description

Agilent .uv files come in several formats. This parser detects the version from the file and reads versions 31 and 131 from 'Agilent ChemStation' and 'Agilent OpenLab'; any other version is an error.

Usage

read_chemstation_uv(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  scale = TRUE,
  source_file = NULL
)

Arguments

Details

Retention times are read from each spectrum, so they are unevenly spaced when the detector did not store every spectrum. Interpolate onto a common time axis before comparing runs.

Value

A 3D chromatogram in the format specified by data_format and format_out. If data_format is wide, the chromatogram will be returned with retention times as row names and wavelengths as columns. If long format is requested, three columns will be returned: one for the retention time, one for the wavelength and one for the intensity. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached to the chromatogram as attributes if read_metadata is TRUE.

Note

This function was adapted from the parser in the rainbow project licensed under GPL 3 by Evan Shi https://rainbow-api.readthedocs.io/en/latest/agilent/uv.html.

Author(s)

Ethan Bass

See Also

Other 'Agilent' parsers: read_agilent_d(), read_agilent_dx(), read_agilent_rslt(), read_chemstation_ch(), read_chemstation_csv(), read_chemstation_logs(), read_chemstation_method(), read_chemstation_ms(), read_chemstation_reports()

Examples

read_chemstation_uv("tests/testthat/testdata/dad1.uv")

Read 'Chromatotec' file

Description

Reads 'Chromatotec' .Chrom files.

Usage

read_chromatotec(
  path,
  what = c("chrom", "peak_table"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE,
  peaktable_format = c("chromatographr", "original")
)

Arguments

Value

A chromatogram and/or peak table from the specified path, according to the value of what, with times in minutes. Chromatograms are returned in the format specified by format_out. The rows of the peak table that report a total over most of the run rather than a peak, such as NMTHC-EqC6 and THC_PAMS, are only kept with peaktable_format = "original". In the original table, Start and End are where integration of the peak starts and ends, and SubstanceIndex appears to be the position of its substance in the run's substance table (0 for an unnamed peak); U1, U3 and U4 have not been identified.

Author(s)

Ethan Bass

Examples

## Not run: 
read_chromatotec(path)

## End(Not run)

Read 'Chromeleon' ASCII files

Description

Reads 'Thermo Fisher Chromeleon™ CDS' ASCII (.txt) files.

Usage

read_chromeleon(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  decimal_mark = NULL
)

Arguments

Value

A chromatogram in the format specified by format_out (retention time x wavelength).

Author(s)

Ethan Bass

Examples

## Not run: 
read_chromeleon("path/to/file.txt")

## End(Not run)

Read Chromatograms

Description

Reads chromatograms from specified folders or vector of paths using either an internal parser or bindings to an external library, such as Aston, Entab, ThermoRawFileParser, OpenChrom, rainbow.

Usage

read_chroms(
  paths,
  format_in = supported_formats(),
  find_files,
  pattern = NULL,
  parser = c("", "chromconverter", "aston", "entab", "thermoraw", "openchrom", "rainbow"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  path_out = NULL,
  export_format = c("", "csv", "chemstation_csv", "cdf", "mzml", "animl", "arw"),
  force = FALSE,
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  progress_bar,
  cl = 1,
  verbose = getOption("verbose"),
  sample_names = c("basename", "sample_name"),
  sort_by = c("auto", "none", "acquisition_time", "file_time"),
  dat = NULL,
  ...
)

Arguments

Details

Provides a unified interface to all chromConverter parsers. The formats it recognizes are listed under the format_in argument. It also wraps the 'OpenChrom' parsers, which cover many additional formats but require 'OpenChrom' 1.4 or earlier (see call_openchrom). The 'Entab', 'ThermoRawFileParser' and 'OpenChrom' parsers must be installed separately; see the instructions in the README.

If paths to individual files are provided, read_chroms infers the file format from the first file and selects a parser for it. When providing paths to directories, the file format must be specified using the format_in argument.

Value

A chrom_list of chromatograms in matrix, data.frame, or data.table format, according to the value of format_out. Chromatograms may be returned in either wide or long format according to the value of data_format. Peak tables are returned in the chromatographr layout described in read_peaklist, which can also return all the columns the file provides.

Side effects

If export_format is provided, chromatograms are written to the folder given by path_out in that format. The options are csv, chemstation_csv, cdf, mzml and arw, as well as animl (AnIML) when an openchrom parser is selected. Files are also written to path_out whenever the thermoraw or openchrom parser is used, as these parsers convert the files before reading them: thermoraw to mzML, and openchrom to export_format (mzml by default).

Author(s)

Ethan Bass

Examples

path <- system.file("extdata/alkane_ladder.txt", package = "chromConverter")
chroms <- read_chroms(path, format_in = "shimadzu_ascii",
                      find_files = FALSE, progress_bar = FALSE)

Read 'Lumex' MDF

Description

Reads 'Lumex' .mdf files.

Usage

read_mdf(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE
)

Arguments

Value

A chromatogram in the format specified by the format_out and data_format arguments.

Author(s)

Ethan Bass

Examples

## Not run: 
read_mdf("path/to/file.mdf")

## End(Not run)

Read mzML files

Description

Extracts data from mzML files using parsers from either RaMS or mzR.

Usage

read_mzml(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  parser = c("RaMS", "mzR"),
  what = c("MS1", "MS2", "BPC", "TIC", "DAD", "chroms", "metadata", "everything"),
  verbose = FALSE,
  ...
)

Arguments

Details

Both parsers return a list with one element per stream in what. Mass spectra and EICs are always long. With data_format = "wide" (the default), TIC and BPC are returned as 2D chromatograms of class format_out, and DAD as a wide chromatogram of class format_out; with "long", every stream is a long data.table.

The chroms stream holds the chromatograms stored in the file, such as the SIM and SRM traces of a triple quadrupole run. In wide format it is a list of 2D chromatograms named by their ID in the file (or ⁠Chromatogram 1⁠, ⁠Chromatogram 2⁠ and so on where it has none), each with the precursor_mz and product_mz it monitors as attributes. If any trace repeats a retention time, as in some malformed files, the whole stream is returned as the long data.table instead, with a warning.

The mzR parser reads files that RaMS cannot, such as those compressed with MS-Numpress. It returns only MS1, MS2, BPC, TIC and DAD, and no file metadata. Its TIC and BPC are the per-scan values recorded in the MS1 spectra.

Value

A named list of the streams in what.

Author(s)

Ethan Bass

Examples

## Not run: 
read_mzml("path/to/file.mzML")

## End(Not run)

Read peak lists

Description

Reads peak lists from specified folders or vector of paths.

Usage

read_peaklist(
  paths,
  find_files,
  format_in = c("chemstation", "shimadzu_fid", "shimadzu_dad", "shimadzu_lcd",
    "shimadzu_gcd", "chromatotec", "asm", "cdf", "openlab"),
  pattern = NULL,
  peaktable_format = c("chromatographr", "original"),
  metadata_format = c("chromconverter", "raw"),
  read_metadata = TRUE,
  progress_bar,
  cl = 1,
  sort_by = c("auto", "none", "acquisition_time", "file_time"),
  data_format = NULL
)

Arguments

Value

A peak_list: a list with one element per sample, holding its peak table, or a list of peak tables where the file records more than one. The tables are named by wavelength (e.g. "254") where the file records one, and otherwise by the file's own name for the signal; a table identical to another at the same wavelength is a copy and is left out. Each row is a peak. Every table starts with a sample column and a lambda column giving the signal's wavelength, which is NA for a detector without one or a file that does not record it, followed by the columns of peaktable_format.

Author(s)

Ethan Bass

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
peak_list <- read_peaklist(path, progress_bar = FALSE)
names(peak_list)
peak_list[["BENZOS_250PPM"]][["254"]]

Read 'Shimadzu' ASCII

Description

Reads 'Shimadzu' ASCII (.txt) files. These files can be exported from 'Shimadzu LabSolutions' by right clicking on samples in the sample list and selecting ⁠File Conversion:Convert to ASCII⁠.

Usage

read_shimadzu(
  path,
  what = "chroms",
  format_in = NULL,
  include = c("fid", "lc", "dad", "uv", "tic"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  peaktable_format = c("chromatographr", "original"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  ms_format = c("data.frame", "list"),
  collapse = TRUE,
  scale = TRUE
)

Arguments

Value

A nested list of elements from the specified file, where the top levels are chromatograms, peak tables, and/or mass spectra according to the value of what, and the chromatograms are grouped by type (e.g. fid). Where collapse is TRUE, a list of one is unwrapped at the top level and within each type of chromatogram. Chromatograms are returned in the format specified by format_out and data_format.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_lcd_3d(), read_sz_tables()

Examples

path <- system.file("extdata/alkane_ladder.txt", package = "chromConverter")
read_shimadzu(path)

Read 'Shimadzu' GCD

Description

Read chromatogram data streams from 'Shimadzu' .gcd files.

Usage

read_shimadzu_gcd(
  path,
  what = "chroms",
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE,
  peaktable_format = c("chromatographr", "original")
)

Arguments

Details

A parser to read chromatogram data streams from 'Shimadzu' .gcd files. GCD files are encoded as 'Microsoft' OLE documents. The parser relies on the olefile package in Python to unpack the files. The chromatogram data is encoded in streams titled ⁠LSS Raw Data:Chromatogram Ch<#>⁠. Each stream begins with a 24-byte header:

• 4 bytes: segment label (17234).

• 4 bytes: Little-endian integer specifying the sampling interval in milliseconds.

• 4 bytes: Little-endian integer specifying the number of values in the stream.

• 4 bytes: Little-endian integer specifying a byte count, which does not match the size of the stream exactly.

• 8 bytes of 00s

After the header, the data are encoded as 64-bit (little-endian) floating-point numbers. Retention times are derived from the number of values and the sampling interval encoded in the header, rather than read from the file: the nth value is placed at n times the sampling interval.

Value

A 2D chromatogram in the format specified by data_format and format_out. If data_format is wide, the chromatogram will be returned with retention times as row names and a single column for the intensity. If long format is requested, two columns will be returned: one for the retention time and one for the intensity. The format_out argument determines whether the chromatogram is returned as a matrix, data.frame, or data.table. Metadata are attached to the chromatogram as attributes if read_metadata is TRUE.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_lcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_lcd_3d(), read_sz_tables()

Examples

## Not run: 
read_shimadzu_gcd("path/to/file.gcd")

## End(Not run)

Read 'Shimadzu' LCD

Description

Read PDA, chromatogram, mass spectrometry and peak table streams from 'Shimadzu' .lcd files.

Usage

read_shimadzu_lcd(
  path,
  what,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  scale = TRUE,
  sparse = TRUE,
  collapse = TRUE,
  peaktable_format = c("chromatographr", "original")
)

Arguments

Details

A parser to read data from 'Shimadzu' .lcd files. LCD files are encoded as 'Microsoft' OLE documents. The parser relies on the olefile package in Python to unpack the files. Each detector writes its own storage, and this function dispatches over them:

• PDA (⁠PDA 3D Raw Data:3D Raw Data⁠), requested as DAD: one delta-encoded segment per retention time, each holding a full spectrum. Read by read_sz_lcd_3d(), which documents the segment header and the delta encoding.

• Chromatograms (⁠LSS Raw Data:Chromatogram Ch<#>⁠): one stream per channel, delta-encoded in the same way. Read by read_sz_lcd_2d().

• Quadrupole time-of-flight mass spectra (⁠QTFL RawData⁠): centroided scans stored as a scan header, a block of flight times and a block of intensities, with the mass axis reconstructed from the calibration table in the file. Read by read_sz_qtof(), which documents the scan header, the flight-time conversion and the intensity scaling. The total ion current is held separately, in ⁠Centroid SumTIC⁠ (read_sz_qtof_tic()).

• Triple quadrupole mass spectra (⁠TLM Raw Data⁠): zlib-compressed scan records located through a spectrum index, covering full scan, product-ion scan, MRM and SIM acquisitions. Read by read_sz_tlm(), which documents the index, the scan header and the layout of each scan type. The total ion current is again held separately, in ⁠TIC Data⁠.

• Peak tables (⁠Peak Table⁠): integration results as reported by 'LabSolutions', one stream per channel. Read by read_sz_tables(), which documents the two record layouts.

The two mass spectrometry containers are mutually exclusive: a file holds one or the other, according to the instrument that wrote it.

A mass spectrometry run is divided into acquisition events: the scan functions defined by the method, each with its own polarity, MS level and mass range, which the instrument cycles through as the run proceeds. The mass spectrometry streams are reported per event — TIC returns one chromatogram for each, and the scan_info attribute of a table of spectra names the event every scan came from.

Value

A named list with one element per stream requested, or the element itself where there is only one and collapse is TRUE. Chromatograms and the PDA data are returned in the format specified by data_format and format_out. In wide format, retention times are the rows, and each 2D chromatogram has a single intensity column while the PDA data have one column per wavelength. If long format is requested, the retention time and the intensity are returned as columns, alongside the detector, channel, wavelength and unit for a 2D chromatogram. The format_out argument determines whether they are returned in matrix, data.frame, or data.table format. Mass spectra and peak tables are always long. Metadata are attached as attributes when read_metadata is TRUE.

Note

Times are stored as a 'Windows' FILETIME, which is always UTC, so run_datetime is reported in UTC. The files also record the offset of the local time zone (e.g. ⁠+01'00'⁠), but this is the standard offset of the zone rather than the offset that was in force, and it seems that no daylight saving information is stored anywhere in the file. The local times displayed by 'LabSolutions' therefore cannot be reconstructed from the recorded offset alone: where daylight saving time applied, they are an hour ahead of it. Rendering run_datetime in the zone where the data were acquired, e.g. format(attr(x, "run_datetime"), tz = "Europe/Paris"), recovers them exactly.

As of v0.10.0, 2D chromatograms are scaled by the calibration factor and the value factor recorded for each channel, so their intensities match those reported by 'LabSolutions'. An absorbance axis can be reported in uAU, mAU or AU, and the file records the size of each as a value factor: 1, 1000 and 1e6, since one mAU is a thousand uAU and one AU a million. The smallest of them is the base unit, while 'LabSolutions' displays the data in whichever unit the method selected, usually mAU. Other detectors work the same way: a refractive index axis measures in nRI and displays uRI.

Two factors separate the stored integers from the displayed value. The calibration factor converts an integer into base units, and the value factor converts base units into the displayed unit; an intensity as 'LabSolutions' reports it is the integer times the one divided by the other. The calibration factor is 1 on some channels and not on others (e.g. about 0.024 for an SPD-20A and 0.0032 for an RID-10A), which suggests the integers are detector counts whose size varies by module, though the file does not say so.

For a 2D chromatogram, scale = TRUE applies both factors. scale = FALSE returns the stored integers. Where the calibration factor is 1, their detector_y_unit is the base unit (e.g. uAU), and the values and the attribute agree. Where it is not, the integers are in no unit we can name, so detector_y_unit is NA; the scaled attribute records which of the two was returned.

PDA data is instead returned as it is encoded in the file, matching the ⁠[PDA 3D]⁠ section of a 'LabSolutions' ASCII export, which declares no intensity unit or multiplier. The ⁠3D Data Item⁠ describes the absorbance axis in mAU with a value factor of 1000, which would imply scaling the values by 0.001, but the ⁠[PDA Multi Chromatogram]⁠ traces in the ASCII export, which are extracted from the same data, report values on the same scale as the raw data with a multiplier of 1. Until this can be resolved, PDA data is left unscaled and the scale argument is ignored.

⁠Max Plot⁠ is the maximum absorbance over the wavelength range at each point in time, so the value at one time can come from a different wavelength than the value at the next, and no single wavelength describes the trace. It is derived from the PDA data but is read as a 2D chromatogram, so it is scaled and currently differs from the PDA data by a factor of 1000. The wavelength range it was taken over is not recorded in the ⁠2D Data Item⁠, whose nanometer axis spans 0 to 0, so its wavelength attribute is NA rather than the acquisition range of the PDA stream.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_lcd_3d(), read_sz_tables()

Examples

## Not run: 
read_shimadzu_lcd(path)

## End(Not run)

Read a 'Shimadzu' method

Description

Reads the instrument settings stored with a 'Shimadzu' GC run (.gcd), LC run (.lcd) or GC-MS run (.qgd), such as the oven program, gradient, flows and column.

Usage

read_shimadzu_method(
  path,
  what = NULL,
  format_out = c("data.frame", "tibble", "data.table")
)

Arguments

Details

Method parameters are attached automatically to every chromatogram and peak table read from these files, in the method_params metadata field. This includes all scalar values but leaves out the oven program, gradient and other tables, which are only returned by this function. The ms module of a GC-MS or LC-MS run is attached as ms_params.

Value

A named list with one element per module.

For GC runs:

oven: a list with scalar elements equilibration_time_min, initial_temperature_C and initial_hold_min, plus program, a table of the temperature ramps with columns rate_C_min, temperature_C and hold_min.

injector: a list with scalar elements name, temperature_C, split_ratio, column_flow_mL_min, linear_velocity_cm_s, pressure_kPa, total_flow_mL_min and purge_flow_mL_min.

detector: a list with scalar elements name, temperature_C, h2_flow_mL_min, air_flow_mL_min, makeup_flow_mL_min and sampling_rate_ms.

autosampler: a list with scalar element injection_volume_uL.

column: a list with scalar elements name, length_m, diameter_mm, film_thickness_um, max_temperature_C and serial_number.

For GC-MS runs, oven, injector, autosampler and column as for GC runs, and ms, a list with scalar elements start_time_min and end_time_min (the window in which the mass spectrometer acquires), ion_source_temperature_C, interface_temperature_C and event_time_s. Files without the labeled method (e.g. from a GC-2010) record no equilibration_time_min, injector name or pressure_kPa, injection_volume_uL, column diameter_mm or film_thickness_um, or interface_temperature_C, which are then NA. A split ratio of -1 appears to mean the split is off. The injector settings are the values at the start of the run; a method may program the pressure or purge flow to change later, so a purge flow of 0 can be the start of a purge program.

For LC runs:

pump: a list with scalar elements mode, the abbreviation 'LabSolutions' stores for the pump mode (e.g. ISO, BGE or LPGE), flow_mL_min and stop_time_min, plus gradient, a table with columns time_min and pct_B, and solvents, a table of the mobile phase names entered in the method, with columns pump, line and solvent, or NULL if none were entered. The gradient starts from the pump's initial concentration of B at time 0 and changes linearly between the times listed. It is NULL for an isocratic run whose time program sets no concentration. flow_mL_min is NA if the method sets no flow.

column: a list with scalar element temperature_C, the temperature of the column oven, which is NA if the oven is not in use.

ms: the ion source interface of a single or triple quadrupole mass spectrometer, a list with scalar elements dl_temperature_C, the temperature of the desolvation line (CDL on single quadrupole instruments), and heat_block_temperature_C. It is attached to the chromatograms as ms_params.

dad: the PDA detector, a list with scalar elements start_wavelength_nm, end_wavelength_nm, sampling_interval_ms, end_time_min and cell_temperature_C (NA if the cell is not thermostatted), plus channels, a table of the channels the acquisition method extracts, with columns channel, wavelength_nm and bandwidth_nm. Data processing can change these channels; the wavelengths of the peak tables are those of the processed channels.

File format

.gcd and .lcd files store the method and instrument configuration as labeled XML, in the GUC.1.METHOD and GUC.1.CONFIG streams, and the PDA settings in PDA.1.METHOD. The settings of a single or triple quadrupole mass spectrometer are records stored as hex in the same XML, in the LCMS unit of its own GUC.1.METHOD or GUM.METHOD stream; of these, only the interface record (Ifs) is read, whose DL and heat block temperatures are uint16 in hundredths of a degree at bytes 70 and 74. They were checked against a method printout for an 'LCMS-2020' and the published method of an 'LCMS-8040'.

.qgd files from a GC-2030 (e.g. with a 'GCMS-QP2020 NX') also hold the GC method and configuration as labeled XML, in ⁠GCMS Configuration/GUC_GC2⁠, and their oven, injector, autosampler and column settings are read from it as for .gcd files. Every .qgd file stores the method as unlabeled binary records, one stream per module, at fixed byte offsets, which are read for the other settings and for files without the XML. Values are little-endian float32 unless marked otherwise, and bytes not listed are not read. The same streams are found in files from 'GCMS-QP2010' and 'QP2020 NX' instruments:

• ⁠GC-2010 Instrument Parameters/Column Oven Parameter⁠, 260 bytes:

  • 8: the number of ramps, n (int32).

  • 12, 16: the initial temperature and hold.

  • 20, 100, 180: the rates, target temperatures and holds, each an array of 20 slots, of which those past n are zero.

• ⁠GC-2010 Instrument Parameters/Injection Parameter-1⁠, 512 bytes:

  • 12, 16, 20: the column flow, linear velocity and split ratio.

  • 24, 120, 216, 312: the temperature, total flow, pressure and purge flow programs, 96 bytes each: the number of ramps (int32), the initial value and hold, then arrays of 7 rates, targets and holds.

• ⁠GCMS Configuration/Column-1⁠, 832 bytes:

  • 0, 64: the column name and serial number, null-terminated strings of up to 64 bytes.

  • 132: the length in tenths of a metre (int32).

  • 140: the maximum temperature (int32).

• ⁠QP5K Instrument Parameters/MS Parameter⁠, 600 or 664 bytes:

  • 20: the ion source temperature in tenths of a degree (int32).

  • 44, 48: the start and end of acquisition in milliseconds (int32).

  • 52: the event time in milliseconds (int32).

The interface temperature is only read from the XML, as the additional heater the configuration names MS. Method heaters are numbered by their position in the configuration's list of heaters, which starts at 2, so the MS heater is method heater 4 in every file seen.

The settings were checked against the 'GCMSsolution' method printouts published with three 'QP2020 NX' runs.

Author(s)

Ethan Bass

See Also

read_chemstation_method and read_agilent_amx for 'Agilent' methods.

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_lcd_3d(), read_sz_tables()

Examples

## Not run: 
method <- read_shimadzu_method("path/to/file.gcd")
method$oven$program

## End(Not run)

Read 'Shimadzu' QGD files

Description

Reads 'Shimadzu GCMSsolution' .qgd GC-MS data files.

Usage

read_shimadzu_qgd(
  path,
  what = c("MS1", "TIC"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  collapse = TRUE
)

Arguments

Details

The MS data is stored in the ⁠GCMS Raw Data⁠ storage, which contains an ⁠MS Raw Data⁠ stream with MS scans, a ⁠TIC Data⁠ stream containing the total ion chromatogram, and a ⁠Retention Time⁠ stream containing the retention times. All known values are little-endian. The retention time stream is an array of 4-byte integers giving the time of each scan in milliseconds, and the TIC stream an array of 8-byte integers, one per retention time.

The MS Raw Data stream holds one block per scan, located through the ⁠Spectrum Index⁠ stream. Each block begins with a 32-byte header:

• scan number (4-byte integer)

• retention time in milliseconds (4-byte integer)

• unknown (12 bytes)

• number of bytes in each intensity value (2-byte integer)

• number of m/z values in the block (2-byte integer)

• unknown (8 bytes)

After the header, each m/z value is followed by its intensity. The m/z values are 2-byte integers holding m/z times 20. Intensities are unsigned integers of the width given in the header, except that the top bit of a 4-byte intensity is dropped.

Value

A list holding the MS1 spectra and the TIC, or the one requested where collapse is TRUE. The TIC is returned in the format specified by data_format and format_out. If data_format is wide, it is returned with retention times as rows and a single column for the intensity. If long format is requested, two columns are returned: one for the retention time and one for the intensity. The format_out argument determines whether it is returned as a matrix, data.frame, or data.table. The spectra are always long, with columns scan, rt, mz and intensity, and a matrix resolves to a data.table. Metadata are attached as attributes if read_metadata is TRUE.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_method(), read_sz_lcd_2d(), read_sz_lcd_3d(), read_sz_tables()

Examples

## Not run: 
read_shimadzu_qgd("path/to/file.qgd")

## End(Not run)

Read 'Shimadzu' LCD 2D data

Description

Reads the chromatogram data streams from 'Shimadzu' .lcd files.

Usage

read_sz_lcd_2d(
  path,
  format_out = "data.frame",
  data_format = "wide",
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd",
  scale = TRUE
)

Arguments

Details

A parser to read chromatogram data streams from 'Shimadzu' .lcd files. LCD files are encoded as 'Microsoft' OLE documents. The parser relies on the olefile package in Python to unpack the files. The chromatogram data is encoded in streams titled ⁠LSS Raw Data:Chromatogram Ch<#>⁠. The chromatogram data streams begin with a 24-byte header.

The 24 byte header consists of the following fields:

• 4 bytes: segment label (17234).

• 4 bytes: Little-endian integer specifying the sampling rate (in milliseconds).

• 4 bytes: Little-endian integer specifying the number of values in the file.

• 4 bytes: Little-endian integer specifying the total number of bytes in the file.

• 8 bytes of 00s

Each segment is divided into multiple sub-segments, which begin and end with an integer specifying the length of the sub-segment in bytes. All known values in this data stream are little-endian and the data are delta-encoded. The first hexadecimal digit of each value is a sign digit specifying the number of bytes in the delta and whether the value is positive or negative. The sign digit represents the number of hexadecimal digits used to encode each value. Even numbered sign digits correspond to positive deltas, whereas odd numbers indicate negative deltas. Positive values are encoded as little-endian integers, while negative values are encoded as two's complements. The value at each position is derived by subtracting the delta at each position from the previous value.

Value

One or more 2D chromatograms from the chromatogram streams in matrix or data.frame format, according to the value of format_out. If multiple chromatograms are found, they will be returned as a list of matrices or data.frames. The chromatograms will be returned in wide or long format according to the value of data_format.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_3d(), read_sz_tables()

Read 'Shimadzu' LCD 3D data

Description

Reads 3D PDA data stream from 'Shimadzu' .lcd files.

Usage

read_sz_lcd_3d(
  path,
  format_out = "matrix",
  data_format = "wide",
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd",
  scale = TRUE
)

Arguments

Details

A parser to read PDA data from 'Shimadzu' .lcd files. LCD files are encoded as 'Microsoft' OLE documents. The parser relies on the olefile package in Python to unpack the files. The PDA data is encoded in a stream called ⁠PDA 3D Raw Data:3D Raw Data⁠. The PDA data stream contains a segment for each retention time, beginning with a 24-byte header.

The 24 byte header consists of the following fields:

• 4 bytes: segment label (17234).

• 4 bytes: Little-endian integer specifying the sampling rate along the spectral axis, where the equivalent field of a 2D stream gives the sampling rate along the time axis. This reading is not confirmed.

• 4 bytes: Little-endian integer specifying the number of wavelength values in the segment.

• 4 bytes: Little-endian integer specifying the total number of bytes in the segment.

• 8 bytes of 00s

Each segment is divided into two sub-segments, which begin and end with an integer specifying the length of the sub-segment in bytes. All known values in this data stream are little-endian and the data are delta-encoded. The first hexadecimal digit of each value is a sign digit specifying the number of bytes in the delta and whether the value is positive or negative. The sign digit represents the number of hexadecimal digits used to encode each value. Even numbered sign digits correspond to positive deltas, whereas odd numbers indicate negative deltas. Positive values are encoded as little-endian integers, while negative values are encoded as two's complements. The value at each position is derived by subtracting the delta at each position from the previous value.

Value

A 3D chromatogram from the PDA stream in matrix, data.frame, or data.table format, according to the value of format_out. The chromatograms will be returned in wide or long format according to the value of data_format.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_tables()

Read 'Shimadzu' QTOF stream

Description

Read QTOF stream from 'Shimadzu LabSolutions' .lcd files.

Usage

read_sz_qtof(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = "long",
  levels = c("MS1", "MS2"),
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd",
  scale = TRUE
)

Arguments

Details

Data for each scan is stored in three contiguous blocks: a 64-byte header (72 bytes in some files), a block of flight times, followed by a block of intensities.

Scan Header (64 bytes, little-endian):

m/z block (n x 8 bytes) Each peak's flight time is an unsigned 64-bit little-endian integer. R has no 64-bit integer type, so it is read as two 32-bit halves and recombined as low + high * 2^32. The low half is unsigned, but R has no unsigned 32-bit type and reads it as signed, so it is corrected before recombining. Left uncorrected, it would shift half of all flight times by 2^32 (2 to 9 ppm of flight time in the files examined, so twice that in m/z) and read 0x80000000 as NA. Conversion is

mz = ((t-B)/A)^2

A and B are fitted per file from the ⁠TOF Calibration Table⁠ stream (see read_sz_qtof_calibration), which stores calibration points for both polarities; the polarity of the acquisition selects between them. This matters: the coefficients differ by ~1.5% between polarities on one of the two instruments examined (0.006% on the other), which is ~3% in m/z, so fixed coefficients are not usable. The tuning calibration alone is still a few ppm out, because it is recorded before the run; folding in the mass correction the file caches for the run closes that gap (see read_sz_qtof_mass_correction). Measured against 'ProteoWizard' conversions of three files from two instruments — which read the file through Shimadzu's own library — the m/z then agree to 0.03-0.1 ppm (median). That figure is the resolution of the comparison rather than of this parser: the vendor reports m/z to four decimal places, which is 0.5 ppm at the bottom of the mass range and 0.05 ppm at the top.

Intensity block (n x m bytes) Each peak's intensity is stored as a little-endian unsigned integer of m bytes, where m is the int_width field from the scan header (2 for most scans, 4 for scans containing large values, and occasionally 1). The stored values are raw detector counts summed over every TOF accumulation in the scan — the individual time-of-flight spectra the instrument adds together to make one. LabSolutions (and the 'Shimadzu' library used by 'ProteoWizard') normalizes them to a nominal 100 accumulations:

intensity = round(raw \times 100 / n)

where n is the number of accumulations per scan (rounding is half-up). n is read from the Status stream, which stores it once per acquisition event; it is 376 in the reference file, giving a divisor of 3.76.

Value

A named list holding whichever of the requested levels the file contains, each a data.table or data.frame in long format with columns scan, rt, mz and intensity, and a precursor_mz column before mz for product-ion spectra. Each carries a scan_info attribute giving one row per spectrum of that level, including the ones that hold no peaks, with the acquisition event, MS level, DDA cycle, ion polarity, selected precursor and peak count.

Read TOF calibration coefficients from a 'Shimadzu' QTOF file

Description

Fits the flight-time-to-m/z coefficients A and B from the calibration points stored in the file.

Usage

read_sz_qtof_calibration(
  path,
  drop_rep = 2L,
  correct = TRUE,
  polarity = read_qtof_polarity(path)
)

Arguments

Details

The ⁠TOF Calibration Table⁠ stream holds the calibration points themselves: pairs of a known m/z and the flight time at which the instrument actually observed it. It is encoded as a protocol buffer, a binary format in which every value is tagged with a number rather than a name, so the fields are referred to below by those numbers. The top-level ones are:

• 10 – positive mode (⁠Na(NaI)n⁠ calibrants)

• 20 – negative mode (⁠I(NaI)n⁠ calibrants)

Both polarities are written to every file, so the table is the same in a positive and a negative run on the same instrument.

Within each entry are the theoretical m/z scaled by 1e9 (.10), the measured flight time in the same units as the ⁠Centroid Data⁠ stream (.20) and a label (.30). Five calibrants are stored per polarity, in three replicate sets. The second is a factory default rather than a measurement — its flight times are byte-identical across different instruments — and including it inflates the error by two orders of magnitude.

'LabSolutions' fits one of the remaining sets rather than their average, and which one varies between files. The mass correction the file caches for the run (see read_sz_qtof_mass_correction) says which, because its offset is tied to that set's intercept by

offset = B(1 - scale) + shift \times A

Solving that for B reproduces one set's own intercept to ~1e-7 and no other's to better than 1e-4. That set is fitted and the correction folded in, as A/scale and B - shift \times A/scale, which reproduces the m/z 'LabSolutions' reports to the four decimal places it writes them with, leaving 0.03 to 0.1 ppm (median) over three files from two instruments.

Failing that — no cached correction, or an offset that fits no set — the sets named by drop_rep are dropped and the rest fitted together, which lands within about 5 ppm. read_sz_qtof then refines that fit against the reference ions it finds in the data.

Value

Named numeric vector with elements A and B.

Read the cached mass correction from a 'Shimadzu' QTOF file

Description

Reads the mass correction 'LabSolutions' fitted for the run, where the file carries one.

Usage

read_sz_qtof_mass_correction(path, polarity = read_qtof_polarity(path))

Arguments

Details

⁠Mass Data Load Format/Mass Correction Cache⁠ holds the mass correction 'LabSolutions' applied to the run: the reference ions it found and the coefficients it fitted to them. Like the other QTOF parameter streams it is a protocol buffer with a block per polarity (field 10 positive, 20 negative), the reference compounds under 10 and the result under 30:

• ⁠30.<pol>.10.10⁠ — offset of the correction, in flight-time units

• ⁠30.<pol>.10.20⁠ — scale factor of the correction, near 1

• ⁠30.<pol>.20.10.10⁠, .20 — id of a reference compound and the m/z at which it was measured in this run, scaled by 1e9

The correction is applied to the flight time, as ⁠t' = scale * t + offset⁠, which is the same as shifting the calibration in the square root of the mass:

\sqrt{mz'} = scale \sqrt{mz} + shift

where shift is the mean of sqrt(theoretical) - scale * sqrt(measured) over the reference ions. Reading the vendor's own correction out reproduces its mass axis exactly, where refitting on the reference ions found in the data leaves a few tenths of a ppm.

Value

A list of scale, offset and shift, or NULL if the stream is missing or holds no usable result.

Read 'Shimadzu' QTOF TIC stream

Description

A parser to read total ion chromatogram data streams from the quadrupole time-of-flight (⁠QTFL RawData⁠) container of 'Shimadzu' .lcd files. Triple quadrupole files store their TIC differently and are read by read_sz_tlm_tic instead. LCD files are encoded as 'Microsoft' OLE documents. The parser relies on the olefile package in Python to unpack the files. The TIC data is encoded in a stream called ⁠Centroid SumTIC⁠, which opens with an 8-byte header and holds one 16-byte record per scan: three 4-byte little-endian integers — the retention time in milliseconds, the scan number and the intensity — followed by a 4-byte spacer (00000000). Retention times are converted to minutes, as elsewhere in the package.

Usage

read_sz_qtof_tic(
  path,
  format_out = "data.frame",
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd"
)

Arguments

Value

A 2D chromatogram from the SumTIC stream in matrix or data.frame format, according to the value of format_out. The chromatograms will be returned in wide or long format according to the value of data_format.

Author(s)

Ethan Bass

Read 'Shimadzu' peak tables

Description

Read the integration results 'LabSolutions' stored alongside the raw data in a 'Shimadzu' OLE container (.lcd or .gcd), one table per channel.

Usage

read_sz_tables(path, format_out = "data.frame")

Arguments

Details

Each table lives in its own stream, a short header followed by one fixed-length record per peak. Only chromatographic tables are read: streams named ⁠PT-⁠ plus the channel (PT-LC.1.1.DET.1.CH#1, matching that channel's channel_id metadata), or ⁠Peak Table-⁠ plus a number (⁠Peak Table-100⁠). The tables a mass spectrometry run produces (⁠Mass Peak Table⁠, ⁠Compound Peak Table⁠, ⁠Ident Peak Table⁠) have layouts of their own and are skipped.

There are two layouts. V0 has no magic number and opens with an 8-byte header: the peak count as a uint32, then four unparsed bytes. V1 opens with the magic number ⁠56 45 52 31⁠ (VER1), the peak count as a uint32, and twelve further unparsed bytes, for a 20-byte header.

In every file seen so far the layout follows the stream name: ⁠PT-⁠ streams, under ⁠LSS Data Processing⁠, are V1, and ⁠Peak Table-⁠ streams, under ⁠LC Data Processing⁠, are V0. The parser still dispatches on the magic number rather than on the name of the stream, since the name is the weaker signal.

Retention, initial and final times are stored in milliseconds and converted to minutes, as elsewhere in the package. All values are little-endian.

A V0 record is 280 bytes:

A V1 record is longer and its length is not fixed by the format: it is derived as ⁠(stream size - 20) / peak count⁠. The first 728 bytes are the part this parser reads, and any remainder is skipped.

Two things the tables above do not show. AH is a scaled integer in V0 but a double in V1, so the same field has to be decoded differently in each. The V1 values are also spaced rather than packed: seven doubles lie exactly 64 bytes apart — Plate.no (248), Plate.ht (376) and the tailing factor (504), with unidentified values at 312, 440, 568 and 632 — while k (240), the resolution (512) and the separation factor (640) each sit 8 bytes to one side of that grid, paired with the value on it. Each derived quantity therefore seems to occupy a 64-byte slot and use only the first eight bytes of it. The field names are this package's reading of the format rather than the vendor's own.

A V0 record is not always 280 bytes: the ⁠Peak Table-100⁠ streams under ⁠LC Data Processing⁠ hold 544-byte records whose first 256 bytes follow the table above, with the retention factor (k) as a double at 208. As for V1, the record length is derived as ⁠(stream size - 8) / peak count⁠ and any remainder beyond 280 bytes is skipped. A table whose records are shorter than 280 bytes, or do not divide the stream evenly, is rejected.

Value

A named list with one peak table per channel, named for the stream it was read from. A table that cannot be parsed is returned as NA with a message, so one bad channel does not lose the others.

Author(s)

Ethan Bass

See Also

Other 'Shimadzu' parsers: read_shimadzu(), read_shimadzu_gcd(), read_shimadzu_lcd(), read_shimadzu_method(), read_shimadzu_qgd(), read_sz_lcd_2d(), read_sz_lcd_3d()

Read 'Shimadzu' TLM stream

Description

Read the ⁠TLM Raw Data⁠ mass spectrometry stream from 'Shimadzu LabSolutions' .lcd files.

Usage

read_sz_tlm(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = "long",
  levels = c("MS1", "MS2"),
  sparse = TRUE,
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd"
)

Arguments

Details

Spectra live in the ⁠MS Raw Data⁠ stream and are located through ⁠Spectrum Index⁠, which holds one 24-byte entry per spectrum:

Each record begins with a 12-byte wrapper (0xFFFFFFFF, uncompressed size, compressed size) followed by a zlib stream. The decompressed block opens with a 44-byte header shared by every scan type:

Profile scans (type 10 and 14) follow the header with two m/z pairs stored as m/z x 100 — the isolation window (equal low and high values for MS2; the scan range for MS1), then the scan range — and then n unsigned 32-bit intensities. Bit 31 of an intensity marks detector saturation and is not part of the value. Intensities are already in the units LabSolutions reports, so no scaling is applied.

Points lie on an evenly spaced m/z grid running from the low end of the scan range, with a bin width of (high - low) / (100 * n) (0.1 in the files seen so far). The grid overhangs the acquired range by 10 bins at the bottom and 9 at the top; those are dropped, which is what makes the summed intensity match the ⁠TIC Data⁠ stream exactly.

MRM and SIM scans (types 15 and 11) instead follow the header with n 12-byte transitions: Q1 m/z x 100, Q3 m/z x 100, and intensity.

Value

A named list holding whichever of the requested levels the file has, each a long table with columns scan, rt (minutes), mz and intensity, and a precursor_mz column before mz where the scans carry one. A per-scan summary (retention time, event, MS level, polarity, precursor m/z, point count) is attached to each as a scan_info attribute.

Author(s)

Ethan Bass

Read TIC from 'Shimadzu' TLM stream

Description

Reads total ion current chromatograms from the ⁠TLM Raw Data⁠ streams of 'Shimadzu LabSolutions' .lcd files.

Usage

read_sz_tlm_tic(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = "shimadzu_lcd",
  what = c("tic", "sumtic")
)

Arguments

Details

⁠TIC Data⁠ holds two little-endian uint32s per spectrum: the total ion current and a flag that is 0x80000000 when any point in the spectrum saturated the detector. The retention times come from the ⁠Retention Time⁠ stream. Neither stream needs the spectra themselves to be decompressed, so this is much cheaper than read_sz_tlm.

Each acquisition event is returned as a separate chromatogram, named ⁠Event 1⁠, ⁠Event 2⁠ and so on, since events can differ in polarity, MS level and scan range, and are interleaved in acquisition order.

The ⁠SumTIC Data⁠ stream (one 12-byte record per cycle: retention time, value, saturation flag) is a curve computed by the instrument. It is not a plain sum of the per-spectrum TICs: in the MRM files examined it matches the cycle mean (which, with one event per cycle, is also the sum), in the scan files the cycle mean divided by six, and in a file mixing SIM with product-ion scans neither. It is therefore returned as stored rather than recomputed.

Value

A named list of chromatograms, one per acquisition event, or a single chromatogram for what = "sumtic".

Author(s)

Ethan Bass

Read ThermoRaw

Description

Converts a 'Thermo' .raw file to mzML with the ThermoRawFileParser and reads the result with read_mzml.

Usage

read_thermoraw(
  path,
  path_out = NULL,
  format_out = c("matrix", "data.frame", "data.table"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw"),
  verbose = getOption("verbose")
)

Arguments

Details

The ThermoRawFileParser must be installed separately.

Value

A list of chromatograms, as returned by read_mzml, in the format specified by format_out.

Side effects

If path_out is specified, the mzML file (and, if read_metadata is TRUE, a metadata .txt file) is left there.

Author(s)

Ethan Bass

References

Hulstaert Niels, Jim Shofstahl, Timo Sachsenberg, Mathias Walzer, Harald Barsnes, Lennart Martens, and Yasset Perez-Riverol. ThermoRawFileParser: Modular, Scalable, and Cross-Platform RAW File Conversion. Journal of Proteome Research 19, no. 1 (January 3, 2020): 537–42. doi:10.1021/acs.jproteome.9b00328.

See Also

Other external parsers: call_entab(), call_openchrom(), call_rainbow(), sp_converter(), uv_converter()

Examples

## Not run: 
read_thermoraw(path)

## End(Not run)

Read 'Varian' peak list

Description

Read peak list(s) from 'Varian MS Workstation'.

Usage

read_varian_peaklist(path)

Arguments

Value

A data.frame containing the information from the specified report.

Author(s)

Ethan Bass

See Also

Other 'Varian' parsers: read_varian_sms()

Examples

## Not run: 
read_varian_peaklist(path)

## End(Not run)

Read 'Varian' SMS

Description

Reads 'Varian Workstation' SMS files.

Usage

read_varian_sms(
  path,
  what = c("MS1", "TIC", "BPC"),
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = "long",
  read_metadata = TRUE,
  collapse = TRUE
)

Arguments

Details

Varian SMS files begin with a DIRECTORY holding the offsets of each section. The first section is MSData, which begins at byte 3238 in every file seen so far, and is itself divided in two. The first part, after a short header, holds chromatogram data, one record per scan: the scan number, the retention time (as a 64-bit float), the ion time (µsec, as a 2-byte unsigned integer), the total ion chromatogram (TIC), the base peak chromatogram (BPC), and further unidentified fields. The scan numbers and the TIC and BPC intensities are stored as 4-byte little-endian integers. A run of null bytes then separates this part from the segments holding the mass spectra.

The mass spectra are encoded differently. Each scan is a series of variable-length values, separated from the next scan by two null bytes. Within a scan the values are paired: the first of each pair is the delta-encoded mass-to-charge ratio and the second is the intensity. Each value is a big-endian integer whose length, 1 + (d %/% 4) bytes, and bit width are set by its leading hexadecimal digit (d). Values beginning with 0-3 are single bytes. For d >= 4, the lowest n bits are preserved according to the following scheme:

• d = 4-5 -> preserve lowest 13 bits

• d = 6-7 -> preserve lowest 14 bits

• d = 8-9 -> preserve lowest 21 bits

• d = 10-11 (A-B) -> preserve lowest 22 bits

• d = 12-13 (C-D) -> preserve lowest 27 bits

• d = 14-15 (E-F) -> preserve lowest 28 bits

No file seen so far carries a leading digit above C, so the rules for D and for E-F are extrapolated from the others rather than observed.

Value

A chromatogram or list of chromatograms from the specified file, according to the value of what. Chromatograms are returned in the format specified by format_out, except that mass spectra are returned as a data.table when format_out is matrix.

Note

There is still only limited support for the extraction of metadata from this file format.

Author(s)

Ethan Bass

See Also

Other 'Varian' parsers: read_varian_peaklist()

Examples

## Not run: 
read_varian_sms(path)

## End(Not run)

Read 'Waters' ASCII (.arw)

Description

Reads 'Waters' ASCII .arw files.

Usage

read_waters_arw(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw")
)

Arguments

Details

For help exporting files from Empower, you can consult the official documentation: How_to_export_3D_raw_data_from_Empower.

Value

A chromatogram in the format specified by the format_out and data_format arguments.

Author(s)

Ethan Bass

See Also

Other 'Waters' parsers: read_waters_raw()

Examples

## Not run: 
read_waters_arw("path/to/file.arw")

## End(Not run)

Read 'Waters' RAW

Description

Reads 'Waters MassLynx' (.raw) files into R.

Usage

read_waters_raw(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw")
)

Arguments

Value

A list of 2D chromatograms, one per trace and named by it, in the format specified by format_out and data_format.

Note

This parser reads only 2D chromatograms (retention time and intensity), not mass spectra or DAD data.

Author(s)

Ethan Bass

See Also

Other 'Waters' parsers: read_waters_arw()

Examples

## Not run: 
read_waters_raw("path/to/file.raw")

## End(Not run)

Shared params 2D chromatogram

Description

Shared params 2D chromatogram

Arguments

Value

A chromatogram in the format specified by the format_out and data_format arguments.

Converter for 'Agilent MassHunter' UV files

Description

Reads a single chromatogram from a MassHunter .sp file using the Aston file parser.

Usage

sp_converter(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw")
)

Arguments

Value

A chromatogram in the format specified by the format_out and data_format arguments.

Deprecation

The 'aston' parser is deprecated and will be removed in a future release. 'Aston' has been unmaintained since 2020. This is the only remaining 'aston' binding, and read_chroms selects it automatically only when 'entab' is not installed. Please use the 'entab' parser (by the same author as 'Aston') instead, e.g. read_chroms(path, format_in = "masshunter_dad", parser = "entab").

See Also

Other external parsers: call_entab(), call_openchrom(), call_rainbow(), read_thermoraw(), uv_converter()

Select chromatograms by their metadata

Description

Retains the chromatograms of a chrom_list whose metadata meet the specified condition, such as sample_name == "blank" or run_datetime > as.POSIXct("2024-01-01", tz = "UTC"). The condition can refer to any field extract_metadata reports, such as sample_name or method, as well as the chromatogram's name in the list.

Usage

## S3 method for class 'chrom_list'
subset(x, subset, ...)

Arguments

Details

Numeric fields such as time_range and sample_injection_volume compare as numbers wherever the file's value parses as one, and a field with several values can be indexed (e.g. time_range[2]). A field a chromatogram does not carry is NA, and a chromatogram for which subset is NA is dropped, as in subset() for data frames. Where an element holds several chromatograms, such as the traces read_agilent_d returns for each .D directory, it is kept or dropped as a whole, and subset sees the fields its chromatograms agree on, ignoring those that leave a field empty; a field they disagree on is NA.

Value

A chrom_list containing the selected chromatograms.

See Also

extract_metadata

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
chroms <- read_chroms(path, format_in = "chemstation_ch", pattern = "dad1A",
                      parser = "chromconverter", progress_bar = FALSE)
subset(chroms, sample_name != "MEOH")
subset(chroms, run_datetime < as.POSIXct("2023-06-21", tz = "UTC"))

Summarize a chrom_list object

Description

Returns what print.chrom_list displays as a table, with one row per chromatogram: the sample it belongs to, its size, and the metadata fields in cols. Unlike print, nothing is collapsed into a header, abbreviated or truncated to the first few rows, so the result can be filtered and joined against.

Usage

## S3 method for class 'chrom_list'
summary(
  object,
  cols = chrom_summary_cols(),
  format_out = c("data.frame", "data.table", "tibble"),
  digits = NULL,
  ...
)

Arguments

Value

A data.frame, data.table or tibble (according to the value of format_out) with one row per chromatogram. The first columns describe where the chromatogram sits and how large it is — sample, trace (only when a sample holds more than one), n_rows and n_cols — followed by one column per metadata field found. A field no chromatogram records, or that every one of them leaves empty, is dropped rather than filled with NA. A field holding more than one value, such as the product_mz of an MRM event monitoring several transitions, is collapsed to a comma-separated string so that it occupies one column.

See Also

extract_metadata, print.chrom_list

Examples

path <- system.file("extdata", "benzoxazinoid_standards",
                    package = "chromConverter")
chroms <- read_chroms(path, format_in = "chemstation_ch", pattern = "dad1A",
                      parser = "chromconverter", progress_bar = FALSE)
summary(chroms)

Converter for 'Agilent ChemStation' UV files

Description

Defunct. Use read_chemstation_uv instead.

Usage

uv_converter(
  path,
  format_out = c("matrix", "data.frame", "data.table"),
  data_format = c("wide", "long"),
  correction = TRUE,
  read_metadata = TRUE,
  metadata_format = c("chromconverter", "raw")
)

Arguments

Details

This function wrapped 'Aston”s generic TraceFile reader, which imports scipy.io.netcdf.NetCDFFile. That symbol was removed in scipy v1.14, so TraceFile cannot be used without pinning scipy < 1.14 for the whole Python session. Since .uv files are read by chromConverter's internal parser, read_chemstation_uv, this wrapper was retired rather than constraining scipy for everyone.

Value

There is no return value. Calling this function is an error.

See Also

Other external parsers: call_entab(), call_openchrom(), call_rainbow(), read_thermoraw(), sp_converter()

Write ANDI chrom CDF file from chromatogram

Description

Exports a chromatogram in ANDI (Analytical Data Interchange) chromatography format (ASTM E1947-98). The format holds a single trace, so a 3D chromatogram must be reduced to one: name the column to export with the lambda argument, or the first column is exported with a warning.

Usage

write_andi_chrom(x, path_out, sample_name = NULL, lambda = NULL, force = FALSE)

Arguments

Details

Retention times are written in the unit the chromatogram reports, declared in the file's mandatory retention_unit attribute as Minutes or Seconds. A chromatogram whose time_unit is missing or unrecognized is taken to be in minutes, since the attribute cannot be left unset. The run length, delay time and sampling interval are derived from the retention times, and detector_maximum_value and detector_minimum_value report the range of the exported trace. actual_sampling_interval is the mean of the intervals, and uniform_sampling_flag reports whether every interval matches that mean. The per-point times are written to raw_data_retention either way, which is what a reader needs where the flag is N.

Value

Invisibly returns the path to the written CDF file.

Side effects

Exports a chromatogram in ANDI chromatography format (netCDF) in the directory specified by path_out. The file will be named according to the value of sample_name. If no sample_name is provided, the sample_name attribute will be used if it exists.

Author(s)

Ethan Bass

See Also

Other write functions: write_andi_ms(), write_chroms(), write_mzml()

Examples

path <- system.file("extdata/alkane_ladder.txt", package = "chromConverter")
chrom <- read_shimadzu(path, what = "chroms")
# the file is named for the `sample_name` attribute unless one is supplied
write_andi_chrom(chrom, path_out = tempdir(), force = TRUE)

Write ANDI MS CDF file from chromatogram

Description

Exports mass spectrometry data in ANDI (Analytical Data Interchange) MS format (ASTM E1947-98). A total ion chromatogram is derived from the MS1 scans if the supplied object does not already carry one.

Usage

write_andi_ms(
  x,
  path_out,
  sample_name = NULL,
  force = FALSE,
  ms_params = list()
)

Arguments

Details

Retention times are written in seconds, the only time unit the specification suggests, and declared in raw_data_time_units. A chromatogram is converted unless its time_unit already reports seconds, so one whose unit is missing or unrecognized is taken to be in minutes.

Value

Invisibly returns the path to the written CDF file.

Side effects

Exports mass spectrometry data in ANDI MS format (netCDF) in the directory specified by path_out. The file will be named according to the value of sample_name. If no sample_name is provided, the sample_name attribute will be used if it exists.

Author(s)

Ethan Bass

See Also

Other write functions: write_andi_chrom(), write_chroms(), write_mzml()

Examples

## Not run: 
write_andi_ms(chrom, path_out = "path/to/directory")

## End(Not run)

Write chromatograms

Description

Writes chromatograms to disk in the format specified by export_format: either mzml, cdf, csv, or arw.

Usage

write_chroms(
  chrom_list,
  path_out,
  export_format = c("mzml", "cdf", "csv", "arw"),
  what = "",
  force = FALSE,
  show_progress = TRUE,
  verbose = getOption("verbose"),
  ...
)

Arguments

Value

No return value. The function is called for its side effects.

Side effects

Exports a chromatogram in the file format specified by export_format in the directory specified by path_out.

Author(s)

Ethan Bass

See Also

Other write functions: write_andi_chrom(), write_andi_ms(), write_mzml()

Examples

path <- system.file("extdata/alkane_ladder.txt", package = "chromConverter")
chroms <- read_chroms(path, format_in = "shimadzu_ascii",
                      find_files = FALSE, progress_bar = FALSE)
write_chroms(chroms, path_out = tempdir(), export_format = "csv",
             show_progress = FALSE)

Write mzML

Description

Writes spectra and chromatograms to an mzML file.

Usage

write_mzml(
  data,
  path_out,
  sample_name = NULL,
  what = NULL,
  instrument_info = NULL,
  centroided = TRUE,
  compress = TRUE,
  indexed = TRUE,
  force = FALSE,
  show_progress = TRUE,
  verbose = getOption("verbose")
)

Arguments

Details

Mass spectra and DAD spectra are written to the spectrumList, while the total ion current (TIC) and the base peak chromatogram (BPC) go to the chromatogramList, since the controlled vocabulary has terms for those two summaries. DAD spectra are written as electromagnetic radiation spectra (MS:1000804) using Thermo's naming convention, with controllerType=4 in the spectrum ID for compatibility with existing tools.

Asking for both MS1 and MS2 writes them into one spectrumList, interleaved in acquisition order: on the scan column they share, or on retention time where neither has one. Each spectrum is then named for its scan (scan=417) rather than for its position in the list, which keeps the names unique across the levels. An MS2 spectrum carries the precursor it came from as MS:1000744 ("selected ion m/z"), and a spectrumRef to the MS1 spectrum that precedes it. Collision energy, isolation window and precursor charge are not written, as no parser in the package reads them.

Retention times are written in minutes (UO:0000031), as chromConverter reports them, rather than converted to seconds as write_andi_ms does.

The streams to write come from the names of data, so a bare chromatogram has to say what it holds through its detector attribute: UV and DAD are written as a DAD stream, and MS as MS1, or as MS2 where the table also carries an ms_level attribute above 1. Any other detector, including a missing or NA one (which is how several parsers report an unknown detector), is an error: the function stops rather than guess, and asks for a named list instead.

A one-dimensional DAD stream (a single wavelength) is refused: mzML has no axis to write it along, so it would become one single-point spectrum per retention time. Use write_andi_chrom for a single trace. If it is the only stream requested this is an error; otherwise it is dropped with a warning and the rest is written.

The file's metadata are taken from the MS1 stream if it is written, and otherwise from the first stream requested. That stream's sample_name attribute names the file unless sample_name is supplied.

If indexed = TRUE, the function will generate an indexed mzML file, which allows faster random access to spectra. The file is assembled by writing XML strings straight to a connection rather than by building a document in memory.

Value

Invisibly returns the path to the written mzML file.

Author(s)

Ethan Bass

See Also

Other write functions: write_andi_chrom(), write_andi_ms(), write_chroms()

Examples

## Not run: 
chrom <- read_chroms("path/to/file.qgd", progress_bar = FALSE)
write_mzml(chrom[[1]], path_out = "path/to/directory")

## End(Not run)