Package 'isoorbi'

Description

Read and process isotopocule data from an Orbitrap Isotope Solutions mass spectrometer. Citation: Kantnerova et al. (Nature Protocols, 2024).

Details

Resources:

• Website for the isoorbi package: https://isoorbi.isoverse.org

• Package options: orbi_options

Author(s)

Maintainer: Caj Neubauer [email protected] (ORCID) [copyright holder]

Authors:

• Sebastian Kopf [email protected] (ORCID)

• Kristýna Kantnerová [email protected] (ORCID)

See Also

Useful links:

• https://isoorbi.isoverse.org/

• https://github.com/isoverse/isoorbi

• Report bugs at https://github.com/isoverse/isoorbi/issues

Description

This function can be used to add colored background to a plot of dual-inlet data where different colors signify different data types (data, startup time, changeover time, unused). Note that this function only works with continuous and pseudo-log y axis, not with log y axes.

Usage

orbi_add_blocks_to_plot(
  plot,
  x = c("guess", "scan.no", "time.min"),
  data_only = FALSE,
  fill = .data$data_type,
  fill_colors = c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02",
    "#A6761D", "#666666"),
  fill_scale = scale_fill_manual("blocks", values = fill_colors),
  alpha = 0.5,
  show.legend = !data_only
)

Arguments

Description

This function can be used to manually adjust where certain block starts or ends after it's been defined with orbi_define_block_for_flow_injection() or orbi_define_blocks_for_dual_inlet() using either time or scan number. Note that adjusting blocks removes all block segmentation. Make sure to call orbi_segment_blocks() after adjusting block delimiters.

Usage

orbi_adjust_block(
  dataset,
  block,
  filename = NULL,
  shift_start_time.min = NULL,
  shift_end_time.min = NULL,
  shift_start_scan.no = NULL,
  shift_end_scan.no = NULL,
  set_start_time.min = NULL,
  set_end_time.min = NULL,
  set_start_scan.no = NULL,
  set_end_scan.no = NULL
)

Arguments

Value

A data frame (tibble) with block limits altered according to the provided start/end change parameters. Any data that is no longer part of the original block will be marked with the value of orbi_get_option("data_type_unused"). Any previously applied segmentation will be discarded (segment column set to NA) to avoid unintended side effects.

Description

This function allows dynamic aggregation and validation of data read by orbi_read_raw(). Like orbi_read_raw(), it is designed to be fail save by safely catching errors and reporting back on them (see orbi_get_problems()). This function should work out of the box for most files without additional modification of the aggregator.

Usage

orbi_aggregate_raw(
  files_data,
  aggregator = "standard",
  show_progress = rlang::is_interactive(),
  show_problems = TRUE
)

Arguments

Value

a list of merged dataframes collected from the files_data based on the aggregator definitions

Description

This function computes the shot noise calculation.

Usage

orbi_analyze_shot_noise(dataset, include_flagged_data = FALSE)

Arguments

Details

Analyze shot noise

will calculate for all combinations of filename, compound, and isotopocule in the provided dataset

Value

The processed data frame with new columns: n_effective_ions, ratio, ratio_rel_se.permil, shot_noise.permil

Description

This functions calculates ions (ions.incremental) from intensities based on the equation

$N_{ions} = S/N \cdot{} C_N/z \cdot{} \sqrt{R_N/R} \cdot \sqrt{N_{MS}}$

where S is the reported signal (intensity) of the isotopocule, N is the noise associated with the signal (peakNoise), measured at the resolution setting R (resolution), the noise factor $C_N$ (CN) is the number of charges corresponding to the Orbitrap noise band at some reference resolution $R_N$ (RN), $N_{MS}$ is the number of microscans, and z is the charge per ion (charge) of the isotopocule. See Makarov and Denisov (2009) and Eiler et al. (2017) for details about this equation. The default values for CN and RN are from the Orbitrap Exploris Isotope Solutions Getting Started Guide (BRE0032999, Revision A, October 2022). Note that the exact values of these factors are only critical if the number of ions are interpreted outside of ratio calculations (in ratio calculations, these factors cancel).

Usage

orbi_calculate_ions(dataset, CN = 3, RN = 240000)

Arguments

Details

If using a dataset read from isox files you might have to add a charge column if it does not yet exist that indicates the charge of the isotopocule. If using data from raw files, orbi_identify_isotopocules() will automatically call this function with the default CN and RN so you don't need to call it explicitly unless you want to change these parameters.

