Package: MsBackendTimsTof
Authors: Johannes Rainer [aut, cre] (ORCID: https://orcid.org/0000-0002-6977-7147), Andrea Vicini
[aut] (ORCID: https://orcid.org/0000-0001-9438-6909), Steffen Neumann
[ctb] (ORCID: https://orcid.org/0000-0002-7899-7192), Carolin Huber
[ctb] (ORCID: https://orcid.org/0000-0002-9355-8948)
Compiled: Wed Jun 24 10:25:57 2026
The Spectra package provides a central infrastructure for the handling of Mass Spectrometry (MS) data. The package supports interchangeable use of different backends to import MS data from a variety of sources (such as mzML files). The MsBackendTimsTof package adds support for 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")To get some variables from the data files an additional library from the manufacturer is needed. This library can be downloaded with:
This downloads the shared library to a temporary folder. Note however that at present this shared library is only available for Windows and Linux (i.e. no macOS support). Next, to use this library, it has to be registered with the opentimsr package:
These steps would be necessary for every new R session. To avoid
that, it is suggested to copy the downloaded shared library above to a
directory on the computer and to define an environment variable called
TIMSTOF_LIB that defines the full path where this file is
located (i.e. a character string defining the full file path with the
file name). This variable can either be defined system wide, or within
the .Rprofile file. An example entry in a .Rprofile
could for example be:
options(TIMSTOF_LIB = "/home/jo/lib/libtimsdata.so")The MsBackendTimsTof
package adds support for Bruker TimsTOF files to
Spectra-based analysis workflows. Below we load the package
and in addition fetch the required shared library and store that to a
temporary folder.
library(MsBackendTimsTof)
## Load the opentimsr package and download and register the shared library
library(opentimsr)
so_folder <- tempdir()
so_file <- download_bruker_proprietary_code(so_folder, method = "wget")## [1] "Downloading 64-bit Linux binary."
## [1] "Downloading from: https://raw.githubusercontent.com/MatteoLacki/opentims_bruker_bridge/main/opentims_bruker_bridge/libtimsdata.so"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.
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")
be <- backendInitialize(MsBackendTimsTof(), fl)In a real use case, we would however directly load the data into a
Spectra object:
## 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:
## [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"And the full data can be retrieved with spectraData:
## DataFrame with 9120 rows and 38 columns
## msLevel rtime acquisitionNum scanIndex mz intensity
## <integer> <numeric> <integer> <integer> <NumericList> <NumericList>
## 1 1 0.218626 NA 218 1221.98 52
## 2 1 0.218626 NA 220 1222 93
## 3 1 0.218626 NA 221 1221.99 108
## 4 1 0.218626 NA 222 1222.00,1224.01 38,57
## 5 1 0.218626 NA 223 1222.00,1222.02 61,34
## ... ... ... ... ... ... ...
## 9116 1 6.7812 NA 719 425.83 82
## 9117 1 6.7812 NA 723 425.84 78
## 9118 1 6.7812 NA 726 425.84 89
## 9119 1 6.7812 NA 727 425.837 50
## 9120 1 6.7812 NA 730 738.739 77
## dataStorage dataOrigin centroided smoothed
## <character> <character> <logical> <logical>
## 1 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 2 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 3 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 4 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 5 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## ... ... ... ... ...
## 9116 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 9117 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 9118 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 9119 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## 9120 /tmp/RtmpqCVV2d/Rins.. /tmp/RtmpqCVV2d/Rins.. NA NA
## polarity precScanNum precursorMz precursorIntensity precursorCharge
## <integer> <integer> <numeric> <numeric> <integer>
## 1 1 NA NA NA NA
## 2 1 NA NA NA NA
## 3 1 NA NA NA NA
## 4 1 NA NA NA NA
## 5 1 NA NA NA NA
## ... ... ... ... ... ...
## 9116 1 NA NA NA NA
## 9117 1 NA NA NA NA
## 9118 1 NA NA NA NA
## 9119 1 NA NA NA NA
## 9120 1 NA NA NA NA
## collisionEnergy isolationWindowLowerMz isolationWindowTargetMz
## <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
## isolationWindowUpperMz tof inv_ion_mobility frameId ScanMode
## <numeric> <NumericList> <numeric> <integer> <integer>
## 1 NA 315091 1.39278 1 8
## 2 NA 315094 1.39053 1 8
## 3 NA 315092 1.38940 1 8
## 4 NA 315093,315457 1.38827 1 8
## 5 NA 315094,315097 1.38715 1 8
## ... ... ... ... ... ...
## 9116 NA 134284 0.831408 52 8
## 9117 NA 134287 0.826949 52 8
## 9118 NA 134287 0.823604 52 8
## 9119 NA 134286 0.822490 52 8
## 9120 NA 216904 0.819146 52 8
## MsMsType TimsId MaxIntensity SummedIntensities NumScans NumPeaks
## <integer> <integer> <integer> <integer> <integer> <integer>
## 1 0 0 734 44601 927 348
## 2 0 0 734 44601 927 348
## 3 0 0 734 44601 927 348
## 4 0 0 734 44601 927 348
## 5 0 0 734 44601 927 348
## ... ... ... ... ... ... ...
## 9116 0 208896 742 42368 927 304
## 9117 0 208896 742 42368 927 304
## 9118 0 208896 742 42368 927 304
## 9119 0 208896 742 42368 927 304
## 9120 0 208896 742 42368 927 304
## MzCalibration T1 T2 TimsCalibration PropertyGroup
## <integer> <numeric> <numeric> <integer> <integer>
## 1 1 25.143 23.9875 1 1
## 2 1 25.143 23.9875 1 1
## 3 1 25.143 23.9875 1 1
## 4 1 25.143 23.9875 1 1
## 5 1 25.143 23.9875 1 1
## ... ... ... ... ... ...
## 9116 1 25.143 23.9898 1 1
## 9117 1 25.143 23.9898 1 1
## 9118 1 25.143 23.9898 1 1
## 9119 1 25.143 23.9898 1 1
## 9120 1 25.143 23.9898 1 1
## AccumulationTime RampTime Pressure file
## <numeric> <numeric> <numeric> <integer>
## 1 100.008 100.008 2.57282 1
## 2 100.008 100.008 2.57282 1
## 3 100.008 100.008 2.57282 1
## 4 100.008 100.008 2.57282 1
## 5 100.008 100.008 2.57282 1
## ... ... ... ... ...
## 9116 100.008 100.008 2.57283 1
## 9117 100.008 100.008 2.57283 1
## 9118 100.008 100.008 2.57283 1
## 9119 100.008 100.008 2.57283 1
## 9120 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". Spectra variable
"inv_ion_mobility" provides the inverse ion
mobility information. This variable is available as a spectra
variable, but also as a peaks variable along with
e.g. "tof". Available peaks variables can be listed with
the peaksVariables() function.
## [1] "frame" "scan" "tof" "intensity"
## [5] "mz" "inv_ion_mobility" "retention_time"Below we subset the backend to a range of spectra and extract their
peaksData.
sps_sub <- sps[224:227]
peaksData(sps_sub, columns = c("mz", "intensity", "tof", "inv_ion_mobility",
"retention_time")) |> as.list()## [[1]]
## mz intensity tof inv_ion_mobility retention_time
## [1,] 921.9999 123 257111 1.188193 0.344953
##
## [[2]]
## mz intensity tof inv_ion_mobility retention_time
## [1,] 921.9999 47 257111 1.187071 0.344953
## [2,] 923.0248 18 257324 1.187071 0.344953
##
## [[3]]
## mz intensity tof inv_ion_mobility retention_time
## [1,] 923.0248 83 257324 1.185949 0.344953
##
## [[4]]
## mz intensity tof inv_ion_mobility retention_time
## [1,] 922.0095 104 257113 1.184827 0.344953
## [2,] 923.0103 119 257321 1.184827 0.344953
## [3,] 924.0165 45 257530 1.184827 0.344953Note however that both the "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. Below we extract the inverse ion mobility values and display
the first 6 of them.
## [1] 1.392779 1.390527 1.389401 1.388274 1.387148 1.386022The 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.
This new variable is now available within the object and can be extract like any other spectra variable.
## [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"## [1] 1 2 3 4 5 6Analogously it is also possible to change existing spectra variables. Below we add a value to each retention time.
## [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.0 (2026-04-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04 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.32.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: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] opentimsr_1.2.0 MsBackendTimsTof_0.2.0 Spectra_1.23.3
## [4] BiocParallel_1.47.0 S4Vectors_0.51.3 BiocGenerics_0.59.7
## [7] generics_0.1.4 BiocStyle_2.41.0
##
## loaded via a namespace (and not attached):
## [1] bit_4.6.0 jsonlite_2.0.0 compiler_4.6.0
## [4] BiocManager_1.30.27 Rcpp_1.1.1-1.1 blob_1.3.0
## [7] parallel_4.6.0 cluster_2.1.8.2 jquerylib_0.1.4
## [10] IRanges_2.47.2 yaml_2.3.12 fastmap_1.2.0
## [13] R6_2.6.1 ProtGenerics_1.39.2 knitr_1.51
## [16] MASS_7.3-65 maketools_1.3.2 DBI_1.3.0
## [19] bslib_0.11.0 rlang_1.2.0 cachem_1.1.0
## [22] xfun_0.59 fs_2.1.0 MsCoreUtils_1.25.4
## [25] sass_0.4.10 sys_3.4.3 bit64_4.8.2
## [28] otel_0.2.0 memoise_2.0.1 RSQLite_3.53.2
## [31] cli_3.6.6 digest_0.6.39 MetaboCoreUtils_1.21.1
## [34] lifecycle_1.0.5 clue_0.3-68 vctrs_0.7.3
## [37] evaluate_1.0.5 data.table_1.18.4 codetools_0.2-20
## [40] buildtools_1.0.0 rmarkdown_2.31 pkgconfig_2.0.3
## [43] tools_4.6.0 htmltools_0.5.9