Read 'Shimadzu' QGD files

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

Usage

read_shimadzu_qgd(
  path,
  what = c("MS1", "MS2", "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

path: Path to 'Shimadzu' .qgd file.
what: What stream to get: current options are full scans (MS1), MRM scans (MS2) and the TIC. If a stream is not specified, the function returns all three. A level asked for by name that the file doesn't hold is left out with a warning.
format_out: Class of output. Either matrix, data.frame, or data.table.
data_format: Whether to return data in wide (default) or long format.
read_metadata: Logical. Whether to attach metadata. Defaults to TRUE.
metadata_format: Format to output metadata. Either chromconverter (standardized field names) or raw (vendor field names, unmapped).
collapse: Logical. Whether to collapse lists that only contain a single element. Defaults to TRUE.

Value

A list holding whichever of the requested spectra the file has (MS1, MS2) 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, plus precursor_mz before mz in the MRM spectra, and a matrix resolves to a data.table. Each table of spectra has a scan_info attribute with one row per scan, giving its scan, rt, ms_level and scan_type ("scan" or "MRM"). Metadata are attached as attributes if read_metadata is TRUE.

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. The index is an array of byte offsets, held as 4-byte integers in some files and as 8-byte integers after a 2-byte header in others, such as the MRM files seen so far. 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)
MRM event number (2-byte integer)
number of MRM transitions in the block (2-byte integer)
unknown (4 bytes)

In a full scan, 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, since it appears to flag a saturated value, as it does in 'Shimadzu' triple quadrupole .lcd files.

An MRM scan leaves the width and the number of m/z values at zero and instead holds one record per transition: the precursor and product m/z, each stored like the m/z of a full scan, followed by an intensity, an unsigned integer whose top bit is dropped when it is 4 bytes wide. No MRM file with 4-byte intensities has been seen. The header doesn't give the intensity width, so the reader works it out from the size of the block.

Author

Ethan Bass

Examples

if (FALSE) { # \dontrun{
read_shimadzu_qgd("path/to/file.qgd")
} # }