Value

same object as provided in dataset with new column ions.incremental

Description

This function calculates isotopocule/base peak ratios for all isotopocules. It does not summarize or average the ratios in any way. For a summarizing version of this function, see orbi_summarize_results().

Usage

orbi_calculate_ratios(dataset)

Arguments

Value

Returns a mutated dataset with ratio column added.

Description

This function calculates the ratio of two isotopocules (the numerator and denominator). This function averages multiple measurements of each using the ratio_method and returns a single value. Normally this function is not called directly by the user, but via the function orbi_summarize_results(), which calculates isotopocule ratios and other results for an entire dataset.

Usage

orbi_calculate_summarized_ratio(
  numerator,
  denominator,
  ratio_method = c("direct", "mean", "sum", "median", "geometric_mean", "slope",
    "weighted_sum")
)

Arguments

Value

Single value ratio between the isotopocules defined as numerator and denominator calculated using the ratio_method.

Examples

df <-
  system.file("extdata", "testfile_flow.isox", package = "isoorbi") |>
  orbi_read_isox()

ions_18O <- dplyr::filter(df, isotopocule == "18O")$ions.incremental
ions_M0 <- dplyr::filter(df, isotopocule == "M0")$ions.incremental

orbi_calculate_summarized_ratio(
  numerator = ions_18O, denominator = ions_M0, ratio_method = "sum"
)

orbi_calculate_summarized_ratio(
  numerator = ions_18O, denominator = ions_M0, ratio_method = "slope"
)

Description

By default, this will install the isoraw reader if it is missing or outdated, and will ask the user to agree to Thermo's license agreement for the Thermo RawFileReader before proceeding. This function runs automatically during a raw file read and does not usually need to be called directly by the user.

Usage

orbi_check_isoraw(
  install_if_missing = !on_cran(),
  reinstall_if_outdated = !on_cran(),
  reinstall_always = FALSE,
  min_version = "0.2.2",
  source = paste0("https://github.com/isoverse/isoorbi/releases/download/isoraw-v",
    min_version),
  accept_license = FALSE,
  ...
)

Arguments

Description

Default isoorbi plotting theme

Usage

orbi_default_theme(text_size = 16, facet_text_size = 20)

Arguments

Value

ggplot theme object

Description

This function sets one isotopocule in the data frame as the base peak (ratio denominator) and calculates the instantaneous isotope ratios against it. Note that any unidentified or missing peaks in the dataset are filtered out prior to ratio calculations (i.e. what orbi_filter_isotopocules() does by default) to avoid ambiguity in the dataset. To do this explicitly (with information displayed about how many unidentified peaks were filtered out), call orbi_filter_isotopocules() manually before orbi_define_basepeak().

Usage

orbi_define_basepeak(dataset, basepeak_def)

Arguments

Value

same object as provided in dataset without the rows of the basepeak isotopocule and instead three new columns called basepeak, basepeak_ions, and ratio holding the basepeak information and the isotope ratios vs. the base peak

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <- orbi_read_isox(file = fpath) |>
  orbi_simplify_isox() |>
  orbi_define_basepeak(basepeak_def = "M0")

Description

Define a data block by either start and end time or start and end scan number. If you want to make segments in the blocks (optional), note that this function - manually defining blocks - removes all block segmentation. Make sure to call orbi_segment_blocks() only after finishing block definitions.

Usage

orbi_define_block_for_flow_injection(
  dataset,
  start_time.min = NULL,
  end_time.min = NULL,
  start_scan.no = NULL,
  end_scan.no = NULL,
  sample_name = NULL
)

Arguments

Value

A data frame (tibble) with block definition added. Any data that is not part of a block will be marked with the value of orbi_get_option("data_type_unused"). Any previously applied segmentation will be discarded (segment column set to NA) to avoid unintended side effects.

Description

This function sorts out (bins) data into indivual blocks of reference, sample, changeover time, and startup time.

Usage

orbi_define_blocks_for_dual_inlet(
  dataset,
  ref_block_time.min,
  change_over_time.min,
  sample_block_time.min = ref_block_time.min,
  startup_time.min = 0,
  ref_block_name = orbi_get_option("di_ref_name"),
  sample_block_name = orbi_get_option("di_sample_name")
)

