R/MsBackendTimsTof-functions.R, R/MsBackendTimsTof.R
MsBackendTimsTof.RdThe 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.
MsBackendTimsTof()
# S4 method for class 'MsBackendTimsTof'
backendInitialize(object, files, ..., BPPARAM = bpparam())
# S4 method for class 'MsBackendTimsTof'
length(x)
# S4 method for class 'MsBackendTimsTof'
peaksData(object, columns = c("mz", "intensity"))
# S4 method for class 'MsBackendTimsTof'
peaksVariables(object)
# S4 method for class 'MsBackendTimsTof'
mz(object)
# S4 method for class 'MsBackendTimsTof'
intensity(object)
# S4 method for class 'MsBackendTimsTof'
rtime(object)
# S4 method for class 'MsBackendTimsTof'
x[i, j, ..., drop = FALSE]
# S4 method for class 'MsBackendTimsTof,ANY'
extractByIndex(object, i)
# S4 method for class 'MsBackendTimsTof'
dataStorage(object)
# S4 method for class 'MsBackendTimsTof'
spectraData(object, columns = spectraVariables(object))
# S4 method for class 'MsBackendTimsTof'
show(object)
# S4 method for class 'MsBackendTimsTof'
x$name
# S4 method for class 'MsBackendTimsTof'
selectSpectraVariables(object, spectraVariables = spectraVariables(object))
# S4 method for class 'MsBackendTimsTof'
x$name <- value
# S4 method for class 'MsBackendTimsTof'
precScanNum(object)
# S4 method for class 'MsBackendTimsTof'
spectraNames(object)
# S4 method for class 'MsBackendTimsTof'
tic(object, initial = TRUE)MsBackendTimsTof object.
character specifying TimsTOF ’*.d’ folders names.
Additional arguments.
Parameter object defining the parallel processing
setup to import data in parallel. Defaults to BPPARAM = bpparam().
See bpparam() for more information.
MsBackendTimsTof object.
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").
For [: integer, logical to subset the object.
For [: not supported.
For [: not considered.
For $: the name of the variable to access.
character with the names of the spectra variables
that should be retained in the returned object.
For $<-: the value to assign to the spectra variable.
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).
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.
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.
## Define the test file
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")
## Create a MsBackend instance for that file
be <- backendInitialize(MsBackendTimsTof(), fl)
be
#> MsBackendTimsTof with 9120 spectra
#> msLevel precursorMz polarity
#> <integer> <numeric> <integer>
#> 1 1 NA 1
#> 2 1 NA 1
#> 3 1 NA 1
#> 4 1 NA 1
#> 5 1 NA 1
#> ... ... ... ...
#> 9116 1 NA 1
#> 9117 1 NA 1
#> 9118 1 NA 1
#> 9119 1 NA 1
#> 9120 1 NA 1
#> ... 35 more variables/columns.
#> Use 'spectraVariables' to list all of them.
## Available spectra variables
spectraVariables(be)
#> [1] "msLevel" "rtime"
#> [3] "acquisitionNum" "scanIndex"
#> [5] "mz" "intensity"
#> [7] "dataStorage" "dataOrigin"
#> [9] "centroided" "smoothed"
#> [11] "polarity" "precScanNum"
#> [13] "precursorMz" "precursorIntensity"
#> [15] "precursorCharge" "collisionEnergy"
#> [17] "isolationWindowLowerMz" "isolationWindowTargetMz"
#> [19] "isolationWindowUpperMz" "tof"
#> [21] "inv_ion_mobility" "frameId"
#> [23] "ScanMode" "MsMsType"
#> [25] "TimsId" "MaxIntensity"
#> [27] "SummedIntensities" "NumScans"
#> [29] "NumPeaks" "MzCalibration"
#> [31] "T1" "T2"
#> [33] "TimsCalibration" "PropertyGroup"
#> [35] "AccumulationTime" "RampTime"
#> [37] "Pressure" "file"
## Available peaks variables
peaksVariables(be)
#> [1] "frame" "scan" "tof" "intensity"
#> [5] "mz" "inv_ion_mobility" "retention_time"
## Subset to 10 randomly selected spectra.
be_sub <- be[sort(sample(seq_along(be), 10))]
rtime(be_sub)
#> [1] 0.473940 1.264748 1.783703 2.046246 3.185555 3.441554 3.969275 4.315153
#> [9] 5.099894 6.129237
## 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
#> [[1]]
#> mz intensity tof inv_ion_mobility
#> [1,] 446.8664 48 140640 0.8944984
#>
#> [[2]]
#> mz intensity tof inv_ion_mobility
#> [1,] 519.1433 115 161415 1.001294
#>
#> [[3]]
#> mz intensity tof inv_ion_mobility
#> [1,] 521.8032 61 162151 0.8891046
#> [2,] 539.8064 23 167084 0.8891046
#>
#> [[4]]
#> mz intensity tof inv_ion_mobility
#> [1,] 487.9017 159 152625 0.8923409
#>
#> [[5]]
#> mz intensity tof inv_ion_mobility
#> [1,] 1221.97 152 315090 1.329234
#> [2,] 1223.00 40 315276 1.329234
#>
#> [[6]]
#> mz intensity tof inv_ion_mobility
#> [1,] 425.3518 129 134136 0.9915858
#>
#> [[7]]
#> mz intensity tof inv_ion_mobility
#> [1,] 1221.947 115 315086 1.343258
#> [2,] 1221.986 495 315093 1.343258
#> [3,] 1222.989 176 315274 1.343258
#> [4,] 1223.986 12 315454 1.343258
#>
#> [[8]]
#> mz intensity tof inv_ion_mobility
#> [1,] 1221.986 500 315093 1.336785
#> [2,] 1222.961 12 315269 1.336785
#> [3,] 1223.011 102 315278 1.336785
#> [4,] 1223.986 39 315454 1.336785
#>
#> [[9]]
#> mz intensity tof inv_ion_mobility
#> [1,] 1221.981 43 315092 1.362675
#>
#> [[10]]
#> mz intensity tof inv_ion_mobility
#> [1,] 519.1433 53 161415 0.9959008
#>
## Filter to data set to MS2 spectra only
be_ms2 <- filterMsLevel(be, 2L)
be_ms2
#> MsBackendTimsTof with 50 spectra
#> msLevel precursorMz polarity
#> <integer> <numeric> <integer>
#> 1 2 1221.99 1
#> 2 2 1221.99 1
#> 3 2 1221.99 1
#> 4 2 1221.99 1
#> 5 2 1221.99 1
#> ... ... ... ...
#> 46 2 1221.99 1
#> 47 2 1221.99 1
#> 48 2 1221.99 1
#> 49 2 1221.99 1
#> 50 2 1221.99 1
#> ... 35 more variables/columns.
#> Use 'spectraVariables' to list all of them.
## Get the full spectra data (including peaks variables)
spectraData(be_ms2)
#> DataFrame with 50 rows and 38 columns
#> msLevel rtime acquisitionNum scanIndex mz
#> <integer> <numeric> <integer> <integer> <NumericList>
#> 1 2 4.10207 NA 225 471.591,545.896,684.669,...
#> 2 2 4.10207 NA 226 323.133, 712.595,1221.942,...
#> 3 2 4.10207 NA 227 131.399,176.125,246.738,...
#> 4 2 4.10207 NA 228 637.171,1039.985,1057.704,...
#> 5 2 4.10207 NA 229 163.251,203.954,228.826,...
#> ... ... ... ... ... ...
#> 46 2 4.20924 NA 245 103.746,152.643,153.168,...
#> 47 2 4.20924 NA 246 499.549,589.305,891.086,...
#> 48 2 4.20924 NA 247 309.341, 826.619,1219.568,...
#> 49 2 4.20924 NA 248 666.879,1221.455,1221.931,...
#> 50 2 4.20924 NA 249 244.266,1221.981,1222.972,...
#> intensity dataStorage dataOrigin centroided
#> <NumericList> <character> <character> <logical>
#> 1 9,9,9,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 2 9,60,21,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 3 9,9,9,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 4 9,41,34,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 5 9,9,9,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> ... ... ... ... ...
#> 46 9,9,9,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 47 9,9,9,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 48 9,69,20,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 49 9,36,39,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> 50 9,256, 60,... /__w/_temp/Library/M.. /__w/_temp/Library/M.. NA
#> smoothed polarity precScanNum precursorMz precursorIntensity
#> <logical> <integer> <integer> <numeric> <numeric>
#> 1 NA 1 NA 1221.99 13042
#> 2 NA 1 NA 1221.99 13042
#> 3 NA 1 NA 1221.99 13042
#> 4 NA 1 NA 1221.99 13042
#> 5 NA 1 NA 1221.99 13042
#> ... ... ... ... ... ...
#> 46 NA 1 NA 1221.99 13042
#> 47 NA 1 NA 1221.99 13042
#> 48 NA 1 NA 1221.99 13042
#> 49 NA 1 NA 1221.99 13042
#> 50 NA 1 NA 1221.99 13042
#> precursorCharge collisionEnergy isolationWindowLowerMz
#> <integer> <numeric> <numeric>
#> 1 1 50.0807 1221.1
#> 2 1 50.0807 1221.1
#> 3 1 50.0807 1221.1
#> 4 1 50.0807 1221.1
#> 5 1 50.0807 1221.1
#> ... ... ... ...
#> 46 1 50.0807 1221.1
#> 47 1 50.0807 1221.1
#> 48 1 50.0807 1221.1
#> 49 1 50.0807 1221.1
#> 50 1 50.0807 1221.1
#> isolationWindowTargetMz isolationWindowUpperMz tof
#> <numeric> <numeric> <NumericList>
#> 1 1222.6 1224.1 147924,168734,204107,...
#> 2 1222.6 1224.1 100702,210777,315085,...
#> 3 1222.6 1224.1 18474,41304,72068,...
#> 4 1222.6 1224.1 192442,280902,284356,...
#> 5 1222.6 1224.1 35064,54056,64734,...
#> ... ... ... ...
#> 46 1222.6 1224.1 2347,29735,30003,...
#> 47 1222.6 1224.1 155934,180238,250630,...
#> 48 1222.6 1224.1 95806,236741,314656,...
#> 49 1222.6 1224.1 199787,314997,315083,...
#> 50 1222.6 1224.1 71072,315092,315271,...
#> inv_ion_mobility frameId ScanMode MsMsType TimsId MaxIntensity
#> <numeric> <integer> <integer> <integer> <integer> <integer>
#> 1 1.35728 31 8 8 114688 886
#> 2 1.35620 31 8 8 114688 886
#> 3 1.35512 31 8 8 114688 886
#> 4 1.35405 31 8 8 114688 886
#> 5 1.35297 31 8 8 114688 886
#> ... ... ... ... ... ... ...
#> 46 1.33571 32 8 8 118784 854
#> 47 1.33463 32 8 8 118784 854
#> 48 1.33355 32 8 8 118784 854
#> 49 1.33247 32 8 8 118784 854
#> 50 1.33139 32 8 8 118784 854
#> SummedIntensities NumScans NumPeaks MzCalibration T1 T2
#> <integer> <integer> <integer> <integer> <numeric> <numeric>
#> 1 19807 927 190 1 25.1431 23.9887
#> 2 19807 927 190 1 25.1431 23.9887
#> 3 19807 927 190 1 25.1431 23.9887
#> 4 19807 927 190 1 25.1431 23.9887
#> 5 19807 927 190 1 25.1431 23.9887
#> ... ... ... ... ... ... ...
#> 46 19168 927 214 1 25.1431 23.9887
#> 47 19168 927 214 1 25.1431 23.9887
#> 48 19168 927 214 1 25.1431 23.9887
#> 49 19168 927 214 1 25.1431 23.9887
#> 50 19168 927 214 1 25.1431 23.9887
#> TimsCalibration PropertyGroup AccumulationTime RampTime Pressure
#> <integer> <integer> <numeric> <numeric> <numeric>
#> 1 1 1 100.008 100.008 2.57282
#> 2 1 1 100.008 100.008 2.57282
#> 3 1 1 100.008 100.008 2.57282
#> 4 1 1 100.008 100.008 2.57282
#> 5 1 1 100.008 100.008 2.57282
#> ... ... ... ... ... ...
#> 46 1 1 100.008 100.008 2.57282
#> 47 1 1 100.008 100.008 2.57282
#> 48 1 1 100.008 100.008 2.57282
#> 49 1 1 100.008 100.008 2.57282
#> 50 1 1 100.008 100.008 2.57282
#> file
#> <integer>
#> 1 1
#> 2 1
#> 3 1
#> 4 1
#> 5 1
#> ... ...
#> 46 1
#> 47 1
#> 48 1
#> 49 1
#> 50 1
## Add a new spectra variable
be$new_var <- seq_along(be)
head(be$new_var)
#> [1] 1 2 3 4 5 6
## 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))
#> [1] 0.218626 0.218626 0.218626 0.218626 0.218626 0.218626
be$rtime <- rtime(be) + 10
head(rtime(be))
#> [1] 10.21863 10.21863 10.21863 10.21863 10.21863 10.21863