Package {ume}

Title:	Ultrahigh-Resolution Mass Spectrometry Data Evaluation for Complex Organic Matter
Version:	1.7.1
Description:	Provides tools for assigning molecular formulas from exact masses obtained by ultrahigh-resolution mass spectrometry. The methodology follows the workflow described in Leefmann et al. (2019) <doi:10.1002/rcm.8315>. The package supports the inspection, filtering and visualization of molecular formula data and includes utilities for calculating common molecular parameters (e.g., double bond equivalents, DBE). A graphical user interface is available via the 'shiny'-based 'ume' application.
URL:	https://gitlab.awi.de/bkoch/ume, https://github.com/boriskoch/ume, https://doi.org/10.5281/zenodo.20108477, https://www.awi.de/en/ume
Depends:	R (≥ 4.2.0)
Imports:	data.table, ggplot2 (≥ 3.5.0), plotly, vegan, viridis, jsonlite
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
LazyDataCompression:	xz
Suggests:	rmarkdown, knitr, testthat (≥ 3.0.0), xml2, pdftools, KEGGREST, zCompositions
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
RoxygenNote:	8.0.0
NeedsCompilation:	no
Packaged:	2026-07-14 05:07:36 UTC; bkoch
Author:	Boris Koch [aut, cre], Stephan Frickenhaus [ctb], Shuxian Gao [ctb], Oliver Lechtenfeld [ctb], Tim Leefmann [ctb], Fabian Moye [ctb]
Maintainer:	Boris Koch <boris.koch@awi.de>
Repository:	CRAN
Date/Publication:	2026-07-14 05:40:02 UTC

Convert numeric m/z vector into minimal peaklist

Description

Converts a simple numeric vector containing m/z values into a minimal UME peaklist. This is useful when users want to perform direct formula assignment on a single spectrum represented only by m/z values.

The generated peaklist contains:

• mz (copied from input)

• i_magnitude (set to 1 for all peaks)

• file_id = 1L

A "col_history" attribute is added to track that the object was constructed from a numeric vector.

Usage

.as_peaklist_from_numeric(x)

Arguments

Value

A minimal peaklist as a data.table.

See Also

Other peaklist helpers: .filter_peaklist_basic(), .load_peaklist_file()

Extract UME library version from formula library object

Description

Extract UME library version from formula library object

Usage

.extract_library_version(lib)

Arguments

Value

Numeric library version.

Internal helper: pretty label lookup

Description

Internal utility function to translate a UME variable name or synonym into a human-readable label using ume::ume_name_dictionary.

The function supports:

• canonical UME variable names,

• external software synonyms,

• and plotting aliases.

Matching is performed using exact matching on the label column of ume_name_dictionary.

If no match is found, the original colname is returned unchanged.

This helper is mainly used internally for:

• automatic axis labels,

• legend labels,

• plot annotations,

• and report generation.

Usage

.f_label(colname, lookup = ume::ume_name_dictionary)

Arguments

Details

Lookup Pretty Labels for UME Variables (Internal)

Value

Character string containing either:

• the matched human-readable label, or

• the original colname if no match exists.

Apply basic filters to peaklist

Description

Removes entries that are clearly invalid for formula assignment:

• mz is missing (NA) or negative

• i_magnitude is missing (NA)

These checks ensure that downstream validation and formula assignment receive only physically meaningful peaks.

Usage

.filter_peaklist_basic(pl)

Arguments

Value

A filtered data.table with invalid rows removed.

See Also

Other peaklist helpers: .as_peaklist_from_numeric(), .load_peaklist_file()

Load a peaklist from file

Description

Internal helper for as_peaklist() that reads a peaklist from a file. Supports common tabular formats, including:

• CSV (.csv)

• TSV (.tsv, .txt)

• RDS (.rds)

Column names are not altered here; normalization happens later in as_peaklist() via .normalize_column_aliases().

Usage

.load_peaklist_file(path)

Arguments

Value

A data.table containing the raw peaklist data.

See Also

Other peaklist helpers: .as_peaklist_from_numeric(), .filter_peaklist_basic()

Conditional message output for verbose functions

Description

Helper function for internal use to print formatted messages when verbose = TRUE. It uses sprintf() for clean formatting.

Usage

.msg(...)

Arguments

Details

This function standardizes how verbose messages are displayed across package functions. It automatically checks if a variable verbose exists in the calling environment and is TRUE.

Use it inside functions like this:

n <- 5
verbose <- TRUE
.msg("Processing %d samples...", n)

If verbose is not defined or FALSE, no output is shown.

CENTRAL PALETTE REGISTRY

Description

defines all palettes in ONE place.

Usage

.palette_builders

Ensure required peaklist columns are present

Description

Internal helper for as_peaklist() that ensures essential structural columns required for UME processing are present. Specifically:

• If file_id is missing but a character column such as file or link_rawdata exists, file_id is generated as a unique integer per distinct value in that column.

• If no such identifier exists, file_id := 1L is assigned.

• Adds peak_id if missing (using .I)

• Converts file_id to integer type

Usage

.prepare_peaklist_columns(pl)

Arguments

Value

A data.table with guaranteed core columns.

Data table schemas used in ume

Description

Internal definitions of expected column structures for key ume table types.

Usage

.ume_schema_peaklist

Internal helper to check required columns in molecular formula data

Description

Internal helper to check required columns in molecular formula data

Usage

.uplots_require_columns(mfd, required, fun_name = "")

Arguments

Value

Invisibly returns TRUE if all columns exist; otherwise stops.

Add metainformation derived from ume::known_mf

Description

Annotate molecular formulas using metadata from ume::known_mf.

The function joins molecular formulas with predefined molecular formula categories such as:

• CRAM

• marine_dom

• surfactant

• peptide

• nucleotide

Categories are controlled through ume::ume_name_dictionary using entries with:

semantic_type == "formula_category"

This allows centralized management of active categories and labels.

The function works with:

• character vectors of molecular formulas,

• data.frames,

• and data.tables.

Usage

add_known_mf(
  mfd,
  mf_col = "mf",
  known_mf = ume::known_mf,
  category_dictionary = ume::ume_name_dictionary,
  wide = FALSE,
  ...
)

Arguments

Details

Add metainformation derived from ume::known_mf

Molecular formulas are matched against known_mf.

If wide = FALSE (default), matching categories are returned as a comma-separated character column named categories.

If wide = TRUE, one numeric column per category is returned (CRAM, surfactant, ...).

Category selection is dynamically controlled through ume::ume_name_dictionary, allowing centralized management of known molecular formula categories.

Value

A data.table containing the original input plus additional molecular formula category information.

Author(s)

Boris P. Koch

References

CRAM

Hertkorn N., Benner R., Frommberger M., Schmitt-Kopplin P., Witt M., Kaiser K., Kettrup A., Hedges J.I. (2006). Characterization of a major refractory component of marine dissolved organic matter. Geochimica et Cosmochimica Acta, 70, 2990-3010. doi:10.1016/j.gca.2006.03.021

Surfactants

Lechtenfeld O.J., Koch B.P., Gasparovic B., Frka S., Witt M., Kattner G. (2013). The influence of salinity on the molecular and optical properties of surface microlayers in a karstic estuary. Marine Chemistry, 150, 25-38. doi:10.1016/j.marchem.2013.01.006

Ideg

Flerus R., Lechtenfeld O.J., Koch B.P., McCallister S.L., Schmitt-Kopplin P., Benner R., Kaiser K., Kattner G. (2012). A molecular perspective on the ageing of marine dissolved organic matter. Biogeosciences, 9, 1935-1955. doi:10.5194/bg-9-1935-2012

iTerr

Medeiros P.M., Seidel M., Niggemann J., Spencer R.G.M., Hernes P.J., Yager P.L., Miller W.L., Dittmar T., Hansell D.A. (2016). A novel molecular approach for tracing terrigenous dissolved organic matter into the deep ocean. Global Biogeochemical Cycles, 30, 689-699. doi:10.1002/2015gb005320

See Also

Other Formula assignment: calc_eval_params(), check_formula_library(), eval_isotopes(), ume_assign_formulas()

Examples

# Character vector input
add_known_mf(
  c("C10H12O5", "C20H30O10")
)

# Molecular formula table
add_known_mf(
  mfd = mf_data_demo
)

# Wide format
add_known_mf(
  mfd = mf_data_demo,
  wide = TRUE
)

Add Missing Isotope Columns to mfd

Description

This function ensures that missing isotope columns are added to the input data table (mfd), which is required for further data evaluation that considers isotope information. If any of the specified isotope columns are not already present in the data, they will be added with a default value of 0.

The function is typically used to standardize the dataset by ensuring that all expected isotopes (e.g., nitrogen-15, carbon-13) are represented, even if they are not initially present in the data. The function works by checking for the existence of each specified isotope column and adding the missing ones.

Usage

add_missing_element_columns(mfd, missing_cols = "15n")

Arguments

Value

A data.table object with the missing isotope columns added, where missing columns are populated with a default value of 0. The original mfd object is modified in place.

See Also

Other tools: order_columns()

Examples

# Add missing isotope columns to a demo dataset
mfd_with_isotopes <- add_missing_element_columns(mfd = mf_data_demo)

# Add a specific isotope column for Nitrogen-15 (if missing)
mfd_with_15n <- add_missing_element_columns(mfd = mf_data_demo, missing_cols = c("15n", "na"))

Coerce input to UME molecular formula data

Description

Flexible entry point for molecular formula data in UME.

as_mfd() normalizes column names using ume::ume_name_dictionary, adds missing structural columns where possible, optionally calculates Kendrick mass defect (kmd), validates required columns, and returns a standardized data.table.

Usage

as_mfd(
  mfd,
  required_cols = c("file_id", "mz", "mf", "m", "ppm"),
  target = "mfd",
  dictionary = ume::ume_name_dictionary,
  add_peak_id = TRUE,
  add_kmd = TRUE,
  kmd_digits = 3,
  kmd_base_mass = 14.01565,
  track_original_names = TRUE,
  ...
)

Arguments

Details

Coerce input to UME molecular formula data

Value

A standardized molecular formula data.table with attribute ume_type = "mfd".

See Also

Other check ume objects: as_peaklist(), check_formula_library(), check_mfd()

Check format of peaklist

Description

Flexible entry point for UME. Accepts:

• data.frame / data.table peaklists

• numeric m/z vectors

• file paths (csv, txt, tsv, rds)

Normalizes column names, adds missing structural columns (file_id, peak_id), removes invalid rows, validates schema, and assigns the UME peaklist class. Creates a standardized data.table ready for formula assignment.

Usage

as_peaklist(pl, verbose = FALSE, track_original_names = TRUE, ...)

Arguments

Value

A validated and normalized peaklist as a data.table with class "ume_peaklist".

See Also

Other check ume objects: as_mfd(), check_formula_library(), check_mfd()

Convert molecular formula data to a feature matrix

Description

Converts long molecular formula data into a wide sample-by-feature matrix for multivariate statistics.

Rows are defined by grp, columns by feature_col, and values by value_col. Duplicate group-feature combinations are aggregated.

Usage

as_ume_matrix(
  mfd,
  grp = "file_id",
  feature_col = "mf",
  value_col = "norm_int",
  fun.aggregate = mean,
  fill = 0,
  as_matrix = TRUE
)

Arguments

Value

A numeric matrix or data.frame with groups as rows and features as columns.

Examples

mat <- as_ume_matrix(
  mfd = mf_data_demo,
  grp = "file_id",
  value_col = "norm_int"
)

Molecular Formula Assignment

Description

Assigns molecular formulas to molecular masses using a predefined library. Input of the peaklist (pl) is internally checked as_peaklist(), converted to neutral masses calc_neutral_mass(), and assigned with molecular formulas based on the mass accuracy (ma_dev) provided calc_ma_abs(). The input can be either:

• A peaklist (data.table) containing m/z values or neutral masses and additional metadata .

• A numeric vector of m/z values or neutral masses without additional metadata (internally checked and standardized by as_peaklist()).

Usage

assign_formulas(pl, formula_library, verbose = FALSE, ...)

Arguments

Details

This function calculates the neutral mass of peaks in pl and compares it to mass values in formula_library, assigning molecular formulas based on mass accuracy thresholds. If 13C, 15N, or 34S isotope information is missing, additional columns are added to the output table.

Value

