Package 'MsBackendTimsTof'

TimsTOF MS data backend

Description

The MsBackendTimsTof class adds support for Bruker TimsTOF data files (.d files) to Spectra() objects. New objects are created with the MsBackendTimsTof() function and initialized using the backendInitialize() function. To ensure a small memory footprint, only general information is kept in memory (such as number of frames and scans) and all data (specifically the peaks data) are retrieved from the original data files on-the-fly. MsBackendTimsTof directly extends the MsBackendCached() backend from the Spectra package and supports therefore adding or locally caching spectra variables.

Usage

MsBackendTimsTof()

## S4 method for signature 'MsBackendTimsTof'
backendInitialize(object, files, ..., BPPARAM = bpparam())

## S4 method for signature 'MsBackendTimsTof'
length(x)

## S4 method for signature 'MsBackendTimsTof'
peaksData(object, columns = c("mz", "intensity"))

## S4 method for signature 'MsBackendTimsTof'
peaksVariables(object)

## S4 method for signature 'MsBackendTimsTof'
mz(object)

## S4 method for signature 'MsBackendTimsTof'
intensity(object)

## S4 method for signature 'MsBackendTimsTof'
rtime(object)

## S4 method for signature 'MsBackendTimsTof'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'MsBackendTimsTof,ANY'
extractByIndex(object, i)

## S4 method for signature 'MsBackendTimsTof'
dataStorage(object)

## S4 method for signature 'MsBackendTimsTof'
spectraData(object, columns = spectraVariables(object))

## S4 method for signature 'MsBackendTimsTof'
show(object)

## S4 method for signature 'MsBackendTimsTof'
x$name

## S4 method for signature 'MsBackendTimsTof'
selectSpectraVariables(object, spectraVariables = spectraVariables(object))

## S4 replacement method for signature 'MsBackendTimsTof'
x$name <- value

## S4 method for signature 'MsBackendTimsTof'
precScanNum(object)

## S4 method for signature 'MsBackendTimsTof'
spectraNames(object)

## S4 method for signature 'MsBackendTimsTof'
tic(object, initial = TRUE)

Arguments

