Package {opentimsr}

Encoding:	UTF-8
Type:	Package
Title:	An Open-Source Loader for Bruker's timsTOF Data Files
Version:	1.2.0
Date:	2026-09-24
Maintainer:	Mateusz Krzysztof Łącki <matteo.lacki@gmail.com>
Description:	Reads raw data from Bruker's timsTOF mass spectrometers, stored in analysis.tdf and analysis.tdf_bin files inside .d folders. Frames can be selected by number or by retention time, and each peak is reported with its scan, time-of-flight index, intensity, mass-to-charge ratio and inverse ion mobility. Mass-to-charge ratios and ion mobilities are computed with built-in open-source calibration, or optionally with Bruker's proprietary library. See Łącki et al. (2021) <doi:10.1021/acs.jproteome.0c00962>.
License:	MIT + file LICENSE
Copyright:	See file inst/COPYRIGHTS
URL:	https://github.com/michalsta/opentims
BugReports:	https://github.com/michalsta/opentims/issues
Depends:	R (≥ 4.3.0)
Imports:	Rcpp (≥ 0.12.0), methods, DBI, RSQLite
LinkingTo:	Rcpp
NeedsCompilation:	yes
SystemRequirements:	C++20, libzstd
Suggests:	testthat (≥ 3.0.0)
Config/roxygen2/version:	8.1.1
Packaged:	2026-10-13 09:38:52 UTC; matteo
Author:	Michał Piotr Startek [aut, cph], Mateusz Krzysztof Łącki [aut, cre, cph], mandreyel [ctb, cph] (Author and copyright holder of the bundled 'mio' library (https://github.com/mandreyel/mio))
Repository:	CRAN
Date/Publication:	2026-10-22 10:00:08 UTC

Close the TIMS data handle and release all resources.

Description

Calling this method is not mandatory - the resources will anyway be cleanly released when the garbage collector decides to destroy the OpenTIMS data handle. The only purpose of this method is to enable them to be explicitly released earlier than that.

Usage

CloseTIMS(opentims)

Arguments

Value

No return value, called for its side effect of closing the data handle.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
CloseTIMS(D)

Get MS1 frame numbers.

Description

Get MS1 frame numbers.

Usage

MS1(opentims)

Arguments

Value

Numbers of frames corresponding to MS1, i.e. precursor ions.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
MS1(D)
CloseTIMS(D)

Get OpenTIMS data representation.

Description

Get OpenTIMS data representation.

Usage

OpenTIMS(path.d)

Arguments

Value

An object of class OpenTIMS, used as the data handle by the other functions.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
D[1] # first frame
CloseTIMS(D)

TimsTOF data accessor.

Description

S4 class that facilitates data queries for TimsTOF data.

Slots

path.d

Path to raw data folder (typically *.d).

handle

Pointer to raw data.

min_frame

The index of the minimal frame.

max_frame

The index of the miximal frame.

min_scan

The minimal scan number. It is assumed to be equal to 1.

max_scan

The maximal scan number.

min_intensity

The minimal value of intensity. Set to 0, but actually 9 is more sensible.

max_intensity

The maximal intensity: the max over values reported in the frames.

min_retention_time

The lowest recorded retention time.

max_retention_time

The highest recorded retention time.

min_inv_ion_mobility

The minimal recorded inverse ion mobility.

max_inv_ion_mobility

The maximal recorded inverse ion mobility.

min_mz

The minimal recorded mass to charge ratio.

max_mz

The maximal recorded mass to charge ratio.

frames

A data.frame with information on the frames (contents of the Frames table in the sqlite db).

all_columns

Names of available columns.

Get some frames of data.

Description

Get some frames of data.

Usage

## S4 method for signature 'OpenTIMS'
x[i]

Arguments

Value

For the requested frames, a data.frame with columns 'frame', 'scan', 'tof' and 'intensity', one row per peak.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
head(D[1])   # first frame
head(D[1:2]) # frames 1 and 2
CloseTIMS(D)

Get Bruker's code needed for running proprietary time of flight to mass over charge and scan to drift time conversion.

Description

Bruker's 'timsdata' library is proprietary software owned by Bruker. It is not part of opentimsr and is not distributed with it: this function downloads it only when called, from "https://github.com/MatteoLacki/opentims_bruker_bridge", and by using it you agree to the license terms stated there. The library is available only for Linux and Windows. opentimsr works without it, using its built-in open-source converters (see setup_opensource).

Usage

download_bruker_proprietary_code(
  target.folder,
  net_url = paste0("https://raw.githubusercontent.com/MatteoLacki/",
    "opentims_bruker_bridge/main/opentims_bruker_bridge/"),
  mode = "wb",
  ...
)

Arguments

Value

Path to the output 'timsdata.dll' on Windows and 'libtimsdata.so' on Linux.

Examples

if (interactive()) {
  download_bruker_proprietary_code(tempdir())
}

Explore the contentents of the sqlite .tdf database.

Description

Explore the contentents of the sqlite .tdf database.

Usage

explore.tdf.tables(opentims, ...)

Arguments

Value

No return value, called for its side effect of printing the tables.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
if (interactive()) explore.tdf.tables(D)
CloseTIMS(D)

Get frames as separate data frames.

Description

Like query, but returns one data frame per frame instead of one table with the peaks of all frames. Frames are decoded in parallel (see opentims_set_threads). A frame requested more than once is returned once.

Usage

get_separate_frames(opentims, frames, columns = all_columns)

Arguments

Value

A named list of data.frames, one per distinct frame, in order of first request and named by frame number. Each data.frame has the requested columns, with one row per peak, as returned by query.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
frames = get_separate_frames(D, c(1, 2))
names(frames)
head(frames[["2"]])
get_separate_frames(D, 1, columns=c('scan','intensity')) # only 'scan' and 'intensity'
CloseTIMS(D)

Get the overall number of peaks.

Description

Get the overall number of peaks.

Usage

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

Arguments

Value

The total number of peaks in the dataset.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
length(D) # number of peaks in the dataset
CloseTIMS(D)

Get border values for measurements.

Description

Get the min-max values of the measured variables (except for TOFs, that would require iteration through data rather than parsing metadata).

Usage

min_max_measurements(opentims)

Arguments

Value

data.frame Limits of individual extracted quantities.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
min_max_measurements(D) # small data frame with min and max values
CloseTIMS(D)

Set the number of threads to be used for data processing by OpenTIMS

Description

Frames are decoded in parallel by query, query_slice, rt_query, [ and range. By default all detected cores are used; a value of 0 restores that default. When the environment variable _R_CHECK_LIMIT_CORES_ is set (as during R CMD check --as-cran), the default is two threads.

Usage

opentims_set_threads(n)

Arguments

Value

No return value, called for its side effect of setting the number of threads.

Examples

opentims_set_threads(1)

Get the number of peaks per frame.

Description

Get the number of peaks per frame.

Usage

peaks_per_frame_cnts(opentims)

Arguments

Value

Number of peaks in each frame.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
peaks_per_frame_cnts(D)
CloseTIMS(D)

Query for raw data.

Description

Get the raw data from Bruker's 'tdf_bin' format. Defaults to both raw data ('frame','scan','tof','intensity') and its tranformations into physical units ('mz','inv_ion_mobility','retention_time').

Usage

query(opentims, frames, columns = all_columns)

Arguments

Value

data.frame with selected columns.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
query(D, c(1, 2)) # extract all columns
query(D, c(1, 2), columns=c('scan','intensity')) # only 'scan' and 'intensity'
CloseTIMS(D)

Query for raw data.

Description

Get the raw data from Bruker's 'tdf_bin' format. Defaults to both raw data ('frame','scan','tof','intensity') and its tranformations into physical units ('mz','inv_ion_mobility','retention_time').

Usage

query_slice(opentims, from = NULL, to = NULL, by = 1, columns = all_columns)

Arguments

Details

We assume 'from' <= 'to'.

Value

data.frame with selected columns.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
query_slice(D, 1, 2)    # frames 1 to 2
query_slice(D, 1, 2, 2) # every second frame between 1 and 2
query_slice(D, 1, 2, columns=c('scan','intensity')) # only 'scan' and 'intensity'
CloseTIMS(D)

Select a range of frames to extract.

Description

This is similar to using the from:to:by operator in Python.

Usage

## S4 method for signature 'OpenTIMS'
range(x, from, to, by = 1L, na.rm = FALSE)

Arguments

Value

For the selected frames, a data.frame with columns 'frame', 'scan', 'tof' and 'intensity', one row per peak.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
head(range(D, 1, 3))    # frames 1 and 2
head(range(D, 1, 3, 2)) # every second frame, i.e. only frame 1
CloseTIMS(D)

Get the retention time for each frame.

Description

Get the retention time for each frame.

Usage

retention_times(opentims)

Arguments

Value

Retention times corresponding to each frame.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
retention_times(D)
CloseTIMS(D)

Get the retention time for each frame.

Description

Extract all frames corresponding to retention times inside [min_retention_time, max_retention_time] closed borders interval.

Usage

rt_query(
  opentims,
  min_retention_time,
  max_retention_time,
  columns = all_columns
)

Arguments

Value

data.frame with selected columns.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
rt_query(D, 0.6, 0.7) # frames recorded between 0.6 and 0.7 seconds
CloseTIMS(D)

Dynamically link Bruker's DLL to enable tof-mz and scan-inv_ion_mobility conversion.

Description

Bruker's 'timsdata' library is proprietary software owned by Bruker. It is not part of opentimsr and is not distributed with it; obtain it with download_bruker_proprietary_code, whose license terms apply. The library is available only for Linux and Windows. opentimsr works without it, using its built-in open-source converters (see setup_opensource).

Usage

setup_bruker_so(path)

Arguments

Value

No return value, called for its side effect of switching the conversion backend.

Examples

if (interactive()) {
  so_path = download_bruker_proprietary_code(tempdir())
  setup_bruker_so(so_path)
}

Use the built-in open-source tof-to-mz and scan-to-inv_ion_mobility converters.

Description

Activates the built-in open-source converters for tof-to-mz and scan-to-inv_ion_mobility transformations. No proprietary Bruker libraries are required. This is the default mode; call this function before querying data if you have not called setup_bruker_so.

Usage

setup_opensource()

Value

No return value, called for its side effect of switching the conversion backend.

Examples

setup_opensource()

Extract tables from sqlite database analysis.tdf.

Description

Export a table from sqlite.

Usage

table2df(opentims, names)

Arguments

Value

A list of tables.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
head(table2df(D, "Frames")$Frames) # extract table "Frames"
CloseTIMS(D)

Extract tables from sqlite database analysis.tdf.

Description

Extract tables from sqlite database analysis.tdf.

Usage

tables_names(opentims)

Arguments

Value

Names of tables.

Examples

path.d = system.file("extdata", "test.d", package = "opentimsr")
setup_opensource()
D = OpenTIMS(path.d)
tables_names(D)
CloseTIMS(D)

Use a lookup table for inverse ion mobility conversion with Bruker's library.

Description

Like use_mz_lookup, for inverse ion mobility. opentimsr uses no pressure compensation, so this conversion is the same in every frame and the table is exact for all frames.

Usage

use_inv_ion_mobility_lookup(opentims, frame = 1L)

Arguments

Value

No return value, called for its side effect of changing the conversion.

Examples

if (interactive()) {
  setup_bruker_so(download_bruker_proprietary_code(tempdir()))
  D = OpenTIMS(system.file("extdata", "test.d", package = "opentimsr"))
  use_inv_ion_mobility_lookup(D)
  CloseTIMS(D)
}

Use a lookup table for m/z conversion with Bruker's library.

Description

Bruker's library converts one frame at a time and can only be called by one thread at a time, which limits parallel extraction. After this call, m/z values come from a table holding the m/z of every tof index for frame, computed once by Bruker's library and then used for all frames.

Usage

use_mz_lookup(opentims, frame = 1L)

Arguments

Details

Values are exact for frame and approximate for other frames: Bruker's m/z calibration changes slightly from frame to frame (by at most 0.16 ppm over four test datasets). The function can be called again with another frame, which refills the same table, or with NULL to return to exact conversion. Only available with Bruker's conversion (see setup_bruker_so).

Value

No return value, called for its side effect of changing the conversion.

Examples

if (interactive()) {
  setup_bruker_so(download_bruker_proprietary_code(tempdir()))
  D = OpenTIMS(system.file("extdata", "test.d", package = "opentimsr"))
  use_mz_lookup(D)        # calibration of frame 1 for all frames
  use_mz_lookup(D, 2)     # calibration of frame 2 instead
  use_mz_lookup(D, NULL)  # back to exact conversion
  CloseTIMS(D)
}