Arguments

Value

A data frame (tibble) with block annotations in the form of the additional columns described below:

• data_group is an integer that numbers each data group (whether that's startup, a sample block, a segment, etc.) in each file sequentially to uniquely identify groups of data that belong together - this columns is NOT static (i.e. functions like orbi_adjust_block() and orbi_segment_blocks() will lead to renumbering) and should be used purely for grouping purposes in calculations and visualization

• block is an integer counting the data blocks in each file (0 is the startup block)

• sample_name is the name of the material being measured as defined by the ref_block_name and sample_block_name parameters

• segment is an integer defines segments within individual blocks - this will be NA until the optional orbi_segment_blocks() is called

• data_type is a text value describing the type of data in each data_group - for a list of the main categories, call orbi_get_options("data_type")

Description

This functions exports the dataset into an Excel file. If the dataset is aggregated data, use the include parameter to decide which part of the data to export.

Usage

orbi_export_data_to_excel(
  dataset,
  file,
  dbl_digits = 7,
  int_format = "0",
  dbl_format = sprintf(sprintf("%%.%sf", dbl_digits), 0),
  include = c("file_info", "summary"),
  show_progress = rlang::is_interactive()
)

Arguments

Value

returns dataset invisibly for use in pipes

Description

This is a basic filter function for file names, compounds and time ranges. For filtering isotopocules, this function calls orbi_filter_isotopocules() internally (as of isoorbi version 1.5.0 orbi_filter_isotopocules() can also be used directly instead of via this function). Default value for all parameters is NULL, i.e. no filter is applied.

Usage

orbi_filter_files(
  dataset,
  filenames = NULL,
  compounds = NULL,
  isotopocules = NULL,
  time_min = NULL,
  time_max = NULL
)

Arguments

Value

Filtered tibble

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <-
  orbi_read_isox(file = fpath) |>
  orbi_simplify_isox() |>
  orbi_filter_files(
    filenames = c("s3744"),
    compounds = "HSO4-",
    isotopocules = c("M0", "34S", "18O")
  )

Description

This function filters out data that have been previously flagged using functions orbi_flag_satellite_peaks(), orbi_flag_weak_isotopocules(), and/or orbi_flag_outliers(). Note that this function is no longer necessary to call explicitly as orbi_analyze_shot_noise() and orbi_summarize_results() automatically exclude flagged data.

Usage

orbi_filter_flagged_data(dataset)

Arguments

Value

a dataset with the flagged data filtered out

Description

This function helps filter out missing isotopcules, unidentified peaks, or select for specific isotopocule. It can be called any time after orbi_identify_isotopocules() or after reading from an isox file. By default (i.e. if run without setting any parameters), it removes unidentified peaks and missing isotopcules and keeps all others.

Usage

orbi_filter_isotopocules(
  dataset,
  isotopocules = c(),
  keep_missing = FALSE,
  keep_unidentified = FALSE
)

Arguments

Value

the dataset but filtered for these isotopocules

Description

orbi_filter_isox() was renamed orbi_filter_files() to incorporate its wider scope for filtering both isox and raw files data.

Usage

orbi_filter_isox(...)

Arguments

Description

Function replaced by orbi_flag_satellite_peaks()

Usage

orbi_filter_satellite_peaks(...)

Arguments

Description

Function replaced by orbi_flag_outliers()

Usage

orbi_filter_scan_intensity(..., outlier_percent)

Arguments

Description

Function replaced by orbi_flag_weak_isotopocules()

Usage

orbi_filter_weak_isotopocules(...)

Arguments

Description

Finds all .isox files in a folder.

Usage

orbi_find_isox(folder, recursive = TRUE)

Arguments

Examples

# all .isox files provided with the isoorbi package
orbi_find_isox(system.file("extdata", package = "isoorbi"))

Description

Finds all .raw files in a folder.

Usage

orbi_find_raw(folder, pattern = NULL, include_cache = TRUE, recursive = TRUE)

Arguments

Examples

# all .raw files provided with the isoorbi package
orbi_find_raw(system.file("extdata", package = "isoorbi"))

Description

This function flags outliers using one of the different methods provided by the parameters (to use multiple, please call this function several times sequentially). Note that this function evaluates outliers within each "uidx", "filename", and "injection" (for those of the columns that exist), and additionally within each "block" and "segment" if by_block = TRUE. in addition to any groupings already defined before calling this function using dplyr's group_by(). It restores the original groupings in the returned datasert.

Usage

orbi_flag_outliers(
  dataset,
  agc_fold_cutoff = NA_real_,
  agc_window = c(),
  agc_absolute_cutoff = c(),
  by_block = TRUE
)

Arguments

Value

same object as provided in dataset with new columns is_outlier and outlier_type (if they don't already exist) that flags outliers identified by the method and provides the type of outlier (e.g. "2 fold agc cutoff"), respectively.

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <-
  orbi_read_isox(file = fpath) |>
  orbi_simplify_isox() |>
  orbi_flag_outliers(agc_window = c(1,99))

Flag minor satellite peaks Flags minor signals for an isotopocule that matches multiple peaks within its exact mass +/- tolerance interval in the same scan. These are often small satellite peaks generated by the Fourier transform. However, if there are satelite peaks of high intensity or very many satellite peaks, it can indicate that the m/z and tolerance setting used for identifying isotopcules need to be revisited. Visualize the flagged satellite peaks with orbi_plot_satellite_peaks().

Description

Flag minor satellite peaks Flags minor signals for an isotopocule that matches multiple peaks within its exact mass +/- tolerance interval in the same scan. These are often small satellite peaks generated by the Fourier transform. However, if there are satelite peaks of high intensity or very many satellite peaks, it can indicate that the m/z and tolerance setting used for identifying isotopcules need to be revisited. Visualize the flagged satellite peaks with orbi_plot_satellite_peaks().

Usage

orbi_flag_satellite_peaks(dataset)

Arguments

Value

same object as provided in dataset with new column is_satellite_peak that flags satellite peaks

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <-
  orbi_read_isox(file = fpath) |>
  orbi_simplify_isox() |>
  orbi_flag_satellite_peaks()

Description

This function flags isotopocules that are not detected in a minimum of min_percent of scans that then can be easily visualized with orbi_plot_isotopocule_coverage(). It evaluates weak isotopocules within each "uidx", "filename", "block", "segment" and "injection" (for those of the columns that exist), in addition to any groupings already defined before calling this function using dplyr's group_by(). It restores the original groupings in the returned data.

Usage

orbi_flag_weak_isotopocules(dataset, min_percent = 100)

Arguments

Value

same object as provided in dataset with new column is_weak_isotopocule that flags weak isotopocules.

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <- orbi_read_isox(file = fpath) |>
      orbi_simplify_isox() |>
      orbi_flag_weak_isotopocules(min_percent = 100)

Description

This function provides an overview table blocks_info which shows information on blocks in the dataset (block number, sample name, data type, scan number and start time where a block starts, and scan number and end time where a block ends).

Usage

orbi_get_blocks_info(
  dataset,
  .by = c("uidx", "filename", "injection", "data_group", "block", "sample_name",
    "data_type", "segment")
)

Arguments

Value

a block summary or if no blocks defined yet, an empty tibble (with warning)

Description

Retrieve a specific subset of the aggregated data into a single data frame by specifying which columns to take from each dataset (file_info, scans, peaks, etc.) using dplyr::select() syntax. If data from more than one dataset is selected (e.g. some columns from scans AND some from peaks), the datasets are combined with an dplyr::inner_join() using the columns listed in by (only the ones actually in the datasets). Joins that would lead to duplicated data entries (i.e. many-to-many joins) are not allowed and will throw an error to avoid unexpected replications of individual datapoints. If you really want to do such a join, you'll have to do it manually.

Usage

orbi_get_data(
  aggregated_data,
  file_info = c("filename"),
  scans = NULL,
  peaks = NULL,
  spectra = NULL,
  problems = NULL,
  summary = NULL,
  by = c("uidx", "scan.no")
)

Arguments

Value

a tibble

Description

This function will provide the path(s) to example file(s). If a requested file is not yet available locally but is available on https://github.com/isoverse/isodata, it will download it from there into local storage. By default, it will download only cache files (.raw.cache.zip) instead of the original .raw files because the cache files are significantely smaller. Todownload the original raw files instead, use download_raw_files = TRUE.

Usage

orbi_get_example_files(
  filenames,
  download_raw_files = FALSE,
  download_always = FALSE
)

Arguments

Value

file path(s) that can be passed directly to orbi_read_raw()

Description

This function retrieves parsing problems encountered during the reading and processing of files.

This function prints out parsing problems encountered during the reading and processing of files.

Usage

orbi_get_problems(obj, strip_ansi = TRUE)

orbi_show_problems(obj)

Arguments

Value

tibble data frame with a list of problems encountered during processing

Description

orbi_get_settings() was renamed orbi_get_options() as part of isoorbi switching from 'settings' to 'options' to be consistent with base R naming conventions

Usage

orbi_get_settings(pattern = NULL)

Arguments

Description

Map the mass spectral peaks to specific isotopocules based on their mass.

Usage

orbi_identify_isotopocules(
  aggregated_data,
  isotopocules,
  default_tolerance = 1,
  default_charge = 1
)

Arguments

Value

same object as provided in aggregated_data with added columns compound (if provided), itc_uidx (introduced unique isotopocule index), isotopocule, mzExact, charge, and ions.incremental (via orbi_calculate_ions()), as as well as any other additional information columns provided in isotopocules. Note that if the default CN and RN values of orbi_calculate_ions() are not the ones that should be used, simply run orbi_calculate_ions() explicitly afterwards. Also note that the information about columns that were NOT aggregated in previous steps is purposefully not preserved at this step.

Description

These options are best set via orbi_options() and queried via orbi_get_option(). However, the base functions options() and getOption() work as well but require an isoorbi. prefix (the package name and a dot) for the option name. Setting an option to a value of NULL means that the default is used. orbi_get_options() is available as an additional convenience function to retrieve a subset of options with a regular expression pattern.

Usage

orbi_options(...)

orbi_get_options(pattern = NULL)

orbi_get_option(x)

Arguments

Functions

• orbi_options(): set/get option values

• orbi_get_options(): get a subset of option values that fit a pattern

• orbi_get_option(): retrieve the current value of one option (option must be defined for the package)

Options for the isoorbi package

• di_ref_name: the text label for dual inlet reference blocks

• di_sample_name: the text label for dual inlet sample blocks

• data_type_data: the text used to flag raw data as actually being data

• data_type_startup: the text used to flag raw data as being part of the startup

• data_type_changeover: the text used to flag raw data as being part of a changeover

• data_type_unused: the text used to flag raw data as being unused

• aggregators: data aggregators for pulling data out of raw files. The list of available aggregators is accessible via orbi_get_option("aggregators"). Individiual aggregators are available via the shortcut helper function orbi_get_aggregator("standard"). Register new/overwrite existing aggregators via orbi_register_aggregator().

• debug: turn on debug mode

• auto_use_ansi: whether to automatically enable correct rendering of stylized (ansi) output in HTML reports from notebooks that call library(isoorbi). Can be turned off by calling isoorbi::orbi_options(auto_use_ansi = FALSE) before call library(isoorbi).

Examples

# All default options
orbi_get_options()

# Options that contain 'data' in the name
orbi_get_options("data")

# Specific option
orbi_get_option("data_type_unused")

# Change an option
orbi_options(data_type_unused = "flagged")
orbi_get_option("data_type_unused")

# Change back to default
orbi_options(data_type_unused = NULL)
orbi_get_option("data_type_unused")

Description

The coverage of each isotopcule across scans/time is an important indicator for data completeness. These functions provide ways to summarize and visualize the isotopocule coverage in a dataset.

Usage

orbi_plot_isotopocule_coverage(
  dataset,
  isotopocules = c(),
  x = c("scan.no", "time.min"),
  x_breaks = scales::breaks_pretty(5),
  add_data_blocks = TRUE
)

orbi_get_isotopocule_coverage(dataset)

Arguments

Value

a ggplot object

summary data frame

Functions

• orbi_plot_isotopocule_coverage(): visualizes isotope coverage. Weak isotopocules (if previously defined by orbi_flag_weak_isotopocules()) are highlighted in red.

• orbi_get_isotopocule_coverage(): calculates which stretches of the data have data for which isotopocules. This function is usually used indicrectly by orbi_plot_isotopocule_coverage() but can be called directly to investigate isotopocule coverage.

Description

Call this function to visualize orbitrap data vs. time or scan number. The most common uses are orbi_plot_raw_data(y = intensity), orbi_plot_raw_data(y = ratio), and orbi_plot_raw_data(y = tic * it.ms). If the selected y is peak-specific data (rather than scan-specific data like tic * it.ms), the isotopocules argument can be used to narrow down which isotopocules will be plotted. By default includes all isotopcules that have not been previously identified by orbi_flag_weak_isotopcules() (if already called on dataset).

Usage

orbi_plot_raw_data(
  dataset,
  isotopocules = c(),
  x = c("time.min", "scan.no"),
  x_breaks = scales::breaks_pretty(5),
  y,
  y_scale = c("raw", "linear", "pseudo-log", "log"),
  y_scale_sci_labels = TRUE,
  color = .data$isotopocule,
  colors = c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02", "#A6761D",
    "#666666", "#BBBBBB"),
  color_scale = scale_color_manual(values = colors),
  add_data_blocks = TRUE,
  add_all_blocks = FALSE,
  show_outliers = TRUE
)

Arguments

Value

a ggplot object

Description

Call this function any time after flagging the satellite peaks to see where they are. Use the isotopocules argument to focus on the specific isotopocules of interest.

Usage

orbi_plot_satellite_peaks(
  dataset,
  isotopocules = c(),
  x = c("scan.no", "time.min"),
  y = c("ions.incremental", "intensity"),
  x_breaks = scales::breaks_pretty(5),
  y_scale = c("log", "pseudo-log", "linear", "raw"),
  y_scale_sci_labels = TRUE,
  colors = c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02", "#A6761D",
    "#666666", "#BBBBBB"),
  color_scale = scale_color_manual(values = colors)
)