object	MsBackendTimsTof object.
files	character specifying TimsTOF ’*.d’ folders names.
...	Additional arguments.
BPPARAM	Parameter object defining the parallel processing setup to import data in parallel. Defaults to BPPARAM = bpparam(). See bpparam() for more information.
x	MsBackendTimsTof object.
columns	For spectraData(): names of the spectra variables to extract from object. For peaksData(): names of the peak variables to extract. Defaults to columns = c("mz", "intensity").
i	For [: integer, logical to subset the object.
j	For [: not supported.
drop	For [: not considered.
name	For $: the name of the variable to access.
spectraVariables	character with the names of the spectra variables that should be retained in the returned object.
value	For ⁠$<-⁠: the value to assign to the spectra variable.
initial	For tic(): logical(1) whether the original total ion count should be returned (initial = TRUE, the default) or whether it should be calculated on the spectras' intensities (initial = FALSE).

Details

The (DDA) MS2 data for MS2 spectra is retrieved from the analytis.tdf SQLite databases within the .d folder. Per default, the m/z of the largest peak in the isolation window is reported as precursorMz (SQLite database column "LargestPeakMz"). Alternatively, the content of database columns "AverageMz" or "IsolationMz" could be reported instead. To use e.g. the "AverageMz" as precursorMz set options(TIMSTOF_PRECURSOR_MZ = "AverageMz").

The reported isolationWindowLowerMz and isolationWindowUpperMz are calculated based on the "IsolationMz" and "IsolationWidth" database columns, i.e., isolationWindowLowerMz <- IsolationMz - IsolationWidth / 2 and isolationWindowUpperMz <- IsolationMz + IsolationWidth / 2.

Available methods

The methods listed below are specifically implemented for MsBackendTimsTof. The backend inherits and thus supports all other methods from the Spectra::MsBackend class.

• $: access any of the spectraVariables of the backend.

• ⁠$<-⁠: add a new spectra variable or change values for an existing spectra variables. Values can be changed for any spectra variable except peaks variables (Spectra::peaksVariables()) or special internal variables "file" and "frameId". Note that changes to spectra variables are only cached within the object but not propagated to the original data files.

• [: subset the backend. Only subsetting by element (row/i) is allowed. First the ⁠@indices⁠ slot of object is subsetted and then the frames and fileNames slots are subsetted accordingly. Note that [ does not update the values of frames variables (such as "MaxIntensity", "SummedIntensities", "NumScans" and "NumPeaks").

• backendInitialize(): initializes object (the MsBackendTimsTof object) using TimsTOF data files whose path is specified by files. This method is supposed to be called right after creating a MsBackendTimsTof object with MsBackendTimsTof() function.

• dataStorage(): gets a character of length equal to the number of spectra in object with the names of the '*.d' folders where each spectrum is stored.

• intensity(): gets the intensity values from the spectra in the backend. Returns a NumericList() of numeric vectors (intensity values for each spectrum). The length of the list is equal to the number of spectra in object.

• mz(): gets the mass-to-charge ratios (m/z) from the spectra in the backend. Returns a NumericList() of numeric vectors (m/z values for each spectrum). The length of the list is equal to the number of spectra in object.

• peaksData(): gets the peak matrices of the spectra in the backend. Returns a list of matrix with columns defined by parameter columns (which defaults to columns = c("mz", "intensity"). Use peaksVariables() to list all supported and available columns for a backend. The length of the list is equal to the number of spectra in object.

• peaksVariables(): gets the supported peak variables (columns) for the backend.

• rtime(): gets the retention times for each spectrum. Returns a numeric vector (length equal to the number of spectra) with the retention time for each spectrum.

• selectSpectraVariables(): reduces the available spectra variables to the ones specified with parameter spectraVariables. For core spectra variables (coreSpectraVariables()) only their values will be removed, but not the variable itself.

• spectraData(): gets spectra variables (specified by columns) from object.

• spectraNames(): returns an ID/name for each spectrum. As IDs the index of the spectrum within the object after the initialization is used. This index/spectra name is unique and stable for each spectrum within the same object.

• spectraVariables(): returns a character vector with the spectra variables names of core spectra variables defined in the Spectra package and other additional variables contained in object. Note that also "mz" and "intensity" (which are by default not returned by the ⁠spectraVariables,Spectra⁠ method) are returned.

• tic(): calculates the total ion count from the intensities of each spectrum (for initial = FALSE). For initial = TRUE NA is returned for all spectra.

Author(s)

Andrea Vicini, Johannes Rainer

Examples

## Define the test file
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")

## Create a MsBackend instance for that file
be <- backendInitialize(MsBackendTimsTof(), fl)
be

## Available spectra variables
spectraVariables(be)

## Available peaks variables
peaksVariables(be)

## Subset to 10 randomly selected spectra.
be_sub <- be[sort(sample(seq_along(be), 10))]
rtime(be_sub)

## Get the peaks data, i.e. m/z, intensity as well as tof and ion mobility
pd <- peaksData(be_sub,
    columns = c("mz", "intensity", "tof", "inv_ion_mobility"))
pd

## Filter to data set to MS2 spectra only
be_ms2 <- filterMsLevel(be, 2L)
be_ms2

## Get the full spectra data (including peaks variables)
spectraData(be_ms2)

## Add a new spectra variable
be$new_var <- seq_along(be)

head(be$new_var)

## Changing values of a spectra variable. Note that these are only changed
## *locally* within the object, but not in the original data files.
head(rtime(be))
be$rtime <- rtime(be) + 10
head(rtime(be))

---

Setup converter library for Bruker files

Description

Function to setup the required built-in open-source converters or the Bruker library to convert tof-to-mz and scan-to-inv_ion_mobility. When the Burker option is selected the library is downloaded automatically using opentimsr::download_bruker_proprietary_code().

Usage

setup_converter_library(opensource = TRUE, path = NULL, force = FALSE)

Arguments

opensource	logical(1) determine if use the built-in open-source converters of opentimsr (defaults) or the proprietary library from Bruker. Defaults to opensource = TRUE.
path	character(1) where save the Bruker library. If NULL the library is cached using BiocFileCache. Used only with the Bruker library. Defaults to path = NULL.
force	logical(1) force to redownload the Bruker library (default: FALSE).

Note

This function is called during package startup, thus it most cases it is not required to be used. This will use the opentimsr::setup_opensource() function. To use Bruker's proprietary library, call setup_converter_library() with parameter opensource = FALSE. This will download the library with opentimsr::download_bruker_proprietary_code() and cache the file in the local BiocFileCache.

Author(s)

Gabriele Tomè

Examples

## To setup the open-source built-in library
setup_converter_library()

## Use `setup_converter_library(opensource = FALSE)` to download and use the
## proprietary library from Bruker. The library file is downloaded and
## cached with *BiocFileCache* package. Alternatively, to download the
## library to a specific local path use the `path` parameter.
#'

---