A data.table where each row represents a molecular formula assigned to a mass peak. The table contains:

• All columns of the input peaklist pl (e.g. mz, i_magnitude, file_id).

• All columns of the input formula_library (e.g. mf, element counts).

• Calculated columns:

  • m — neutral mass.

  • m_cal — exact mass of the assigned formula.

  • del — absolute mass error (Da).

  • ppm — mass error in parts per million.

  • mf_id — unique ID for each (file_id, mf) combination.

• Added isotope columns (⁠13C⁠, ⁠15N⁠, ⁠34S⁠) if missing in the library.

One peak may receive zero, one, or multiple assigned formulas depending on the mass accuracy threshold.

Author(s)

Boris P. Koch

Examples

# Example using demo data and demo peak list:



assign_formulas(pl = peaklist_demo,
                formula_library = ume::lib_demo,
                pol = "neg",
                ma_dev = 0.2,
                verbose = FALSE)

 # Example using a given mass and UME demo library:
 mfd <- assign_formulas(pl = 254.0426527, formula_library = ume::lib_demo,
 pol = "neutral", ma_dev = 0.5, verbose = TRUE)

Build Isotope Parent–Daughter Map from Molecular Formula Data

Description

Internal helper function that constructs an isotope substitution map for elements present in a molecular formula data table (mfd).

The function identifies all isotope columns (e.g. "12C", "13C", "14N") contained in mfd, determines which isotopes are actually present (atom count > 0 in at least one formula), and then retrieves the two most abundant stable isotopes per element from the global masses table.

For each detected element, the most abundant isotope is defined as the parent isotope, and the second most abundant isotope is defined as the daughter isotope. These pairs are later used to generate single isotope-substituted molecular formulas.

Usage

build_isotope_map(mfd)

Arguments

Details

Only elements that occur in mfd and are represented in masses$label are considered. If no isotope columns are detected or none contain non-zero counts, an empty data.table is returned.

The function assumes that a global object masses exists containing at least the columns:

• label – isotope label (e.g. "12C")

• symbol – element symbol (e.g. "C")

• mole_fraction – natural isotopic abundance

The resulting isotope map always contains at most two isotopes per element (parent and daughter), ranked by natural abundance.

Value

A data.table with one row per detected element and the columns:

element

Element symbol.

parent_label

Most abundant isotope label.

parent_mass

Mass number of the parent isotope.

parent_mf

Natural mole fraction of the parent isotope.

daughter_label

Second most abundant isotope label.

daughter_mass

Mass number of the daughter isotope.

daughter_mf

Natural mole fraction of the daughter isotope.

If no eligible elements are found, an empty data.table with the same column structure is returned.

Author(s)

Boris Koch

See Also

Other internal functions: create_custom_formula_library(), extract_aquisition_params(), extract_aquisition_params_from_folder(), read_xml_peaklist(), search_mf_targets(), validate_isotope_presence()

Create a Data Summary Table for Element Ratios and Parameters

Description

Generates a data summary table that provides intensity-weighted averages for element ratios, mass accuracy, and additional parameters. Results can be grouped based on the specified grouping columns.

Usage

calc_data_summary(mfd, grp = "file_id", ...)

Arguments

Details

This function computes a variety of weighted averages and summary statistics for mass spectrometry data using the provided peak list (mfd). Calculated values include weighted averages for elemental counts (e.g., Carbon, Hydrogen), elemental ratios (e.g., O/C, H/C), and additional parameters such as the base peak intensity and summed intensities. It also calculates the aromaticity index (wa(AI)) based on the elemental composition. If grouping columns are provided, the summary statistics are calculated for each group.

The function also joins additional indices (ideg, iterr) from related functions calc_ideg() and calc_iterr() to the final summary table.

Value

A data.table containing the summarized results, with columns including:

n(mf)

Number of molecular formulas per group.

accuracy (median)

Median accuracy in parts-per-million (ppm) for the identified peaks.

accuracy (3 sigma cut-off)

Maximum ppm accuracy within a three-sigma range.

wa(mz)

Weighted average m/z value.

wa(DBE)

Weighted average Double Bond Equivalent (DBE).

wa(element)

Weighted averages for elements (C, H, N, O, P, S) and ratios (O/C, H/C, N/C, S/C).

wa(NOSC)

Weighted average nominal oxidation state of carbon.

wa(delG0_Cox)

Weighted average Gibbs free energy (Cox) in kJ/mol.

wa(AI)

Weighted average aromaticity index.

wa(C/N) and wa(C/S)

Ratios derived from N/C and S/C.

ideg, ideg_n

Indices for degree of degradation, as calculated by calc_ideg().

iterr, iterr_n, iterr2, iterr2_n

Terrestrial indices derived from calc_iterr().

median(i_magnitude)

Median intensity value.

int(basepeak)

Intensity of the base peak.

int(summed)

Summed intensity of all peaks.

References

Koch B.P., Dittmar T. (2006). From mass to structure: an aromaticity index for high-resolution mass data of natural organic matter. Rapid Communications in Mass Spectrometry, 20, 926-932. doi:10.1002/rcm.2386

LaRowe D.E., Van Cappellen P. (2011). Degradation of natural organic matter: A thermodynamic analysis. Geochimica et Cosmochimica Acta, 75, 2030-2042. doi:10.1016/j.gca.2011.01.020

Medeiros P.M., Seidel M., Niggemann J., Spencer R.G.M., Hernes P.J., Yager P.L., Miller W.L., Dittmar T., Hansell D.A. (2016). A novel molecular approach for tracing terrigenous dissolved organic matter into the deep ocean. Global Biogeochemical Cycles, 30, 689-699. doi:10.1002/2015gb005320

See Also

Other calculations: calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Example using demo data, grouping by file ID
calc_data_summary(mfd = mf_data_demo, grp = c("file_id"))

Calculate Double Bond Equivalent (DBE)

Description

Calculates the Double Bond Equivalent (DBE) for a given neutral molecular formula. DBE is a measure of unsaturation, representing the total number of rings and pi bonds in a molecule. The function uses the ume::masses data table to determine valence information for each element in the input molecular formula. #' It can be calculated from the molecular formula using atomic valences:

\mathrm{DBE} = 1 + \frac{1}{2} \sum_i n_i (v_i - 2)

where:

• n_i: number of atoms of element i

• v_i: valence of element i (e.g., C = 4, H = 1, N = 3, O = 2, S = 2/4/6 depending on bonding state)

This formula works for any set of elements as long as their valence is known. Be aware that some elements can have more than one valence at normal conditions (e.g. Sulfur can have valences of 2, 4 and 6). The function uses the valence that is represented in ume:masses$valence.

For a reasonable neutral molecule DBE has an integer value >=0. A higher DBE indicates a more unsaturated structure; a lower DBE indicates a more saturated structure.

Usage

calc_dbe(mfd, masses = ume::masses, verbose = FALSE, ...)

Arguments

Details

This function computes DBE based on the molecular formula specified in mfd. mfd can be a data.table or a character string or character vector of molecular formula strings.

For each isotope in the formula, DBE is calculated as the sum of (valence - 2) multiplied by the count of that isotope, divided by 2, and then adding 1. Elements with a valence of 2 are excluded from the DBE calculation.

The function stops with an informative error if valence information is missing for any element or isotope present in mfd.

Value

A numeric vector of the same length as the number of rows in mfd, where each entry represents the calculated DBE for the corresponding molecular formula. The result vector is named 'dbe'.

See Also