Arguments

Value

a ggplot object

Description

This function creates a shot noise plot using a shotnoise data frame created by the orbi_analyze_shot_noise() function.

Usage

orbi_plot_shot_noise(
  shotnoise,
  x = c("time.min", "n_effective_ions"),
  permil_target = NA_real_,
  color = "ratio_label",
  colors = c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02", "#A6761D",
    "#666666")
)

Arguments

Details

plot shot noise

Value

a ggplot object

Description

This function visualizes mass spectra from aggregated raw file data. The spectra have to be be previously read in with include_spectra = c(1, 10, 100) in orbi_read_raw(). By default, this function tries to visualize different isotopcule ranges (monoisotopic peak, M+1, M+2, M+3). To focus only on isotopcules of interest, run orbi_identify_isotopocules() and orbi_filter_isotopocules() first.

Usage

orbi_plot_spectra(
  aggregated_data,
  mz_min = 0,
  mz_max = Inf,
  mz_base_peak = NULL,
  mz_focus_nominal_offsets = 0:4,
  max_scans = 6,
  max_files = 4,
  label_peaks = TRUE,
  show_filenames = TRUE,
  show_ref_and_lock_peaks = TRUE,
  show_focus_backgrounds = TRUE,
  background_colors = c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02",
    "#A6761D", "#666666", "#BBBBBB")
)

