vignettes/MsBackendTimsTof.Rmd
MsBackendTimsTof.RmdThe Spectra package provides a central infrastructure for Mass Spectrometry (MS) data in R. The package supports interchangeable use of different backends to represent or import MS data from a variety of formats and sources (such as mzML files). The MsBackendTimsTof” package adds support for MS data from Bruker TimsTOF raw data files. This vignette shows how, and which data can be retrieved from such files.
The package depends on the OpenTIMS C++ library to access data in timsTOF Pro data format (TDF) which is provided by the opentimsr R package. The opentimsr and MsBackendTimsTof package can be installed with:
BiocManager::install("michalsta/opentims/src/opentimsr")
BiocManager::install("RforMassSpectrometry/MsBackendTimsTof")Some variables in the data files can only be accessed after setting up a converter library. Two options are available. The first is to use the open-source library built into opentimsr:
The setup_converter_library() function is also run on
package startup hence, to use the default, no manual call to
setup_converter_library() is needed.
Alternatively it is possible to use the proprietary Bruker converter library, which can be downloaded and cached through BiocFileCache or downloaded to a personal folder. Note that this library is currently only available for Windows and Linux (no macOS support).
setup_converter_library(opensource = FALSE)The MsBackendTimsTof
package adds support for Bruker TimsTOF files to
Spectra-based analysis workflows. Below we load the package
which will also automatically setup the use of the open-source converter
library.
As detailed in the installation section, the code to download the
shared library would only be necessary once, if the path to this file is
defined in a environment variable TIMSTOF_LIB.
We next load the TDF test file which is bundled within this package.
## Get the path/file name of the example file
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")
## Initialize the MsBackend
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.In a real use case, we would however directly load the data into a
Spectra object:
sps <- Spectra(fl, source = MsBackendTimsTof())
sps## MSn data (Spectra) with 9120 spectra in a MsBackendTimsTof backend:
## 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.We thus have access to all spectra variables within the file:
spectraVariables(sps)## [1] "msLevel" "rtime"
## [3] "acquisitionNum" "scanIndex"
## [5] "dataStorage" "dataOrigin"
## [7] "centroided" "smoothed"
## [9] "polarity" "precScanNum"
## [11] "precursorMz" "precursorIntensity"
## [13] "precursorCharge" "collisionEnergy"
## [15] "isolationWindowLowerMz" "isolationWindowTargetMz"
## [17] "isolationWindowUpperMz" "frameId"
## [19] "ScanMode" "MsMsType"
## [21] "TimsId" "MaxIntensity"
## [23] "SummedIntensities" "NumScans"
## [25] "NumPeaks" "MzCalibration"
## [27] "T1" "T2"
## [29] "TimsCalibration" "PropertyGroup"
## [31] "AccumulationTime" "RampTime"
## [33] "Pressure" "file"And the full data for spectra variables can be retrieved with
spectraData:
all <- spectraData(sps)
all## DataFrame with 9120 rows and 34 columns
## msLevel rtime acquisitionNum scanIndex dataStorage
## <integer> <numeric> <integer> <integer> <character>
## 1 1 0.218626 NA 218 /__w/_temp/Library/M..
## 2 1 0.218626 NA 220 /__w/_temp/Library/M..
## 3 1 0.218626 NA 221 /__w/_temp/Library/M..
## 4 1 0.218626 NA 222 /__w/_temp/Library/M..
## 5 1 0.218626 NA 223 /__w/_temp/Library/M..
## ... ... ... ... ... ...
## 9116 1 6.7812 NA 719 /__w/_temp/Library/M..
## 9117 1 6.7812 NA 723 /__w/_temp/Library/M..
## 9118 1 6.7812 NA 726 /__w/_temp/Library/M..
## 9119 1 6.7812 NA 727 /__w/_temp/Library/M..
## 9120 1 6.7812 NA 730 /__w/_temp/Library/M..
## dataOrigin centroided smoothed polarity precScanNum
## <character> <logical> <logical> <integer> <integer>
## 1 /__w/_temp/Library/M.. NA NA 1 NA
## 2 /__w/_temp/Library/M.. NA NA 1 NA
## 3 /__w/_temp/Library/M.. NA NA 1 NA
## 4 /__w/_temp/Library/M.. NA NA 1 NA
## 5 /__w/_temp/Library/M.. NA NA 1 NA
## ... ... ... ... ... ...
## 9116 /__w/_temp/Library/M.. NA NA 1 NA
## 9117 /__w/_temp/Library/M.. NA NA 1 NA
## 9118 /__w/_temp/Library/M.. NA NA 1 NA
## 9119 /__w/_temp/Library/M.. NA NA 1 NA
## 9120 /__w/_temp/Library/M.. NA NA 1 NA
## precursorMz precursorIntensity precursorCharge collisionEnergy
## <numeric> <numeric> <integer> <numeric>
## 1 NA NA NA NA
## 2 NA NA NA NA
## 3 NA NA NA NA
## 4 NA NA NA NA
## 5 NA NA NA NA
## ... ... ... ... ...
## 9116 NA NA NA NA
## 9117 NA NA NA NA
## 9118 NA NA NA NA
## 9119 NA NA NA NA
## 9120 NA NA NA NA
## isolationWindowLowerMz isolationWindowTargetMz isolationWindowUpperMz
## <numeric> <numeric> <numeric>
## 1 NA NA NA
## 2 NA NA NA
## 3 NA NA NA
## 4 NA NA NA
## 5 NA NA NA
## ... ... ... ...
## 9116 NA NA NA
## 9117 NA NA NA
## 9118 NA NA NA
## 9119 NA NA NA
## 9120 NA NA NA
## frameId ScanMode MsMsType TimsId MaxIntensity SummedIntensities
## <integer> <integer> <integer> <integer> <integer> <integer>
## 1 1 8 0 0 734 44601
## 2 1 8 0 0 734 44601
## 3 1 8 0 0 734 44601
## 4 1 8 0 0 734 44601
## 5 1 8 0 0 734 44601
## ... ... ... ... ... ... ...
## 9116 52 8 0 208896 742 42368
## 9117 52 8 0 208896 742 42368
## 9118 52 8 0 208896 742 42368
## 9119 52 8 0 208896 742 42368
## 9120 52 8 0 208896 742 42368
## NumScans NumPeaks MzCalibration T1 T2 TimsCalibration
## <integer> <integer> <integer> <numeric> <numeric> <integer>
## 1 927 348 1 25.143 23.9875 1
## 2 927 348 1 25.143 23.9875 1
## 3 927 348 1 25.143 23.9875 1
## 4 927 348 1 25.143 23.9875 1
## 5 927 348 1 25.143 23.9875 1
## ... ... ... ... ... ... ...
## 9116 927 304 1 25.143 23.9898 1
## 9117 927 304 1 25.143 23.9898 1
## 9118 927 304 1 25.143 23.9898 1
## 9119 927 304 1 25.143 23.9898 1
## 9120 927 304 1 25.143 23.9898 1
## PropertyGroup AccumulationTime RampTime Pressure file
## <integer> <numeric> <numeric> <numeric> <integer>
## 1 1 100.008 100.008 2.57282 1
## 2 1 100.008 100.008 2.57282 1
## 3 1 100.008 100.008 2.57282 1
## 4 1 100.008 100.008 2.57282 1
## 5 1 100.008 100.008 2.57282 1
## ... ... ... ... ... ...
## 9116 1 100.008 100.008 2.57283 1
## 9117 1 100.008 100.008 2.57283 1
## 9118 1 100.008 100.008 2.57283 1
## 9119 1 100.008 100.008 2.57283 1
## 9120 1 100.008 100.008 2.57283 1The data is organized by individual spectra, all spectra measured
within the same frame have the same value in the spectra
variable "frameId". This also means that the
scanIndex is not unique within a file,
only within one frame:
sps$scanIndex |> anyDuplicated()## [1] 182The combination of frameId and scanIndex
identifies each spectrum uniquely within the same file:
spectraData(sps, c("frameId", "scanIndex", "file"))## DataFrame with 9120 rows and 3 columns
## frameId scanIndex file
## <integer> <integer> <integer>
## 1 1 218 1
## 2 1 220 1
## 3 1 221 1
## 4 1 222 1
## 5 1 223 1
## ... ... ... ...
## 9116 52 719 1
## 9117 52 723 1
## 9118 52 726 1
## 9119 52 727 1
## 9120 52 730 1The inverse ion mobility data is provided by the
"inv_ion_mobility" variable. This information can be
extracted as a spectra variable (i.e., one value per
spectrum):
## Get the ion mobility information
sps$inv_ion_mobility |> head()## [1] 1.364833 1.362675 1.361597 1.360518 1.359439 1.358360But can also be requested to be added to the
peaksData(). Below we extract the full peaks data (i.e.,
all peaks variables for all spectra) and show the information
of one selected spectrum:
## Request all supported peaks variables
pd <- peaksData(sps, peaksVariables(sps))
## Show the data for the spectrum number 10
pd[[10L]]## frame scan tof intensity mz inv_ion_mobility retention_time
## [1,] 1 228 315083 36 1221.931 1.354045 0.218626
## [2,] 1 228 315091 321 1221.975 1.354045 0.218626
## [3,] 1 228 315095 116 1221.997 1.354045 0.218626
## [4,] 1 228 315270 50 1222.967 1.354045 0.218626
## [5,] 1 228 315277 65 1223.005 1.354045 0.218626
## [6,] 1 228 315453 59 1223.981 1.354045 0.218626Note however that "inv_ion_mobility" and
"retention_time" have the same value for all peaks in each
spectrum. Thus, these variables should be accessed not through
peaksData(), but through spectraData() or
using the $ operator or the dedicated rtime()
function.
The MsBackendTimsTof is a on-disk backend,
hence reading peaks and spectra variables from the original data file(s)
upon request. Modifying spectra variables within the raw data files is
not possible (and also not desired), but, by directly extending the
MsBackendCached backend from the Spectra
package MsBackendTimsTof supports changing or adding
spectra variables by caching them locally within the object.
Below we add a new spectra variable to the object.
## Add a new spectra variable
sps$new_variable <- seq_along(sps)This new variable is now available within the object and can be extract like any other spectra variable.
spectraVariables(sps)## [1] "msLevel" "rtime"
## [3] "acquisitionNum" "scanIndex"
## [5] "dataStorage" "dataOrigin"
## [7] "centroided" "smoothed"
## [9] "polarity" "precScanNum"
## [11] "precursorMz" "precursorIntensity"
## [13] "precursorCharge" "collisionEnergy"
## [15] "isolationWindowLowerMz" "isolationWindowTargetMz"
## [17] "isolationWindowUpperMz" "new_variable"
## [19] "frameId" "ScanMode"
## [21] "MsMsType" "TimsId"
## [23] "MaxIntensity" "SummedIntensities"
## [25] "NumScans" "NumPeaks"
## [27] "MzCalibration" "T1"
## [29] "T2" "TimsCalibration"
## [31] "PropertyGroup" "AccumulationTime"
## [33] "RampTime" "Pressure"
## [35] "file"
sps$new_variable |> head()## [1] 1 2 3 4 5 6Analogously it is also possible to change existing spectra variables. Below we shift each retention time by 10 seconds.
## [1] 0.218626 0.218626 0.218626 0.218626 0.218626 0.218626## [1] 10.21863 10.21863 10.21863 10.21863 10.21863 10.21863## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.4 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] MsBackendTimsTof_0.98.3 Spectra_1.23.5 BiocParallel_1.47.0
## [4] S4Vectors_0.51.10 BiocGenerics_0.59.12 generics_0.1.4
## [7] BiocStyle_2.41.0
##
## loaded via a namespace (and not attached):
## [1] sass_0.4.10 MsCoreUtils_1.25.4 RSQLite_3.53.3
## [4] digest_0.6.39 magrittr_2.0.5 evaluate_1.0.5
## [7] bookdown_0.48 fastmap_1.2.0 blob_1.3.0
## [10] jsonlite_2.0.0 ProtGenerics_1.45.0 DBI_1.3.0
## [13] BiocManager_1.30.27 codetools_0.2-20 textshaping_1.0.5
## [16] jquerylib_0.1.4 cli_3.6.6 opentimsr_1.2.0
## [19] rlang_1.3.0 bit64_4.8.6 cachem_1.1.0
## [22] yaml_2.3.12 otel_0.2.0 tools_4.6.1
## [25] parallel_4.6.1 memoise_2.0.1 dplyr_1.2.1
## [28] vctrs_0.7.3 R6_2.6.1 lifecycle_1.0.5
## [31] fs_2.1.0 htmlwidgets_1.6.4 IRanges_2.47.5
## [34] bit_4.6.0 clue_0.3-68 MASS_7.3-66
## [37] ragg_1.5.2 cluster_2.1.8.3 pkgconfig_2.0.3
## [40] desc_1.4.3 pkgdown_2.2.1.9000 bslib_0.12.0
## [43] pillar_1.11.1 Rcpp_1.1.2 data.table_1.18.6.1
## [46] glue_1.8.1 systemfonts_1.3.2 tidyselect_1.2.1
## [49] tibble_3.3.1 xfun_0.61 knitr_1.52
## [52] htmltools_0.5.9 rmarkdown_2.32 compiler_4.6.1
## [55] MetaboCoreUtils_1.21.1