ncdf4_convert {TargetSearch} | R Documentation

## Convert from a NetCDF file format 3 to format 4

### Description

Convert from NetCDF format 3 into a custom TargetSearch NetCDF format 4. The new NetCDF just contains the raw data in a matrix format in order to allow easier and faster data manipulation.

### Usage

    ncdf4_convert(cdfFile, outFile = NULL, force = FALSE,
      baseline = FALSE, ...)

### Arguments

`cdfFile` | The NetCDF file to be converted
`outFile` | The new output file. If `NULL`, it replaces the `cdfFile`'s file extension (which should be `.cdf`) by `.nc4`. If the file extension is not `.cdf`, then `.nc4` is just appended. If the path to the file does not exist, it will be created automatically.
`force` | Logical. Set to `TRUE` to allow file overwrites, for example if the destination file still exists, in which case a warning is thrown. Default to `FALSE`.
`baseline` | Logical. Whether or not baseline correct the input file.
`...` | extra options passed to `baseline()`.

### Details

Starting from version 1.42.0, TargetSearch introduces a custom NetCDF file which is used for faster and easier data manipulation. This means, ion traces within a retention time can be quickly extracted, which if often required before plotting. Formerly, this process required parsing the whole file before the data could be extracted.

Note that this function only takes one file at the time. To convert many files at the same time, see the function `ncdf4_convert_from_path()` or the high level method `ncdf4Convert()`. Alternatively, you can call this function in a loop or using the `lapply` family of functions.

Keep in mind this function is intended for internal use (or advanced users); it is exported for convenience. Using the method `ncdf4Convert()` is recommended.

### Value

A string. The path to the converted file or invisible.

### File structure

The structure of the NetCDF format 4 is straightforward and the variables and attributes are self-evident. The following variables are defined.

- `retention_time` is a vector representing the retention time in seconds (double).

- `retention_index` is a vector representing the retention time indices (double). If missing, then the variable contains zeros. Its length is equal to the length of `retention_time`.

- `mass_range` is vector of length two containing the minimum and maximum m/z values (integer).

- `intensity` is matrix of intensity values (integer) where columns represent ion traces and rows are scans. The dimensions are length of "retention time" times the number of ions, ie, mass max - mass min + 1.

In addition, the following attributes are defined. Note that only `creator` and `version` are mandatory.

- `creator` a string equal to "TargetSearch" (for indentification purposes).

- `version` file format version (string). Currently "1.1".

- `time_corrected` (optional) a flag (short integer) to indicate RI correction. If missing it defaults to `false`.

- `baseline_corrected` (optional) a flag (short integer) to indicate that the file was baseline corrected by TargetSearch. If missing it defaults to `false`.

### Note

Currently, it is not possible to reconstruct the original NetCDF file from the converted file, especially if nominal mass or baseline correction was applied. On the other hand, if the NetCDF files are exported from custom chromatogram files (such as thermo raw files or LECO peg files), then the NetCDF 3 files can be deleted safely as there is always a way to recover them.

### Author(s)

Alvaro Cuadros-Inostroza

### See Also

`ncdf4Convert()`, `ncdf4_convert_from_path()`, `baseline()`

### Examples

    require(TargetSearchData)

    # get files from package TargetSearchData
    cdfpath <- file.path(find.package("TargetSearchData"), "gc-ms-data")

    # choose any file
    cdf <- file.path(cdfpath, '7235eg04.cdf')
    nc4 <- '7235eg04.nc4' # save file in current path

    # run the function
    ret <- ncdf4_convert(cdf, nc4)

    # the output should match the output file
    stopifnot(ret == nc4)

    # Use mapply to convert many files at the same time.
    cdf <- paste0('7235eg0', 6:8, '.cdf')
    nc4 <- paste0('7235eg0', 6:8, '.nc4')
    ret <- mapply(ncdf4_convert, file.path(cdfpath, cdf), nc4)
    stopifnot(ret == nc4)

[Package TargetSearch version 1.50.1 Index]