Other calculations: calc_data_summary(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Example with user-defined data
calc_dbe("C6H10O6")
calc_dbe("C6H10Br2")
calc_dbe(c("C3[13C1]H10O4", "C6H10O6"))

# Example with demo data from UME package
calc_dbe(mfd = mf_data_demo)

Calculate UME Evaluation Parameters

Description

This function calculates and adds several evaluation parameters as additional columns to the mfd data table. These parameters are essential for evaluating the molecular structure and isotopic distribution, enabling further analysis. For a detailed description of the output table, see help(mf_data_demo).

Usage

calc_eval_params(mfd, verbose = FALSE, ...)

Arguments

Value

The original data.table mfd with additional evaluation columns:

nm

Nominal molecular mass: Calculated if not already present.

dbe

Double Bond Equivalent (measure of unsaturation).

kmd

Kendrick mass defect for CH4 versus O exchange.

O/C, H/C, N/C, S/C

Element ratios for a molecular formula.

nsp_type, snp_check

Types of combinations of N, S, and P atoms in a formula.

nosc

Weighted average nominal oxidation state of carbon.

delG0_Cox

Weighted average Gibbs free energy (Cox) in kJ/mol.

ai

Aromaticity index.

ppm_filt

A mass accuracy threshold calculated for each spectrum.

Author(s)

Boris P. Koch

References

Hughey C.A., Hendrickson C.L., Rodgers R.P., Marshall A.G., Qian K.N. (2001). Kendrick mass defect spectrum: A compact visual analysis for ultrahigh-resolution broadband mass spectra. Analytical Chemistry, 73, 4676-4681. doi:10.1021/ac010560w

Koch B.P., Dittmar T. (2006). From mass to structure: an aromaticity index for high-resolution mass data of natural organic matter. Rapid Communications in Mass Spectrometry, 20, 926-932. doi:10.1002/rcm.2386

LaRowe D.E., Van Cappellen P. (2011). Degradation of natural organic matter: A thermodynamic analysis. Geochimica et Cosmochimica Acta, 75, 2030-2042. doi:10.1016/j.gca.2011.01.020

See Also

Other Formula assignment: add_known_mf(), check_formula_library(), eval_isotopes(), ume_assign_formulas()

Other calculations: calc_data_summary(), calc_dbe(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Example usage with a demo molecular formula dataset
mfd_with_params <- calc_eval_params(mfd = mf_data_demo, verbose = TRUE)

Calculate Exact Monoisotopic Mass of a Molecule

Description

This function calculates the exact monoisotopic mass for each molecule in a given data table based on the specified isotope composition. Exact masses of elements and isotopes used in the calculation are retrieved from the ume::masses data, based on data from NIST (https://www.nist.gov/pml/atomic-weights-and-isotopic-compositions-relative-atomic-masses).

Usage

calc_exact_mass(mfd, ...)

Arguments

Value

A numeric vector of the calculated exact monoisotopic mass.

Author(s)

Boris P. Koch

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Example with demo data
calc_exact_mass(mfd = mf_data_demo)
# Custom example
calc_exact_mass(data.table::data.table(c = 3, h = 8, o = 1))

Calculate Degradation Index (Ideg)

Description

This function calculates the degradation index ('Ideg') following Flerus et al. (2012). High Ideg values indicate 'older' marine DOM (i.e., a higher contribution of peaks that correlate negatively with delta14C), while low values indicate 'younger' DOM (i.e., a higher contribution of peaks that correlate positively with delta14C)./

Ideg is computed as the ratio of summed magnitudes for five negative (NEG) molecular formulas to the total summed magnitudes of five positive (POS) and five negative (NEG) molecular formulas:

Ideg = \frac{\sum{NEG}}{\sum{NEG} + \sum{POS}}

The index ranges from 0 to 1 and is valid only if all required formulas (n = 10) are present. Ideg depends strongly on the type of sample preparation, ionization method, and instrument settings, and should only be interpreted for relative changes within the same dataset.

Usage

calc_ideg(
  mfd,
  mf_col = "mf",
  magnitude_col = "i_magnitude",
  grp = "file_id",
  ...
)

Arguments

Value

A data.table with columns:

• grp: Grouping variable.

• ideg: Calculated degradation index (rounded to 3 decimals).

• ideg_n: Number of assigned formulas used in the calculation.

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Create a minimal dataset containing all required POS and NEG formulas
library(data.table)

demo_ideg <- data.table(
  file_id = 1,
  mf = c(
    "C17H20O9", "C19H22O10", "C20H22O10", "C20H24O11", "C21H26O11",   # NEG
    "C13H18O7", "C14H20O7", "C15H22O7", "C15H22O8", "C16H24O8"        # POS
  ),
  i_magnitude = c(
    1200, 900, 1500, 700, 800,     # NEG intensities
    2000, 1800, 2200, 1600, 1900   # POS intensities
  )
)

calc_ideg(
  mfd = demo_ideg,
  mf_col = "mf",
  magnitude_col = "i_magnitude",
  grp = "file_id"
)

Calculate Isotope Pattern

Description

Calculates the theoretical isotope pattern of a molecular formula based on natural isotope abundances using multinomial/binomial isotope combinations.

Usage

calc_isotope_pattern(
  mf,
  masses = ume::masses,
  threshold = 1e-12,
  rel_threshold = 1e-06,
  max_peaks = 5000L,
  mass_digits = 6L
)

Arguments

Details

Calculate Theoretical Isotope Pattern

The function calculates all relevant isotope combinations for each element in a molecular formula and combines them into a theoretical isotope pattern.

For each isotope peak, the function returns the exact mass, nominal mass, absolute probability, relative abundance, elemental molecular formula (mf), and isotope-specific molecular formula (mf_iso).

The isotope-specific molecular formula uses bracket notation, for example ⁠[12C2][13C][1H6][16O]⁠.

Very small isotope peaks can be removed using threshold and rel_threshold to keep the output compact.

Value

A data.table with one row per isotope peak and the following columns:

mf

Elemental molecular formula.

mf_iso

Isotope-specific molecular formula.

mass

Exact mass of the isotope composition.

nominal_mass

Nominal mass of the isotope composition.

prob

Absolute probability of the isotope composition.

relative_abundance

Relative abundance normalized to the most abundant isotope peak.

isotope_peak

Peak number ordered by increasing mass.

Mathematical background

The theoretical isotope pattern is calculated from the natural isotope abundances of all elements present in a molecular formula.

For an element with n atoms and k naturally occurring isotopes, all possible isotope compositions are generated and their probabilities are calculated using the multinomial distribution:

P(x_1,\ldots,x_k)= \frac{n!}{x_1!x_2!\cdots x_k!} \prod_{i=1}^{k} p_i^{x_i}

where x_i is the number of atoms of isotope i, p_i is its natural abundance, and \sum x_i = n.

For elements with only two relevant isotopes (e.g. carbon, ^{12}C and ^{13}C), the multinomial distribution reduces to the binomial distribution:

P(m)= \binom{n}{m} p^m (1-p)^{n-m}

where m is the number of heavy isotopes.

In this special case, the relative isotope abundances follow the coefficients of Pascal's triangle. For example, the carbon isotope pattern of butane (C_4H_{10}) can be represented as:

(^{12}C + ^{13}C)^4 = 1 : 4 : 6 : 4 : 1

corresponding to the isotope peaks M, M+1, M+2, M+3 and M+4.

Exact masses are calculated from the isotope composition and isotope patterns of individual elements are subsequently combined by convolution, yielding the theoretical isotope pattern of the complete molecular formula.

The implementation therefore provides exact multinomial isotope distributions for all supported elements and molecular formulas.

References

Yergey JA, Heller DN, Hansen G, Cotter RJ, Fenselau C (1983). "Isotopic distributions in mass spectra of large molecules". Analytical Chemistry, 55(2), 353–356. doi:10.1021/ac00252a730

Valkenborg D, Mertens I, Lemiere F, Witters E, Burzykowski T (2012). "The isotopic distribution conundrum". Mass Spectrometry Reviews, 31(1), 96–109. doi:10.1002/mas.20339

See Also

Other isotopes: create_isotope_expanded_table(), eval_isotopes(), uplot_isotope_precision()

Examples

calc_isotope_pattern("C4H10")
calc_isotope_pattern("C2H6O")
calc_isotope_pattern("FeC10H10", rel_threshold = 1e-4)

Calculate terrestrial indeces Iterr and Iterr2 (after Medeiros et al. 2016)

Description

Calculate a degradation index 'Iterr' and modified index 'iterr2' after Medeiros et al. (2016). High Iterr values represent higher contribution of terrestrial material (i.e. higher contribution of peaks that correlate positively with delta13C) while low values represent less terrestrial material (i.e. higher contribution of peaks that correlate negatively with delta13C). Iterr / Iterr2 are calculated from a peak magnitude ratio of 50 or 5 POS and NEG formulas, respectively: sum(terr) / (sum(terr) + sum(marine)) Therefore Iterr / Iterr2 range between 1 and 0. It should be noted that absolute values strongly depend on factors such as type of solid phase extraction, ionization method, instrument settings etc. Therefore values can only be interpreted as relative changes. It should also be noted that for an appropriate evaluation ALL index formulas must be present.

Usage

calc_iterr(
  mfd,
  mf_col = "mf",
  magnitude_col = "i_magnitude",
  grp = "file_id",
  ...
)

Arguments

Value

Iterr and iterr2 values

References

Medeiros P.M., Seidel M., Niggemann J., Spencer R.G.M., Hernes P.J., Yager P.L., Miller W.L., Dittmar T., Hansell D.A. (2016). A novel molecular approach for tracing terrigenous dissolved organic matter into the deep ocean. Global Biogeochemical Cycles, 30, 689-699. doi:10.1002/2015gb005320

Examples

library(data.table)

# Create a minimal dataset containing all required
# POS, NEG, POS2, and NEG2 formulas for demonstration

demo_iterr <- data.table(
  file_id = 1,
  mf = c(
    # NEG (Iterr)
    'C13H12O5','C15H14O4','C14H12O5','C14H14O5','C13H12O6',
    'C16H16O4','C15H14O5','C14H12O6','C15H16O5','C14H14O6',
    'C16H14O5','C16H16O5','C15H14O6','C15H16O6','C14H14O7',
    'C17H16O5','C16H14O6','C17H18O5','C16H16O6','C15H14O7',
    'C17H16O6','C16H14O7','C18H18O6','C17H16O7','C17H18O7',
    'C18H16O7','C18H18O7','C17H16O8','C19H18O7','C20H20O7',
    'C19H18O8','C20H18O9','C19H16O10','C21H20O9','C20H18O10',
    'C22H22O9','C21H20O10','C23H22O10','C24H24O10','C25H26O10',

    # POS (Iterr)
    'C15H19NO6','C15H21NO6','C17H21NO7','C17H23NO7','C17H22O8',
    'C16H21NO8','C17H20N2O7','C17H19NO8','C18H23NO7','C17H21NO8',
    'C18H24O8','C16H19NO9','C17H23NO8','C17H22O9','C17H24O9',
    'C18H21NO8','C17H19NO9','C18H23NO8','C18H22O9','C17H21NO9',
    'C18H24O9','C18H20N2O8','C18H21NO9','C19H24O9','C18H23NO9',
    'C18H22O10','C18H24O10','C20H24O9','C19H22O10','C20H26O9',
    'C19H24O10','C19H26O10','C20H24O10','C20H26O10','C19H24O11',
    'C20H24O11','C20H26O11','C20H26O12','C22H28O11','C21H28O12',

    # NEG2 (Iterr2)
    'C17H18O7','C18H18O7','C17H16O7','C17H16O8','C15H16O6',

    # POS2 (Iterr2)
    'C20H24O9','C20H24O10','C19H22O10','C17H21NO8','C20H26O9'
  ),

  # Assign magnitude values (arbitrary but valid)
  i_magnitude = c(
    rep(1000, 40),  # NEG
    rep(2000, 40),  # POS
    rep(1500, 5),   # NEG2
    rep(1800, 5)    # POS2
  )
)

calc_iterr(
  mfd = demo_iterr,
  mf_col = "mf",
  magnitude_col = "i_magnitude",
  grp = "file_id"
)

calc_logratio

Description

Calculates log-ratio transformed values for compositional molecular formula data and returns either the original long table with added log-ratio columns or a complete group-feature table.

Usage

calc_logratio(
  mfd,
  grp = "file_id",
  feature_col = "mf",
  value_col = "i_magnitude",
  method = c("clr", "alr", "rclr"),
  zero = c("min", "median", "CZM", "GBM", "none"),
  zero_factor = 0.65,
  reference = NULL,
  reclose = TRUE,
  remove_empty = TRUE,
  z_warning = 1,
  fun.aggregate = mean,
  complete = FALSE
)

Arguments

Details

Calculate log-ratio values for molecular formula data

The input must be a molecular formula table in long format. Internally, the data are converted to a sample-by-feature matrix using as_ume_matrix(), zero-filled using zero_filling(), log-ratio transformed using vegan::decostand(), and then converted back to long format.

If complete = FALSE, the original mfd is returned with two additional columns: logratio_type and logratio_value.

If complete = TRUE, the returned table contains all group-feature combinations present in the transformed matrix. This is useful for PCA and clustering based on logratio_value.

Value

A data.table with the columns logratio_type and logratio_value. If complete = FALSE, all original mfd columns are retained. If complete = TRUE, the output contains grp, feature_col, logratio_type, and logratio_value.

Examples

mfd_lr <- calc_logratio(
  mfd = mf_data_demo,
  grp = "file_id",
  feature_col = "mf",
  value_col = "i_magnitude",
  method = "clr",
  zero = "min"
)

## Not run: 
mfd_lr_complete <- calc_logratio(
  mfd = mf_data_demo,
  grp = "file_id",
  feature_col = "mf",
  value_col = "i_magnitude",
  method = "clr",
  zero = "min",
  complete = TRUE
)

res_pca <- uplot_pca(
  mfd = mfd_lr_complete,
  grp = "file_id",
  int_col = "logratio_value"
)

## End(Not run)

Calculate mass accuracy

Description

Calculates relative mass accuracy (ma, in parts per million) as:

(m_{meas} - m_{calc}) / m_{calc} \times 10^6 where:

• m_{meas} = measured mass

• m_{calc} = calculated / theoretical (exact) mass

Returned value is rounded to 4 digits. In this context the theoretical mass is represented by the mass of the assigned molecular formula. A small absolute ppm value indicates a very precise measurement and increases confidence in correct molecular formula assignment.

Usage

calc_ma(m, m_cal, ...)

Arguments

Value

A numeric vector of mass accuracy (rounded to 4 decimals).

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Use of single values
calc_ma(m = 264.08641, m_cal = 264.08653)
# Use in a molecular formula table
calc_ma(m = mf_data_demo$m, m_cal = mf_data_demo$m_cal)
mf_data_demo[, .(m, m_cal, accuracy_in_ppm = calc_ma(m, m_cal))]

Calculate absolute mass accuracy range (ma)

Description

This function calculates the absolute mass accuracy range for a neutral mass (m) at a given a mass accuracy (ma_dev).

Usage

calc_ma_abs(m, ma_dev, ...)

Arguments

Value

Returns a list with two values: m_min, m_max

Examples

calc_ma_abs(m = 327.0134, ma_dev = 0.5)

Calculate neutral molecular mass

Description

Calculates neutral molecular masses for singly charged ions with full numerical precision. No user options are modified.

The conversion used is:

• negative mode: m = mz + 1.0072763

• positive mode: m = mz - 1.0072763

• neutral: m = mz

Usage

calc_neutral_mass(mz, pol = c("neg", "pos", "neutral"), ...)

Arguments

Value

Numeric vector of neutral masses.

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

calc_neutral_mass(199.32, pol = "neg")

Calculate Nominal Mass of a Molecule

Description

Computes the nominal mass (integer mass) for each molecular formula in the provided data. This function uses isotope masses stored in the dataset ume::masses, based on values from NIST, for accurate calculation of each element's nominal mass contribution.

Usage

calc_nm(mfd, ...)

Arguments

Details

The function calculates the nominal mass of each molecular formula by retrieving the relevant integer mass values of isotopes from ume::masses. This information is processed to create a calculation string which is then evaluated to obtain the nominal mass for each molecule.

The nominal mass is derived by summing the integer masses of each constituent element in the formula, where the integer mass for each element is multiplied by the number of atoms of that element in the molecule.

Note: This function depends on ume::get_isotope_info() for isotope data retrieval.

Value

A numeric vector of the calculated nominal mass.

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

# Example using a demo dataset to calculate nominal mass
calc_nm(mfd = mf_data_demo)

Calculate Normalized Peak Intensities

Description

Computes normalized peak intensities for a molecular formula dataset and adds the results as additional columns to the input data.table (mfd). It also calculates:

• the number of molecular formula assignments per peak (n_assignments)

• the total occurrences of each formula across the dataset (n_occurrence)

Normalized intensities are stored in a new column norm_int, and the reference intensity used for normalization is stored in int_ref.

Supported normalization methods:

• "none" – no normalization; raw peak intensities are copied to norm_int

• "bp" – normalized to the base peak intensity per spectrum

• "sum" – normalized by the total sum of intensities per spectrum

• "sum_ubiq" – normalized by the sum of intensities of ubiquitous peaks across the dataset

• "sum_rank" – normalized by the sum of the top n_rank most intense peaks per spectrum

• "euc" – Euclidean normalization (optional, not implemented in current version)

Usage

calc_norm_int(
  mfd,
  ms_id = "file_id",
  peak_id = "peak_id",
  peak_magnitude = "i_magnitude",
  normalization = c("bp", "sum", "sum_ubiq", "sum_rank", "none"),
  n_rank = 200,
  verbose = FALSE,
  ...
)

Arguments

Value

A data.table identical to mfd but with additional columns:

norm_int

Normalized peak intensity based on selected method.

int_ref

Reference intensity used for normalization (e.g., sum, base peak).

n_assignments

Number of formula assignments per peak (calculated internally).

n_occurrence

Number of occurrences of each formula across all spectra (calculated internally).

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_number_assignment(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

mfd_norm <- calc_norm_int(
  mfd = mf_data_demo,
  normalization = "sum_ubiq"
)

Calculate Number of Molecular Formula Assignments per Peak

Description

This function calculates the number of molecular formula (mf) assignments for each individual peak (peak_id) within a specified mass spectrum (ms_id). It counts the occurrences of molecular formulas assigned to each peak and returns a vector of counts corresponding to the number of assignments for each unique combination of mass spectrum ID, peak ID, and molecular formula.

Usage

calc_number_assignment(ms_id, peak_id, mf, ...)

Arguments

Value

A vector of integer counts representing the number of molecular formula assignments for each unique combination of mass spectrum ID, peak ID, and molecular formula.

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_occurrence(), calc_recalibrate_ms()

Examples

ms_ids <- c("file1", "file1", "file2", "file2", "file3")
peak_ids <- c(1, 2, 2, 3, 4)
mfs <- c("C10H10N2O8", "C10H12N2O8", "C10H10N2O8", "C10H11NOS4", "C10H24N4O2S")
n_assignments <- calc_number_assignment(ms_id = ms_ids, peak_id = peak_ids, mf = mfs)
print(n_assignments)

mf_data_demo[, calc_number_assignment(file_id, peak_id, mf)]

Calculate number of molecular formulas that were assigned to a molecular mass.

Description

Calculates the number of molecular formula (mf) assignments for each individual peak (peak_id) in a given mass spectrum (ms_id).

Usage

calc_number_occurrence(mfd, ...)

Arguments

Value

data.table; an additional column "n_occurrence" is added to the original table mfd

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_recalibrate_ms()

Calculate Pielou's Evenness

Description

This function calculates Pielou's evenness index, a measure of the distribution of abundances across molecular formulas. Evenness ranges from 0 (one molecular formula dominates) to 1 (all formulas are equally abundant).

Evenness is derived using the Shannon index:

E = \frac{H}{\log(S)}

where:

• H is the Shannon diversity index.

• S is the number of unique molecular formulas.

If there is only one molecular formula, evenness is defined as 1.

Usage

calc_pielou_evenness(mf, magnitude)

Arguments

Value

A single numeric value representing Pielou's evenness.

Examples

calc_pielou_evenness(
  mf = c("C10H20O5", "C12H18O3", "C18H30O6"),
  magnitude = c(1982375, 2424, 312410)
)

Recalibrate mass spectra

Description

This function performs an automated mass recalibration for peak lists using predefined or user-specified calibrant lists.

Calibration can be based on existing calibrant tables included in ume::known_mf (via the calibr_list argument) or on a user-provided set of molecular formulas (custom_calibr_list).

The function assigns calibrant peaks to each spectrum and evaluates their mass accuracy. Three independent outlier tests are applied to the assigned calibrants, and only those that pass all tests are used to calculate the recalibration model.

Recalibration is performed using a linear model (m ~ m_cal), and spectra with insufficient calibrant matches can be either excluded or corrected using extrapolated calibration parameters.

Usage

calc_recalibrate_ms(
  pl,
  col_spectrum_id = "file_id",
  calibr_list = c("cal_fa_neg", "cal_marine_dom_neg", "calibration", "marine_dom",
    "cal_marine_dom_pos", "cal_marine_pw_neg", "cal_SRFA_neg", "cal_SRFA_OL_neg",
    "E_coli_metabolome", "Post-column standard"),
  custom_calibr_list = NULL,
  min_no_calibrants = 1,
  outlier_removal = TRUE,
  insufficient_calibrants = c("extrapolate", "remove_spectrum"),
  verbose = FALSE,
  pol = c("neg", "pos", "neutral"),
  ma_dev,
  ...
)

Arguments

Details

Recalibration is based on a linear fit (lm(m ~ m_cal)), with slopes and intercepts computed individually for each spectrum. Optionally, spectra without sufficient calibrants can be corrected using median calibration parameters derived from other spectra.

Value

A list containing:

pl

Recalibrated peaklist.

check

Summary of the number of calibrants per spectrum.

cal_peaks

Assigned calibrant peaks and recalibration results.

cal_stats

Calibration statistics (slopes, intercepts, accuracy metrics).

⁠fig_*⁠

Interactive plotly figures comparing mass accuracy before and after recalibration.

Author(s)

Boris P. Koch

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence()

Calculate the Shannon Diversity Index

Description

The Shannon diversity index is calculated to quantify the diversity of molecular formulas based on their relative abundances. This index considers both the richness (number of unique formulas) and the evenness (distribution of abundances). Higher values indicate greater diversity.

The Shannon index is defined as:

H = -\sum (p_i \cdot \ln(p_i))

where:

• p_i is the relative abundance of the i-th molecular formula.

Zero-abundance formulas are excluded from the calculation.

Usage

calc_shannon_index(mf, magnitude)

Arguments

Value

A single numeric value representing the Shannon diversity index. Returns 0 if magnitude is all zeros.

Examples

calc_shannon_index(
  mf = c("C10H20O5", "C12H18O3", "C18H30O6"),
  magnitude = c(1982375, 2424, 312410)
)

Calculate the Simpson Diversity Index

Description

The Simpson diversity index is calculated to measure the probability that two randomly selected individuals (e.g., molecular formulas) belong to the same category. It quantifies the dominance or evenness within a dataset.

The Simpson index is defined as:

D = \sum (p_i^2)

where:

• p_i is the relative abundance of the i-th molecular formula.

The index ranges between 0 and 1:

• A value near 0 indicates high diversity (even distribution of abundances).

• A value of 1 indicates no diversity (one molecular formula dominates).

Usage

calc_simpson_index(mf, magnitude)

Arguments

Value

A single numeric value representing the Simpson diversity index. Returns 0 if magnitude is all zeros.

Examples

calc_simpson_index(
  mf = c("C10H20O5", "C12H18O3", "C18H30O6"),
  magnitude = c(1982375, 2424, 312410)
)

Create a time-flattened molecular formula data table

Description

Create a time-flattened molecular formula data table

Usage

create_time_flattened_mfd(
  mfd,
  ret_time_col = "ret_time_min",
  check_chromatographic = TRUE,
  group_cols = c("mf", "sample_id", "link_rawdata", "bl", "CRAM", "IOS", "amino_acids",
    "ideg_neg", "ideg_pos", "iterr2_neg", "iterr2_pos", "iterr_neg", "iterr_pos",
    "marine_dom", "nucleotide", "peptide", "surfactant", "vkey", "c", "h", "n", "o", "p",
    "s", "m_cal", "nm", "dbe", "oc", "hc", "nc", "sc", "dbe_o", "ai", "wf", "z", "nosc",
    "delg0_cox", "snp_check", "nsp_type", "co_tot", "nsp_tot"),
  sum_cols = c("i_magnitude"),
  mean_cols = c("mz", "res", "m", "ppm", "dev_n_c", "s_n", "kmd", "ppm_filt"),
  check_discrete = TRUE,
  max_unique_frac = 0.5
)

Arguments

Details

calc_time_flattened_mfd() collapses chromatographic molecular formula data across the retention time dimension. This creates a pseudo-direct-infusion-like molecular formula data table from LC-MS or other chromatographic MS data.

The function checks whether the input contains chromatographic data using ret_time_col, which defaults to "ret_time_min". If this column is missing or contains only one distinct non-missing value, the function stops unless check_chromatographic = FALSE.

Grouping columns should contain discrete values. Default grouping columns are only used if they are present in mfd. Numeric measurement columns are then aggregated within each group. By default, i_magnitude is summed, while mass accuracy and signal-related columns are averaged.

Value

A data.table with retention-time-flattened molecular formula data.

Check format of formula library

Description

Verify the correct usage of UME column names, existence of a unique peak identifier (peak_id), and a unique file/analysis name (file_id). Remove rows having missing values for either m/z (mz) or peak magnitude (i_magnitude).

Usage

check_formula_library(formula_library, ...)

Arguments

Value

data.table

Author(s)

Boris P. Koch

References

Leefmann, T., Frickenhaus, S., Koch, B.P., 2019. UltraMassExplorer: a browser-based application for the evaluation of high-resolution mass spectrometric data. Rapid Communications in Mass Spectrometry 33, 193-202.

See Also

Other Formula assignment: add_known_mf(), calc_eval_params(), eval_isotopes(), ume_assign_formulas()

Other check ume objects: as_mfd(), as_peaklist(), check_mfd()

Check format of molecular formula data

Description

Verify the correct usage of UME column names, existence of a unique peak identifier (peak_id), and a unique file/analysis name (file_id). Remove rows having missing values for either m/z (mz) or peak magnitude (i_magnitude).

Usage

check_mfd(mfd, ...)

Value

A data.table containing the validated and standardized molecular formula data. The function checks column names, ensures the presence of essential variables (file_id, mz, m, ppm), renames isotope columns when needed, and adds missing columns if necessary. The returned data.table is the input object mfd, potentially modified in place.

See Also

Other check ume objects: as_mfd(), as_peaklist(), check_formula_library()

Check neutral molecular formulas

Description

Checks whether character strings are valid neutral molecular formulas that can be parsed by convert_molecular_formula_to_data_table().

The function is intended as a lightweight pre-check before converting molecular formulas into element-count tables. It identifies common non-formula entries such as InChIKeys, charged formulas, empty values, unsupported isotope notation, and formulas containing unknown element or isotope labels.

Usage

check_neutral_mf(mf, masses = ume::masses)

Arguments

Details

Check molecular formulas for neutral formula validity

This function validates syntax only. It does not check chemical plausibility, valence rules, isotope natural abundance, charge balance, or whether the molecular formula corresponds to a real compound.

The parser uses the valid element symbols and isotope labels provided in masses. This avoids hard-coding element symbols and ensures that the validation is consistent with convert_molecular_formula_to_data_table().

Supported isotope notation follows the convention used in ume, for example:

• ⁠[13C]⁠ for one carbon-13 atom

• ⁠[13C2]⁠ for two carbon-13 atoms

• ⁠[18O2]⁠ for two oxygen-18 atoms

The alternative notation ⁠[13C]2⁠ is currently classified as unsupported because the isotope count is placed outside the brackets.

Charged formulas such as "C10H13N2+", "C11H18N2+2", or "C18H35CaO2Zn+3" are classified as charged and therefore not neutral.

InChIKeys such as "IOVCWXUNBOPUCH-UHFFFAOYSA-M" are detected separately and classified as non-formula identifiers.

Value

A data.table with one row per input entry and the following columns:

mf

Original input string.

is_empty

Logical; TRUE if the input is NA or empty.

is_inchikey

Logical; TRUE if the input resembles an InChIKey.

has_charge

Logical; TRUE if the formula ends with charge notation such as +, -, +2, -3, ⁠2+⁠, or ⁠3-⁠.

is_parseable

Logical; TRUE if the string can be fully tokenized using valid element and isotope labels from masses.

is_neutral_mf

Logical; TRUE if the input is non-empty, does not resemble an InChIKey, has no terminal charge notation, and can be fully parsed as a molecular formula.

issue

Character label describing the detected issue. Valid neutral formulas are labelled "valid_neutral_mf".

See Also

Other molecular formula functions: convert_data_table_to_molecular_formulas(), convert_molecular_formula_to_data_table()

Examples

mf <- c(
  "C6H6",
  "C6[13C2]HF15O2",
  "C6[13C]2HF15O2",
  "C4H5FeO4+",
  "C11H18N2+2",
  "IOVCWXUNBOPUCH-UHFFFAOYSA-M",
  NA_character_
)

check_neutral_mf(mf)

valid_mf <- check_neutral_mf(mf)[is_neutral_mf == TRUE, mf]

Check data.table structure

Description

Internal helper to verify if a table matches a defined ume schema.

Usage

check_table_schema(dt, schema, name = "table")

Arguments

Value

Logical TRUE/FALSE invisibly.

Classify FTMS files into categories based on filename patterns

Description

Classifies entries into categories (blank, standard, pool, sample, …) based on pattern rules applied to a specific search column. The identifiers returned in each category are also configurable.

Usage

classify_files(
  fi,
  search_col = "link_rawdata",
  id_col = "file_id",
  patterns = list(blank = c("blk", "blank", "mq"), standard = c("srfa", "standard"), pool
    = c("pool")),
  include_blank_check = TRUE,
  return = c("list", "table")
)

Arguments

Details

Default behavior:

• "blank": blank_check == "blank" or pattern "blk"

• "standard": pattern "srfa"

• "pool": pattern "pool"

• "sample": everything unmatched

Pattern matching is case-insensitive.

Value

Named list or a classified data.table.

Examples

# Minimal demo data
fi <- data.table::data.table(
  file_id       = 1:6,
  filename      = c("NS_blk_01.raw", "SRFA_20.raw", "Pool_A.raw",
                    "Sample_01.raw", "Sample_02.raw", "MQ_blank.raw"),
  blank_check   = c("blank", NA, NA, NA, NA, "blank"),  # optional column
  link_rawdata  = c("NS_blk_01.raw", "SRFA_20.raw", "Pool_A.raw",
                    "Sample_01.raw", "Sample_02.raw", "MQ_blank.raw")
)

# 1) Default behavior: return named list of file_ids by category
classify_files(fi)

# 2) Use a different column for pattern matching
classify_files(fi, search_col = "filename")

# 3) Return another ID field (here: file_id → stays the same for demo)
classify_files(fi, id_col = "file_id")

# 4) Return the full table with new category column
classify_files(fi, return = "table")

Create a Custom Interpolated Color Palette

Description

Constructs a continuous color palette from a sequence of base colors. Intermediate colors are interpolated between each pair of adjacent colors, optionally using a custom number of interpolation steps.

Usage

color.palette(steps, n.steps.between = NULL, ...)

Arguments

Details

This helper is primarily used for UME visualizations (e.g., color bars in density plots), but it can be used independently for any plotting task.

Value

A function of class "colorRampPalette" that generates interpolated color vectors when called with a single integer argument n.

For example, ⁠pal <- color.palette(c("blue", "white", "red")); pal(100)⁠ returns a vector of 100 smoothly interpolated colors.

Examples

# Generate a simple blue-white-red palette
pal <- color.palette(c("blue", "white", "red"))
pal(10)

# Add additional steps between colors
pal2 <- color.palette(c("blue", "white", "red"), n.steps.between = c(5, 10))
pal2(20)

Convert Data Table with Element Counts to Molecular Formulas

Description

Creates standardized molecular formula strings from isotope or element count columns and adds them to the input data.table.

Usage

convert_data_table_to_molecular_formulas(
  mfd,
  isotope_formulas = FALSE,
  keep_element_sums = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

The function extracts element or isotope counts from a table with one column per isotope or element. Valid isotope columns are detected using get_isotope_info() and the reference table ume::masses.

The standard molecular formula mf is created by summing isotopes belonging to the same element and arranging elements according to Hill order.

If isotope_formulas = TRUE, an additional mf_iso column is created that keeps isotope-specific information, for example ⁠[12C5][13C][1H12][16O6]⁠.

The function preserves the original row order and keeps duplicate rows.

Value

The original table mfd as a data.table with additional columns:

mf

Standardized molecular formula following Hill order.

mf_iso

If isotope_formulas = TRUE, isotope-specific molecular formula.

C_tot

If keep_element_sums = TRUE, total count of all carbon isotopes. Equivalent ⁠*_tot⁠ columns are created for other elements.

Notes

• Isotopic columns such as ⁠13C⁠ are formatted as ⁠[13C]⁠ in mf_iso.

• The output follows Hill order: C, H, then all other elements alphabetically.

• Single-element counts, e.g. C1H4, are formatted without explicit 1.

References

Hill E.A. (1900). On a system of indexing chemical literature; adopted by the classification division of the U. S. patent office. Journal of the American Chemical Society, 22, 478-494. doi:10.1021/ja02046a005

See Also

Other molecular formula functions: check_neutral_mf(), convert_molecular_formula_to_data_table()

Examples

convert_data_table_to_molecular_formulas(
  mf_data_demo[, .(`12C`, `1H`, `14N`, `16O`, `31P`, `32S`)]
)

Convert Molecular Formulas to a Data Table of Element Counts

Description

Parses molecular formulas and returns a data.table where each row represents one molecular formula and each element or isotope is represented by a separate count column.

Usage

convert_molecular_formula_to_data_table(
  mf,
  masses = ume::masses,
  table_format = c("wide", "long"),
  keep_mf_old = TRUE,
  isotope_default = c("most_abundant", "lightest"),
  check_neutral = FALSE
)

Arguments

Details

The function supports normal element notation such as C6H12O6 and bracketed isotope notation such as ⁠[13C]⁠, ⁠[13C2]⁠, and ⁠[18O2]⁠.

Input formulas are parsed using the element symbols and isotope labels provided in masses. This avoids hard-coded element lists and allows rare elements to be parsed as long as they are present in masses.

By default, input formulas are checked with check_neutral_mf() before parsing.

The standardized molecular formula mf is generated using dynamic Hill ordering:

• if carbon is present: C, then H, then all other elements alphabetically

• if carbon is absent: all elements alphabetically, including H

Value

A data.table in wide or long format.

See Also

Other molecular formula functions: check_neutral_mf(), convert_data_table_to_molecular_formulas()

Create a custom molecular formula library for UltraMassExplorer

Description

Builds a library based on a list of molecular formulas. The main stable isotope masses 13C1, 15N1, and 34S1 are automatically added.

Usage

create_custom_formula_library(mf)

Arguments

Value

A data.table representing a fully constructed UME molecular formula library. The returned table contains one row for each input molecular formula and additional rows for its isotopologues (⁠13C⁠, ⁠15N⁠, ⁠34S⁠) when applicable. Columns include:

• vkey – unique integer identifier for each formula/isotopologue.

• mf – reconstructed molecular formula string.

• mf_iso – isotopologue formula string.

• nm – nominal mass.

• mass – exact mass.

• Element count columns (e.g., ⁠12C⁠, ⁠13C⁠, ⁠1H⁠, ⁠14N⁠, ⁠15N⁠, ⁠32S⁠, ⁠34S⁠).

The library is sorted by exact mass and includes all input formulas plus any automatically constructed isotopologues.

Author(s)

Boris Koch

See Also

Other internal functions: build_isotope_map(), extract_aquisition_params(), extract_aquisition_params_from_folder(), read_xml_peaklist(), search_mf_targets(), validate_isotope_presence()

Create an Expanded Table of Parent and Isotope Daughter Formulas

Description

Creates a new molecular formula table containing the original parent formulas and their corresponding single-isotope daughter formulas.

Usage

create_isotope_expanded_table(
  mfd,
  id_col = "peak_id",
  allow_duplicates = TRUE,
  elements = NULL
)

Arguments

Details

The output includes annotation columns that facilitate isotope validation in downstream workflows:

• iso_role indicates whether a row represents a "parent" or "daughter" isotopologue.

• iso_element stores the element symbol for which the isotope substitution was generated (e.g. "C", "N", "S").

• iso_from and iso_to store the parent and daughter isotope labels (e.g. "12C" and "13C").

Value

A data.table containing parent and daughter formulas, including isotope annotation columns for downstream validation.

See Also

Other isotopes: calc_isotope_pattern(), eval_isotopes(), uplot_isotope_precision()

Create a molecular formula library for UME

Description

Generates all combinations of element / isotope counts between min_formula and max_formula, filtered by mass, DBE, element ratios, and heuristic rules (Kind & Fiehn 2007).

Usage

create_ume_formula_library(
  max_formula,
  min_formula = "C1H1",
  lib_version = 99,
  masses = ume::masses,
  max_mass = 152,
  ratio_filter = TRUE,
  heu_filter = TRUE,
  max_oc = 1.2,
  max_hc = 3.1,
  max_nc = 1.3,
  max_pc = 0.3,
  max_sc = 0.8,
  verbose = FALSE
)

Arguments

Value

A data.table containing the generated molecular formula library. The returned object has class "ume_library" and includes one row per molecular formula, with columns for:

• elemental and isotopic counts (e.g., ⁠12C⁠, ⁠13C⁠, ⁠1H⁠, ⁠16O⁠, ...)

• double bond equivalent (dbe)

• exact mass (mass)

• molecular formula string (mf)

• a unique versioned key (vkey)

Additional metadata is stored as attributes:

• "lib_version": numeric version identifier

• "min_formula": user-supplied minimum formula

• "max_formula": user-supplied maximum formula

• "max_mass": maximum allowed exact mass

• "filters": list describing applied ratio and heuristic filters

• "call": the matched function call

The object inherits from both "ume_library" and "data.table".

References

Kind T., Fiehn O. (2007). Seven Golden Rules for heuristic filtering of molecular formulas obtained by accurate mass spectrometry. BMC Bioinformatics, 8, 105. doi:10.1186/1471-2105-8-105

Hill E.A. (1900). On a system of indexing chemical literature; adopted by the classification division of the U. S. patent office. Journal of the American Chemical Society, 22, 478-494. doi:10.1021/ja02046a005

Download and Load a UME Formula Library

Description

Downloads and loads a UME formula library from Zenodo.

The function is designed to be CRAN-compliant:

• It does not write to the user's file system unless dest is explicitly provided.

• If dest is provided and the file already exists, it is loaded directly and not downloaded again.

• If dest = NULL, the library is downloaded to a temporary file and loaded into memory only.

• Downloads are only performed in interactive sessions.

• Existing local files can also be loaded in non-interactive sessions.

Usage

download_library(
  library = "lib_05.rds",
  doi = "10.5281/zenodo.17606457",
  dest = NULL,
  overwrite = FALSE,
  check_hash = TRUE,
  stop_on_hash_mismatch = FALSE
)

Arguments

Value

A data.table containing the formula library, or invisible NULL if no download is performed.

Evaluate isotope information

Description

Add isotope information to the parent mass and optionally remove isotopoloques from mfd table. Required for further data evaluation that considers isotope information.

Usage

eval_isotopes(mfd, remove_isotopes = TRUE, verbose = FALSE, ...)

Arguments

Value

A data.table with additional columns such as "int_13c" containing stable isotope abundance information.

Author(s)

Boris P. Koch

See Also

Other Formula assignment: add_known_mf(), calc_eval_params(), check_formula_library(), ume_assign_formulas()

Other isotopes: calc_isotope_pattern(), create_isotope_expanded_table(), uplot_isotope_precision()

Examples

eval_isotopes(mfd = mf_data_demo)

Export UME Analysis Results

Description

Exports UME analysis results to a structured output folder. The function writes the following objects to CSV (if provided):

• pl – peaklist

• mfd – full molecular formula dataset

• mfd_filt – filtered MFD

• mfd_filt_tf – transformed filtered MFD

• mfd_filt_tf_pivot – pivoted intensity matrix

• ds_tf – transformed diagnostics / statistics

Optionally, the function can export plot objects, create a ZIP archive of all exported files, and write a metadata file (metadata.R) containing a reproducibility snapshot that can be used later in load_ume_results().

Usage

export_ume_results(
  pl,
  mfd,
  mfd_filt,
  mfd_filt_tf,
  mfd_filt_tf_pivot,
  ds_tf,
  outdir = NULL,
  prefix = "ume",
  figures = FALSE,
  fig_width = 8,
  fig_height = 6,
  fig_device = c("png", "pdf"),
  zip = TRUE,
  metadata = list(),
  env = parent.frame()
)

Arguments

Details

Export UME Analysis Results

Value

Invisibly returns:

• the path to the ZIP file (if zip = TRUE), or

• the path to the output directory (if zip = FALSE).

Extract Acquisition Parameters from a Bruker PDF Report

Description

This function reads a PDF file from Bruker Compass DataAnalysis reports, extracts acquisition parameters, including the spectrum filename and analysis method, and returns them as a data.table. Parameter values are separated into numeric values and corresponding units.

Usage

extract_aquisition_params(pdf_path)

Arguments

Value

A data.table with columns: Parameter, Value, Unit, Spectrum_Filename, Analysis_Method.

See Also

Other internal functions: build_isotope_map(), create_custom_formula_library(), extract_aquisition_params_from_folder(), read_xml_peaklist(), search_mf_targets(), validate_isotope_presence()

Extract Acquisition Parameters from All PDF Files in a Folder

Description

This function processes all PDF files in a specified folder, extracting acquisition parameters from each Bruker PDF report and returns them as a combined data.table.

Usage

extract_aquisition_params_from_folder(folder_path = NULL)

Arguments

Value

A data.table containing the acquisition parameters for all PDF files.

See Also

Other internal functions: build_isotope_map(), create_custom_formula_library(), extract_aquisition_params(), read_xml_peaklist(), search_mf_targets(), validate_isotope_presence()

Create Customized Color Scales

Description

Creates color scales for numeric values using predefined color palettes. The function supports optional log-transformation of the input values, handles constant vectors gracefully, and maps each numeric value to a color in the selected palette.

Usage

f_colorz(
  z,
  tf = FALSE,
  palname = "viridis",
  col_num = 100,
  verbose = FALSE,
  ...
)

Arguments

Value

A character vector of colors of the same length as z.

Retrieve a Palette and a Representative Default Color

Description

Helper function returning a small palette preview (40 colors) plus a representative "selected color" for legends and UI elements.

Usage

f_colpal_selection(palname = "awi")

Arguments

Value

A list with:

• cpal — vector of 40 palette colors

• paltype — type of palette ("limited" or "square")

• colsel — representative color (middle of the palette)

Filter by (relative) peak magnitude

Description

This function filters molecular formulas by (relative) peak abundances.

Usage

filter_int(mfd, norm_int_min = NULL, norm_int_max = NULL, verbose = FALSE, ...)

Arguments

Value

data.table; subset of original molecular formula table

See Also

Other Formula subsetting: filter_mass_accuracy(), filter_mf_data(), remove_blanks(), subset_known_mf(), ume_assign_formulas(), ume_filter_formulas()

Examples

filter_int(mfd = calc_norm_int(mfd = mf_data_demo,
normalization = "sum_rank", n_rank = 100), norm_int_min = 1)

Automated filter for mass accuracy

Description

This function automatically sets a filter for mass accuracy for each individual spectrum.

Usage

filter_mass_accuracy(
  mfd,
  ma_col = "ppm",
  file_col = "file_id",
  msg = FALSE,
  ...
)

Arguments

Value

data.table; subset of original molecular formula table

See Also

Other Formula subsetting: filter_int(), filter_mf_data(), remove_blanks(), subset_known_mf(), ume_assign_formulas(), ume_filter_formulas()

Filter molecular formula data by mass spectrometric metadata

Description

This function filters molecular formulas by isotope numbers, element ratios, etc.

Usage

filter_mf_data(
  mfd,
  c_iso_check = FALSE,
  n_iso_check = FALSE,
  s_iso_check = FALSE,
  ma_dev = 3,
  dbe_max = 999,
  dbe_o_min = -999,
  dbe_o_max = 999,
  mz_min = 1,
  mz_max = 9999,
  n_min = 0,
  n_max = 999,
  s_min = 0,
  s_max = 999,
  p_min = 0,
  p_max = 999,
  oc_min = 0,
  oc_max = 999,
  hc_min = 0,
  hc_max = 999,
  nc_min = 0,
  nc_max = 99,
  verbose = FALSE,
  ...
)

Arguments

Value

data.table; subset of original molecular formula table

Author(s)

Boris P. Koch

See Also

Other Formula subsetting: filter_int(), filter_mass_accuracy(), remove_blanks(), subset_known_mf(), ume_assign_formulas(), ume_filter_formulas()

Examples

filter_mf_data(mfd = mf_data_demo, dbe_o_max = 10)

Filter multiple molecular formula assignments by mass-error medians

Description

Filters multiple molecular formula assignments for the same mass peak using subgroup-specific mass-error distributions.

The function is intended for UME molecular formula data (mfd) and applies the false-positive filtering concept of Gao et al. (2024). Multiple assignments are evaluated separately for each mass spectrum, defined by file_col. Within each spectrum, assignments belonging to the same peak are compared. The assignment whose subgroup median mass error in mDa is closest to zero is retained.

Usage

filter_multi_assignments(
  mfd,
  file_col = "file_id",
  peak_col = "peak_id",
  mf_col = "mf",
  formula_mass_col = "m",
  error_ppm_col = "ppm",
  kmd_col = "kmd",
  kmd_digits = 3,
  kmd_base_mass = 14.01565,
  group_cols = c("nsp_type", "kmd"),
  include_single_assignments = TRUE,
  median_type = 8,
  tie_method = c("first", "all"),
  return = c("filtered", "annotated")
)

Arguments

Details

The default UME column setup assumes:

• file_id: unique mass spectrum identifier

• peak_id: unique peak identifier within a spectrum

• mf: molecular formula

• m: theoretical formula mass

• ppm: relative mass error in ppm

• nsp_type: formula class/group

• kmd: Kendrick mass defect

Mass error in mDa is calculated as:

Merr_{mDa} = m \times ppm / 1000

Multiple assignments are identified by duplicated combinations of file_col and peak_col. Median mass errors are calculated by file_col and group_cols, by default file_id, nsp_type, and kmd.

Value

A data.table.

If return = "filtered", rejected multiple assignments are removed.

If return = "annotated", the returned table contains additional columns:

• ume_multi_assignment

• ume_merr_mda

• ume_median_merr_mda

• ume_abs_median_merr_mda

• ume_assignment_status

References

Gao, S. et al. (2024). Detection and Exclusion of False-Positive Molecular Formula Assignments via Mass Error Distributions in UHR Mass Spectra of Natural Organic Matter. Analytical Chemistry, 96, 10210-10218.

Examples

## Not run: 
mfd_filtered <- filter_multi_assignments(mfd)

mfd_check <- filter_multi_assignments(
  mfd,
  return = "annotated"
)

mfd_only_multi <- filter_multi_assignments(
  mfd,
  include_single_assignments = FALSE
)

## End(Not run)

Find KEGG pathways for molecular formulas

Description

Internal helper to search KEGG compounds by molecular formula and return linked KEGG pathways. The function uses KEGGREST only if it is installed, avoiding additional dependencies on UME.

Usage

find_kegg_pathways_by_formula(formulas, verbose = TRUE)

Arguments

Details

Each molecular formula may trigger multiple KEGG REST queries. For large formula lists the function can be slow and should therefore be used selectively.

Value

A data.table with one row per formula-compound-pathway relation and the columns:

formula

Input molecular formula.

compound_id

KEGG compound identifier, e.g. "cpd:C00031".

map_id

KEGG pathway/map identifier.

pathway_name

KEGG pathway name.

Returns an empty data.table if no matches are found.

Examples

## Not run: 
dt <- find_kegg_pathways_by_formula(
  formulas = c(
    "C6H12O6",
    "C5H11NO2",
    "C3H7NO2"
  )
)

head(dt)

## End(Not run)

Retrieve NIST element and isotope data

Description

Checks if element/isotope columns are present in mfd and lookup of NIST isotope information (based on masses). Can be applied to a formula library and any table having molecular formula data. If only an element name is identified, the symbol and data of the lightest isotope of the element will be returned. For example, the column name "C" will return "12C" isotope data.

Usage

get_isotope_info(mfd, masses = ume::masses, verbose = FALSE, ...)

Arguments

Value

A data.table containing information on all isotopes identified in mfd and a column "orig_name" having the original names of the isotope / element columns in mfd. Results are ordered according to Hill system.

References

Hill E.A. (1900). On a system of indexing chemical literature; adopted by the classification division of the U. S. patent office. Journal of the American Chemical Society, 22, 478-494. doi:10.1021/ja02046a005

Examples

get_isotope_info(mfd = mf_data_demo, verbose = TRUE)

Extract molecular formula from InChI string

Description

Extracts the molecular formula from an InChI string by parsing the first layer of the InChI representation. The function performs a fast string-based extraction without requiring external cheminformatics libraries.

Usage

inchi_to_mf(inchi)

Arguments

Details

Extract molecular formula from InChI

The function extracts the molecular formula from the first layer of the InChI string (i.e., the part immediately following "InChI=1S/" or "InChI=1/" and before the next / separator).

This approach is highly efficient because the molecular formula is explicitly encoded in the InChI and does not require interpretation of molecular structure, in contrast to SMILES-based approaches.

Leading and trailing whitespace is ignored. Non-character inputs result in an error.

Value

A character vector of molecular formulas in Hill notation, with the same length and order as inchi. Invalid or missing inputs return NA_character_.

See Also

https://www.inchi-trust.org/technical-faq/

Examples

inchi <- c(
  "InChI=1S/C2H6O/c1-2-3/h3H,2H2,1H3",
  "InChI=1S/H2O/h1H2",
  NA_character_
)

inchi_to_mf(inchi)
# [1] "C2H6O" "H2O"   NA

Check whether an object is a UME peaklist

Description

Check whether an object is a UME peaklist

Usage

is_ume_peaklist(x)

Arguments

Value

TRUE/FALSE

Collection of known formulas, for which additional information is available.

Description

Known formulas; contains formulas for which additional knowledge is available. This can be also calibration lists. Due to size reasons the table is restricted to what is covered by standard UME formula library (mz<=700, elements CHONSP considered). The original version is part of the UME database and transferred to UME using UTF-8 encoding. CRAM molecular formulas are taken from the supplementary material that is provided by Hertkorn et al. (2006).

Usage

known_mf

Format

A data.table with ~300,000 rows and 14 variables:

mf_kf_id

Unique identifier for formulas in known_mf

mf

molecular formula

category

Grouping of molecular formulas into topics

info1 - 4

Additional information on the formula

reference

Reference in which the formula was mentioned

mass

Exact neutral mass of the formula

last_update

Last update in the source database

Source

taken from www.awi.de

See Also

Other ume data: lib_demo, masses, mf_data_demo, peaklist_demo, ume_name_dictionary

Examples

data(known_mf)

Demo formula library (200 - 300 Da, neutral mass)

Description

Contains a small molecular formula library for demonstration and validation purposes. Complete formula libraries are available in the 'ume.formulas' data package.

Usage

lib_demo

Format

A data.table having ~115,111 rows and 12 variables:

vkey

First two digits represent the formula library version; last digits are unique identifiers for each formula

mf

Neutral molecular formula (no differentiation of isotopes)

mass

Calculated exact neutral mass of a formula (based on ume::masses)

See Also

Other ume data: known_mf, masses, mf_data_demo, peaklist_demo, ume_name_dictionary

Examples

data(peaklist_demo)

load_ume_results

Description

Loads a ZIP file or directory produced by export_ume_results() and reconstructs all exported data objects plus metadata.

Usage

load_ume_results(path, unzip_dir = tempfile("ume_load_"))

Arguments

Details

Load UME Exported Results

Value

A list with elements:

• peaklist

• mfd

• mfd_filt

• mfd_filt_tf

• mfd_filt_tf_pivot

• ds_tf

• metadata

Common parameters for ume package functions

Description

Central place to document arguments (e.g., msg, pl, formula_library) that are inherited by multiple functions via ⁠@inheritParams main_docu⁠. This is not a user-facing function and is only provided for documentation reuse.

Arguments

Details

Use ⁠@inheritParams main_docu⁠ in other functions to pull in these definitions. This topic is marked internal so it does not clutter the index.

License

This package is released under the MIT License. See the LICENSE file for details.

Masses: Elements and isotopes

Description

Contains masses, valences, isotopes and isotope ratios of elements based on data by NIST Physical Measurement Laboratory (https://www.nist.gov/pml).

Usage

masses

Format

A data.table having 288 rows and 23 variables:

label

Element symbol including nominal isotopic mass

symbol

Element symbol in upper case

nm

Nominal mass of the isotope

exact_mass

Exact mass of the isotope

mole_fraction

Mole fraction compared to all isotopes of an element

relative_abundance

Relative abundance compared to the main (most abundant) isotope

valence

Valence at standard conditions

valence2

Alternative valence at standard conditions

hill_order

Rank in Hill Order for molecular formulas (cf. https://en.wikipedia.org/wiki/Chemical_formula)

Source

https://www.nist.gov/pml/atomic-weights-and-isotopic-compositions-relative-atomic-masses

References

Hill E.A. (1900). On a system of indexing chemical literature; adopted by the classification division of the U. S. patent office. Journal of the American Chemical Society, 22, 478-494. doi:10.1021/ja02046a005

See Also

Other ume data: known_mf, lib_demo, mf_data_demo, peaklist_demo, ume_name_dictionary

Examples

data(masses)

mf_data_demo

Description

Contains molecular formula data and metainformation on formulas. The metainformation

Usage

mf_data_demo

Format

A data.table with ~9245 rows (formulas) and 65 variables:

file_id

Unique ID (integer) for each analysis

file

A unique label for a mass spectrum or sample (character)

peak_id

Unique ID (integer) for each mass peak in the peak list 'pl'

mz

Mass to charge ratio of the singly charged molecular ion (numeric)

i_magnitude

Measured mass peak magnitude of the singly charged molecular ion (numeric)

norm_int

Normalized intensity as calculated by calc_norm_int()

m

Neutral measured mass of the molecular ion

m_cal

Neutral calculated mass of the assigned formula

ppm

Realtive mass accuracy of measured mass compared to m_cal (in ppm)

nm

Nominal mass of the neutral molecule

mf

molecular formula (no differentiation of isotopes)

dbe

Double bond equivalent

⁠12C⁠

Number of carbon atoms (12C)

⁠1H⁠

Number of hydrogen atoms

hc

hydrogen / carbon ratio in a molecular formula

oc

oxygen / carbon ratio in a molecular formula

nc

nitrogen / carbon ratio in a molecular formula

sc

sulfur / carbon ratio in a molecular formula

ai

Aromaticity index according to Koch and Dittmar (2008, 2016)

z

z score according to Stenson et al. (2003)

kmd

Kendrick mass defect (based on CH2-units) according to Kendrick (1963)

ppm_filt

Calculated threshold value for relative mass accuracy (in ppm) that can be used for formular filtering

mf_id

Identifier for each unique molecular formula identified in the unfiltered dataset

int13c

Measured relative peak magnitude of the 13C1 isotope compared to the parent ion (0 if isotope was not existing)

int15n

Measured relative peak magnitude of the 15N1 isotope compared to the parent ion (0 if isotope was not existing)

int34s

Measured relative peak magnitude of the 34S1 isotope compared to the parent ion (0 if isotope was not existing)

s_n

Signal to noise ratio of the molecular ion (numeric)

res

Mass resolution of the peak / ion (numeric)

del

Mass difference between the calculated and measured mass

dev_n_c

Deviation of the 12C/13C isotope ratio represented in carbon numbers according to Koch et al. (2007)

dbe_o

DBE minus O

nosc

Nominal oxidation state of carbon according to LaRowe & Van Cappellen (2011)

delg0_cox

Standard molal Gibbs energies of the oxidation half reactions of organic compounds according to LaRowe & Van Cappellen (2011)

relint13c_calc

Calculated relative intensity of the 13C1-isotope compared to the parent ion

int13c_calc

Calculated absolute intensity of the 13C1-isotope compared to the parent ion

relint34s_calc

Calculated relative intensity of the 34S1-isotope compared to the parent ion

int34s_calc

Calculated absolute intensity of the 34S1-isotope compared to the parent ion

snp_check

Checks if a formula contains S, N, or P

nsp_type

Lists the number of N, S, and P atoms in a formula

co_tot

Total number of carbon and oxygen atoms in a molecular formula

nsp_tot

Total number of nitrogen, sulfur, and phosphorus atoms in a molecular formula

n_occurrence_orig

Number of occurrences of a molecular formula in the entire unfiltered set of formulas

n_assignments_orig

Number of molecular formula assignments per molecular mass in the unfiltered set of formulas

int_bp

Peak magnitude (intensity) of the base peak in a spectrum

n_assignments

Number of molecular formula assignments per molecular mass after filter process

int_ref

Reference intensity that was used for calculating the normalized intensity (norm_int)

int_bp

Magnitude of the base peak in a mass spectrum

int_bp

Total magnitude of the reference that was used for normalization (cf. calc_norm_int())

Source

taken from www.awi.de

See Also

Other ume data: known_mf, lib_demo, masses, peaklist_demo, ume_name_dictionary

Examples

data(mf_data_demo)

Order columns

Description

Take most prominent columns required for data evaluation first - followed by all other columns.

Usage

order_columns(mfd, col_order = NULL, ...)

Arguments

Value

A data.table containing isotope data for those isotopes present in mfd.

See Also

Other tools: add_missing_element_columns()

Examples

order_columns(mfd = mf_data_demo)

Demo peak list

Description

Contains parts of the peaklist (200 - 300 m/z) from mass spectra to use as demonstration and validation dataset. The sample mass spectra contain one blank, three replicates of North Sea water, and three Arctic fjord samples as triplicates.

Usage

peaklist_demo

Format

A data.table having 31,091 rows and 7 variables:

file_id

A unique identifier for a mass spectrum (integer)

file

A unique label for a mass spectrum or sample (character)

peak_id

A unique identifier for a peak in the entire peak list (integer)

mz

Mass to charge ratio of the singly charged molecular ion (numeric)

i_magnitude

Peak magnitude of the molecular ion (numeric)

s_n

Signal to noise ratio of the molecular ion (numeric)

res

Mass resolution of the peak / ion (numeric)

Source

taken from www.awi.de

See Also

Other ume data: known_mf, lib_demo, masses, mf_data_demo, ume_name_dictionary

Examples

data(peaklist_demo)

Read xml peaklists generates ultrahigh-resolution MS analyses

Description

This function reads multiple FTMS peaklist files in XML format. The function requires the package 'xml2'. that are generated from Bruker FTICRMS and Thermo Orbitrap instruments. A single peaklists containing the file_paths is returned as a data.table A dialog window requests the path to the required directory (recursive = FALSE by default).

Usage

read_xml_peaklist(folder_path = NULL, ...)

Arguments

Value

A data.table containing the combined peaklists extracted from all XML files in the selected folder. Each row represents a single peak. The table includes:

• filename – name of the XML file from which the peak originates.

• mz – mass-to-charge ratio of the peak.

• sn – signal-to-noise ratio (if available in the XML).

• res – peak resolution (if available in the XML).

• i_magnitude – peak intensity.

Files that contain no peak entries return a row with filename only. If the package xml2 is not installed, the function returns NULL after printing an informative message.

See Also

Other internal functions: build_isotope_map(), create_custom_formula_library(), extract_aquisition_params(), extract_aquisition_params_from_folder(), search_mf_targets(), validate_isotope_presence()

Remove molecular formulas detected in blanks

Description

Remove all molecular formulas that were detected in one or more blank analyses (identified via blank_file_ids). Matching is always on mf. If a retention-time column is present (or provided using ret_time_col), removal is restricted to the corresponding LC segment.

Usage

remove_blanks(
  mfd,
  blank_file_ids = NULL,
  blank_prevalence = 0.5,
  ret_time_col = NULL,
  verbose = FALSE,
  ...
)

Arguments

Details

• Requires a unique integer file_id per analysis in mfd.

• Minimal required columns in mfd: mf, file_id.

• Optional column: a retention-time column (e.g. "ret_time_min").

• If a retention-time column is used, formulas present in blanks are only removed for rows whose mf and retention time match

• The input mfd is not modified by reference; a subset is returned.

Value

data.table; subset of the original molecular formula table (mfd) with blank formulas removed (globally or LC-segment-wise).

Backward compatibility

The argument LCMS is deprecated and no longer used. Retention-time-aware removal is now enabled automatically when a retention-time column is present or explicitly provided via ret_time_col.

Author(s)

Boris P. Koch

See Also

Other Formula subsetting: filter_int(), filter_mass_accuracy(), filter_mf_data(), subset_known_mf(), ume_assign_formulas(), ume_filter_formulas()

Examples

# Presence/absence removal, no retention time:
remove_blanks(mfd = mf_data_demo,
              remove_blank_list = "Blank",
              verbose = TRUE)

Remove empty columns

Description

Removes columns that contain only NA values from a data.table. Columns listed in excl_cols are retained even if they are empty.

Usage

remove_empty_columns(df, excl_cols = NULL, ...)

Arguments

Value

A data.table containing all original non-empty columns, plus any columns listed in excl_cols, regardless of whether they are empty. Columns that contain only NA values and are not explicitly preserved are removed from the output.

Examples

dt <- data.table::data.table(
  c = c(2, 2, 2),
  x = c(NA, NA, NA),
  y = c(NA, NA, NA)
)
remove_empty_columns(dt, excl_cols = "y")

Remove columns that contain ID's

Description

This functions removes columns ID columns ('_id') and hierarchical search columns ('_lft', '_rgt') from a table. Only exceptions are "sample_id" and "bottle_id that are always kept in the output table.

Usage

remove_id_columns(df, ...)

Arguments

See Also

Other Clean data output: remove_unknown_columns()

Remove columns that only have one specific value

Description

This function removes columns that exclusively contain the value defined in 'search_term' (such as " unknown" (default)).

Usage

remove_unknown_columns(df, excl_cols = NULL, search_term = " unknown", ...)

Arguments

See Also

Other Clean data output: remove_id_columns()

Revert data.table column names

Description

Restore the original column names recorded in col_history.

Usage

revert_column_names(dt)

Arguments

Value

data.table with original column names restored

Search database for target molecular formulas

Description

An internal function that searches the MarChem peaklist database for a table of target molecular formulas or isotopologues and returns the raw peak hits while preserving all columns of the input target table.

Usage

search_mf_targets(
  target_table,
  formula_col = "mf_iso",
  ppm_window = 0.5,
  adduct_mass = 1.0072763
)

Arguments

Value

A data.table containing raw peak hits from "tab_ume_peaklists" plus all columns from target_table.

See Also

Other internal functions: build_isotope_map(), create_custom_formula_library(), extract_aquisition_params(), extract_aquisition_params_from_folder(), read_xml_peaklist(), validate_isotope_presence()

Subsetting known molecular formula categories

Description

Subset all molecular formulas that are present in one or more categories of ume::known_mf. Based on presence / absence.

Usage

subset_known_mf(
  mfd,
  select_category = NULL,
  exclude_category = NULL,
  verbose = FALSE,
  ...
)

Arguments

Value

data.table; subset of original molecular formula data.table (mfd)

See Also

Other Formula subsetting: filter_int(), filter_mass_accuracy(), filter_mf_data(), remove_blanks(), ume_assign_formulas(), ume_filter_formulas()

Examples

subset_known_mf(category_list = c("marine_dom"), mfd = mf_data_demo, verbose = TRUE)

theme_uplots

Description

Applies a clean UME-style theme used across all uplot_* visualisations.

Usage

theme_uplots(base_size = 12, base_family = "")

Arguments

Details

Unified UME Theme for All uplot_* Functions

Value

A ggplot2 theme object.

Complete formula assignment (wrapper function)

Description

Assigns molecular formulas to neutral molecular masses and calculates all parameters required for data evaluation, such as a posteriori filtering of molecular formulas, plotting, and statistics. The function uses a pre-build molecular formula library.

Usage

ume_assign_formulas(pl, formula_library, verbose = FALSE, ...)

Arguments

Details

All function arguments: args(filter_mf_data) args(filter_int)

Value

A data.table having molecular formula assignments for each mass.

See Also

Other Formula assignment: add_known_mf(), calc_eval_params(), check_formula_library(), eval_isotopes()

Other Formula subsetting: filter_int(), filter_mass_accuracy(), filter_mf_data(), remove_blanks(), subset_known_mf(), ume_filter_formulas()

Other ume wrapper: ume_filter_formulas()

Examples

ume_assign_formulas(pl = peaklist_demo, formula_library = lib_demo, pol = "neg", ma_dev = 0.2)

Complete Formula subsetting / filtering (wrapper)

Description

A wrapper function to filter molecular formulas according to a evaluation parameters.

Usage

ume_filter_formulas(mfd, verbose = FALSE, ...)

Arguments

Value

A data.table having molecular formula assignments for each mass. ume_filter_formulas(mfd = mf_data_demo, dbe_o_max = 15, norm_int_min = 2)

See Also

Other Formula subsetting: filter_int(), filter_mass_accuracy(), filter_mf_data(), remove_blanks(), subset_known_mf(), ume_assign_formulas()

Other ume wrapper: ume_assign_formulas()

Internal raster of the UME logo

Description

This object contains the preloaded raster version of the UME logo, generated once during package development from inst/figures/ume_package_icon.png.

It is used internally by uplots_add_ume_logo() to avoid runtime dependencies on the png package and to ensure the logo can be added without file I/O.

Format

A 3D numeric array representing an RGBA raster image.

UME name dictionary

Description

A compact dictionary table used internally by UME for column-name normalization, mapping external software names to UME names, and assigning human-readable labels in tables, plots, and reports.

The object is generated from the MarChem database table tab_admin_name_dictionary.

Usage

ume_name_dictionary

Format

A data.table with the following columns:

source_system

Character. Source system of the name, e.g. "UME" or "lambda_miner".

source_name

Character. Original name as used in the source system.

label

Character. Canonical UME name.

synonym_name

Character. Alternative or external name mapped to label.

nice_label

Character. Human-readable label used for plotting, tables, and reports.

semantic_type

Character. Type of mapped concept, e.g. "col_name" or "formula_category".

target

Character. Intended target context, e.g. "ume_labels", "known_mf", or "mfd".

priority

Integer. Mapping priority used when multiple mappings are available.

unit

Character. Optional unit associated with the variable.

Details

UME name dictionary

For internal UME labels, source_name, synonym_name, and label are often identical. For external sources, synonym_name stores the external column name and label stores the corresponding UME name.

Examples include:

• peak_mz -> mz

• formula_error_relative -> ppm

• measurement_name -> file_id

Formula category labels such as CRAM, ideg_neg, or marine_dom are also stored in this object and can be used to create readable column names after reshaping operations.

See Also

as_peaklist()

Other ume data: known_mf, lib_demo, masses, mf_data_demo, peaklist_demo

uplot_cluster

Description

This function plots the results of a cluster analysis and a multi-dimensional scaling (MDS) plot based on molecular formula data.

Usage

uplot_cluster(
  mfd,
  grp = "file_id",
  int_col = "norm_int",
  dist_method = NULL,
  hclust_method = "average",
  scale_distance = FALSE,
  ...
)

Arguments

Details

Plot Cluster Analysis and Multi-Dimensional Scaling

The input data are first converted to a wide sample-by-feature matrix using as_ume_matrix(). A dissimilarity matrix is then calculated with vegan::vegdist(), followed by hierarchical clustering and non-metric MDS.

The default distance method is "euclidean", which is suitable for log-ratio transformed data such as logratio_value and also valid for normalized intensities. For non-negative intensity data such as norm_int, "bray" can be a useful alternative.

Value

A named list with two elements:

dendrogram

A recordedplot object containing the hierarchical clustering dendrogram.

mds

A plotly object representing the two-dimensional MDS scatter plot.

Note

For CLR/ALR-transformed log-ratio values, use dist_method = "euclidean". For non-negative normalized intensities, dist_method = "bray" is also commonly used.

See Also

Other uplots: uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

out <- uplot_cluster(
  mfd = mf_data_demo,
  grp = "file_id",
  int_col = "norm_int"
)

out$dendrogram
out$mds

## Not run: 
mfd_lr <- calc_logratio(
  mfd = mf_data_demo,
  method = "clr",
  zero = "min"
)

out_lr <- uplot_cluster(
  mfd = mfd_lr,
  grp = "file_id",
  int_col = "logratio_value",
  dist_method = "euclidean"
)

## End(Not run)

Carbon vs Mass (CvM) Diagram

Description

Generates a scatter plot of nominal molecular mass (nm) versus carbon count (⁠12C⁠), coloured by the median a supplied variable (z_var), following Reemtsma (2010).

Usage

uplot_cvm(
  mfd,
  z_var = "co_tot",
  fun = median,
  palname = "redblue",
  tf = FALSE,
  size_dots = 1.5,
  ...
)

Arguments

Details

Carbon vs Mass (CvM) Diagram

Value

A ggplot or plotly object.

References

Reemtsma, T. (2010). The carbon versus mass diagram to visualize and exploit FTICR-MS data of natural organic matter. Journal of Mass Spectrometry, 45(4), 382–390. doi:10.1002/jms.1722

See Also

Other uplots: uplot_cluster(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_cvm(mfd = mf_data_demo, z_var = "co_tot", ume_logo = FALSE)
uplot_cvm(mfd = mf_data_demo, z_var = "norm_int", palname = "viridis")

## Not run: 
uplot_cvm(mfd = mf_data_demo, z_var = "co_tot", interactive = TRUE)
uplot_cvm(mf_data_demo, base_size = 11, palname = "awi", tf = TRUE,
  title_show = FALSE, col_bar = FALSE)

## End(Not run)

Frequency Plot of DBE - O atoms

Description

Bar plot showing the frequency distribution of double bond equivalents (dbe) minus the number of oxygen atoms in a molecular formula (dbe_o). The unified UME plotting system is applied (theme, labels, logo, hover text, plotly).

The formula assignment strategy follows chemically motivated constraints and group-wise decision criteria based on DBE and oxygen content to distinguish reliable from equivocal molecular formulas.

Usage

uplot_dbe_minus_o_freq(mfd, ...)

Arguments

Details

Frequency Plot of DBE - O

Value

ggplot or plotly object

References

Herzsprung, P., Hertkorn, N., von Tümpling, W., Harir, M., Friese, K., & Schmitt-Kopplin, P. (2014). Understanding molecular formula assignment of Fourier transform ion cyclotron resonance mass spectrometry data of natural organic matter from a chemical point of view. Analytical and Bioanalytical Chemistry, 406(30), 7977–7987. doi:10.1007/s00216-014-8249-y

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_dbe_minus_o_freq(mf_data_demo)
uplot_dbe_minus_o_freq(mf_data_demo, interactive = TRUE, ume_logo = FALSE, title_show = FALSE)

Plot DBE vs Carbon Atoms

Description

Creates a scatter plot of DBE (double bond equivalents) vs. number of carbon atoms. Points are color-coded by a selected variable (z_var). The plot follows the same stylistic conventions as the other uplot_* functions, including the unified theme and optional UME caption.

This approach follows the DBE/C concept introduced for identifying aromatic sub-structures in a molecular formula.

Usage

uplot_dbe_vs_c(
  mfd,
  z_var = "norm_int",
  fun = median,
  palname = "redblue",
  tf = FALSE,
  size_dots = 1.5,
  ...
)

Arguments

Value

A ggplot2 object or a plotly object (if plotly = TRUE).

References

Hockaday, W. C., Grannas, A. M., Kim, S., & Hatcher, P. G. (2006). Direct molecular evidence for the degradation and mobility of black carbon in soils from ultrahigh-resolution mass spectral analysis of dissolved organic matter from a fire-impacted forest soil. Organic Geochemistry, 37(4), 501–510. doi:10.1016/j.orggeochem.2005.11.003

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_dbe_vs_c(mf_data_demo, z_var = "norm_int")

Plot DBE vs ppm with Option for Interactive Plot

Description

This function generates a scatter plot of DBE (Double Bond Equivalent) versus parts per million (ppm) from the provided data. It also provides the option to customize the appearance and to return an interactive plotly plot.

Usage

uplot_dbe_vs_ma(
  mfd,
  z_var = "norm_int",
  fun = median,
  palname = "redblue",
  tf = FALSE,
  size_dots = 1.5,
  ...
)

Arguments

Value

A ggplot or plotly object.

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_dbe_vs_ma(mfd = mf_data_demo, size_dots = 1)

Plot DBE vs Oxygen Atoms (cf. Herzsprung et al. 2014) with Option for Interactive Plot

Description

This function generates a scatter plot of Double Bond Equivalent (DBE) versus the number of oxygen atoms (o). It allows for optional customization of colors based on a specified variable (z_var) and offers the option to convert the plot to an interactive plotly object.

Usage

uplot_dbe_vs_o(
  mfd,
  z_var = "norm_int",
  fun = median,
  palname = "redblue",
  tf = FALSE,
  size_dots = 1.5,
  ...
)

Arguments

Value

A ggplot or plotly object.

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Frequency Plot of a Selected Variable

Description

Creates a frequency plot (bar plot) for a selected variable in a molecular formula dataset. Values are grouped and counted, then visualized as bars. A unified UME plot theme is applied for consistent styling across all uplot_* functions.

Usage

uplot_freq(
  mfd,
  var = "14N",
  col = "grey",
  space = 0.5,
  width = 0.3,
  logo = TRUE,
  gg_size = 12,
  plotly = FALSE,
  ...
)

Arguments

Value

A ggplot object, or a plotly object when plotly = TRUE.

Histogram of Mass Accuracy

Description

Creates a histogram of mass accuracy values (ppm). Includes summary statistics (median, 2.5% and 97.5% quantiles). Follows general uplot behavior:

• returns a ggplot2 object by default

• converts to plotly only if plotly = TRUE

• uses caption-style UME logo

Usage

uplot_freq_ma(mfd, ma_col = "ppm", bins = NULL, ...)

Arguments

Value

ggplot or plotly object

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Mass Accuracy Frequency Histogram

Description

Creates a histogram showing the frequency distribution of mass accuracy values (ppm). Displays median and quantile statistics in the title and optionally adds a UME caption (logo). The plot uses the unified UME theme (theme_uplots()), ensuring visual consistency across all ⁠uplot_*⁠ functions.

Usage

uplot_freq_vs_ppm(
  df,
  col = "grey",
  width = 0.01,
  gg_size = 12,
  logo = TRUE,
  plotly = FALSE
)

Arguments

Details

This plot is useful for visual inspection of mass accuracy performance. The required additional columns (⁠14N⁠, ⁠32S⁠, ⁠31P⁠, dbe_o) ensure that the dataset is a complete UME molecular formula table and can be compared to other quality-control plots.

Value

A ggplot2 histogram, or a plotly object if plotly = TRUE.

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_freq_vs_ppm(mf_data_demo)

H/C vs Molecular Mass Plot

Description

Creates a scatter plot of the hydrogen-to-carbon ratio (H/C) versus molecular mass (nm). Points are color-coded according to a selected intensity or property column (int_col). This visualization follows the conceptual design in Schmitt-Kopplin et al. (2010).

Usage

uplot_hc_vs_m(
  mfd,
  int_col = "norm_int",
  palname = "redblue",
  size_dots = 1.2,
  plotly = FALSE,
  ...
)

Arguments

Value

A ggplot2 object, or a plotly object if plotly = TRUE.

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_hc_vs_m(mf_data_demo, int_col = "norm_int")

Heteroatom Combination vs Mass Accuracy

Description

Produces a boxplot visualizing the distribution of mass accuracy (ppm) for different heteroatom combinations (nsp_type) defined by the number of nitrogen (N), sulfur (S), and phosphorus (P) atoms in each formula.

The plot can be returned as either a ggplot object or as an interactive plotly object (plotly = TRUE). An optional “UltraMassExplorer” watermark can be added.

Usage

uplot_heteroatoms(df, col = "grey", gg_size = 12, logo = TRUE, plotly = FALSE)

Arguments

Value

A ggplot or plotly interactive boxplot.

See Also

Other uplots: uplot_cluster(), uplot_cvm(), uplot_dbe_minus_o_freq(), uplot_dbe_vs_c(), uplot_dbe_vs_ma(), uplot_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_heteroatoms(mf_data_demo)

Precision of Isotope Abundance

Description

Isotope precision describes how reliably the instrument reproduces the expected intensity of the naturally occurring ^{13}\mathrm{C} isotope peak relative to its corresponding monoisotopic ^{12}\mathrm{C} peak.

Usage

uplot_isotope_precision(
  mfd,
  z_var = "nsp_tot",
  int_col = "norm_int",
  size_dots = 1.5,
  bins = 100,
  data_reduction = FALSE,
  tf = FALSE,
  logo = TRUE,
  plotly = FALSE,
  cex.axis = 1,
  cex.lab = 1.4
)

Arguments