Arguments

Description

Read an IsoX dataput file (.isox) into a tibble data frame.

Usage

orbi_read_isox(file)

Arguments

Details

Additional information on the columns:

• filename: name of the original Thermo .raw file processed by IsoX

• scan.no: scan number

• time.min: acquisition or retention time in minutes

• compound: name of the compound (e.g., NO3-)

• isotopocule: name of the isotopocule (e.g., 15N); called isotopolog in .isox

• ions.incremental: estimated number of ions, in increments since it is a calculated number

• tic: total ion current (TIC) of the scan

• it.ms: scan injection time (IT) in millisecond (ms)

Value

A tibble containing at minimum the columns filename, scan.no, time.min, compound, isotopocule, ions.incremental, tic, it.ms

Examples

fpath <- system.file("extdata", "testfile_dual_inlet.isox", package = "isoorbi")
df <- orbi_read_isox(file = fpath)

Description

Read raw data files (.raw) from Orbitrap IRMS runs directly. This function extracts all available information and thus can be relatively slow (~1s / Mb on a typical personal computer) but with the caching this is only true the first time. The results can be used directly or, more typically, are aggregated with orbi_aggregate_raw() to safely extract the relevant information for downstream processing. This function is designed to be fail save by safely catching errors and reporting back on them (see orbi_get_problems()).

Usage

orbi_read_raw(
  file_paths,
  show_progress = rlang::is_interactive(),
  show_problems = TRUE,
  include_spectra = FALSE,
  read_cache = TRUE,
  cache = TRUE,
  cache_spectra = cache,
  keep_cached_spectra = cache
)

Arguments

Value

a tibble data frame where each row holds the file path and nested tibbles of datasets extracted from the raw file (typically file_info, scans, peaks, and spectra). This is the safest way to extract the data without needing to make assumptions about compatibility across files. Extract your data of interest from the tibble columns or use orbi_aggregate_raw() to extract safely across files.

Description

This step is optional and is intended to make it easy to explore the data within a sample or ref data block. Note that any raw data not identified with data_type set to "data" (orbi_get_option("data_type_data")) will stay unsegmented. This includes raw data flagged as "startup", "changeover", and "unused".

Usage

orbi_segment_blocks(
  dataset,
  into_segments = NULL,
  by_scans = NULL,
  by_time_interval = NULL
)

Arguments

Description

orbi_set_settings() was renamed orbi_options() as part of isoorbi switching from 'settings' to 'options' to be consistent with base R naming conventions

Usage

orbi_set_settings(...)

Arguments

Description

Keep only columns that are directly relevant for isotopocule ratio analysis. This function is optional and does not affect any downstream function calls.

Usage

orbi_simplify_isox(dataset, add = c())

Arguments

Value

A tibble containing only the 9 columns: filepath, filename, scan.no, time.min, compound, isotopocule, ions.incremental, tic, it.ms, plus any additional columns defined in the add argument

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package="isoorbi")
df <- orbi_read_isox(file = fpath) |> orbi_simplify_isox()

Description

These functions allow definition of custom data aggregators for processing data extracted from raw files. An aggregator is run on each imported file and pulls together the relevant data users are interested in while making sure data formats are correct so that the aggregated data can be merged across several imported files for fast downstream processing.

Usage

orbi_start_aggregator(name)

orbi_add_to_aggregator(
  aggregator,
  dataset,
  column,
  source = column,
  default = NA,
  cast = "as.character",
  regexp = FALSE,
  func = NULL,
  args = NULL
)

orbi_register_aggregator(aggregator, name = attr(aggregator, "name"))

orbi_get_aggregator(name)

Arguments

Value

an orbi aggregator tibble

Functions

• orbi_start_aggregator(): starts the aggregator

• orbi_add_to_aggregator(): add additional column to aggregate data for. Overwrites an existing aggregator entry for the same dataset and column if it already exists.

• orbi_register_aggregator(): register an aggregator in the isoorbi options so it can be retrieved with orbi_get_aggregator()

• orbi_get_aggregator(): retrieve a registered aggregator (get all aggregators with orbi_get_option("aggregators"))

Description

Contains the logic to generate the results table. It passes the ratio_method parameter to the orbi_calculate_summarized_ratio() function for ratio calculations.

Usage

orbi_summarize_results(
  dataset,
  ratio_method = c("mean", "sum", "median", "geometric_mean", "slope", "weighted_sum"),
  .by = c("block", "sample_name", "segment", "data_group", "data_type", "injection"),
  include_flagged_data = FALSE,
  include_unused_data = FALSE
)

Arguments

Value

Returns a results summary table (as tibble if dataset is a tibble, as dataset$tibble if dataset is aggregated raw data) with the columns filename, compound, isotopocule and basepeak as well as the grouping columns from the .by parameter that are part of the input dataset. Additionally this function adds the following results columns: start_scan.no, end_scan.no, start_time.min, mean_time.min, end_time.min, ratio, ratio_sem, ratio_relative_sem_permil, shot_noise_permil, No.of.Scans, minutes_to_1e6_ions

• ratio: The isotope ratio between the isotopocule and the basepeak, calculated using the ratio_method

• ratio_sem: Standard error of the mean for the ratio

• number_of_scans: Number of scans used for the final ratio calculation

• minutes_to_1e6_ions: Time in minutes it would take to observe 1 million ions of the isotopocule used as numerator of the ratio calculation.

• shot_noise_permil: Estimate of the shot noise (more correctly thermal noise) of the reported ratio in permil.

• ratio_relative_sem_permil: Relative standard error of the reported ratio in permil

Examples

fpath <- system.file("extdata", "testfile_flow.isox", package = "isoorbi")
df <- orbi_read_isox(file = fpath) |>
      orbi_simplify_isox() |>
      orbi_define_basepeak("M0")  |>
      orbi_summarize_results(ratio_method = "sum")