Package {ume}

Title:	Ultrahigh-Resolution Mass Spectrometry Data Evaluation for Complex Organic Matter
Version:	1.6.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://ume.awi.de/, https://www.awi.de/en/ume
Depends:	R (≥ 4.2.0)
Imports:	data.table, ggplot2, plotly, vegan, viridis, jsonlite
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
LazyDataCompression:	xz
RoxygenNote:	7.3.3
Suggests:	rmarkdown, pander, knitr, testthat (≥ 3.0.0), xml2, pdftools
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-05-09 15:04:24 UTC; bokoc
Author:	Boris Koch [aut, cre], Stephan Frickenhaus [ctb], Oliver Lechtenfeld [ctb], Tim Leefmann [ctb], Fabian Moye [ctb]
Maintainer:	Boris Koch <boris.koch@awi.de>
Repository:	CRAN
Date/Publication:	2026-05-09 16:00: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 map a variable or column name to a more descriptive, human-readable label based on a lookup table.

The lookup table must contain two columns:

• name_pattern – Regular expressions to match column names

• name_substitute – Human-readable label returned when pattern matches

The function returns the first matching substitute label. If no pattern matches, the input colname is returned unchanged.

This function is not exported and is intended for use inside the ume package (e.g., for automatic axis labeling in plotting functions).

Usage

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

Arguments

Details

Lookup Pretty Labels for Column Names (Internal)

Value

A character string: either the substitute label or the original colname if no pattern matches.

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

Format

An object of class list of length 9.

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

Format

An object of class list of length 2.

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 categories using ume::known_mf. Join molecular formula data and metadata about known formulas (e.g. annotate carboxylic-rich alicyclic molecules; CRAM). The name of the molecular formula column will be set to "mf".

This function works with:

• a vector of molecular formulas: returns a 2-column data.table(mf, categories)

• a data.table with a formula column: returns the table with an added categories column

Usage

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

Arguments

Value

A data.table containing additional columns having information on formula categories

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

add_known_mf(mfd = mf_data_demo)

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"))

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: check_formula_library(), check_mfd()

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 identification, as calculated by calc_ideg().

iterr, iterr_n, iterr2, iterr2_n

Iteration error indices from calc_iterr().

median(i_magnitude)

Median intensity value.

int(basepeak)

Intensity of the base peak.

int(summed)

Summed intensity of all peaks.

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.

See Also

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

Examples

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"
)

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)
)

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_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_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 from Zenodo

Description

Downloads one of the UME formula libraries from Zenodo only when explicitly called by the user.

Unlike earlier versions, this CRAN-compliant implementation:

• never writes to the user's filespace unless dest is explicitly provided

• does NOT create ~/.ume/ or any other default directory

• does NOT perform automatic caching

• In non-interactive environments (CRAN checks), the function returns NULL

Usage

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

Arguments

Value

A data.table or NULL (in non-interactive mode).

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 = NULL,
  mfd_filt_tf = NULL,
  mfd_filt_tf_pivot = NULL,
  ds_tf = NULL,
  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)

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:

mz

Mass to charge ratio (numeric)

mf

molecular formula

Source

taken from www.awi.de

See Also

Other ume data: lib_demo, masses, mf_data_demo, nice_labels_dt, peaklist_demo, tab_ume_labels

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, nice_labels_dt, peaklist_demo, tab_ume_labels

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:

element

Element symbol in lower case

symbol

Element symbol in upper case

isotope

Isotope symbol in lower case

label

Isotope 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, nice_labels_dt, peaklist_demo, tab_ume_labels

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

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

CRAM

Molecular formula that was identified (CRAM == 1) as carboxylic rich alicyclic molecule according to Hertkorn et al. (2006). See ume::known_mf for details.

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)

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)

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

n_assignments

Number of molecular formula assignments per molecular mass after filter process

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, nice_labels_dt, peaklist_demo, tab_ume_labels

Examples

data(mf_data_demo)

nice_labels_dt

Description

nice_labels_dt

Usage

nice_labels_dt

Format

A data.table with labels that can be used for plots

name_substitute

Name that will be displayed instead of the standard column name

name_pattern

Name of the standard column in ume tables

Source

taken from www.awi.de

See Also

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

Examples

data(nice_labels_dt)

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, nice_labels_dt, tab_ume_labels

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)

Labels of UME columns.

Description

Labels of UME columns.

Usage

tab_ume_labels

Format

A data.table that is derived from the MarChem database:

label

Identifier for each label

nice_label

Label that can be used e.g. in figures

use_in_ume

Shows if label is used in the UME shiny app

Source

taken from www.awi.de

See Also

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

Examples

data(tab_ume_labels)

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.

uplot_cluster

Description

This function plots the results of a cluster analysis and a multi-dimensional scaling (MDS) plot based on the input data. It first creates a hierarchical cluster dendrogram using the Bray-Curtis dissimilarity index, followed by an MDS plot for dimensionality reduction. The function outputs both plots side by side.

Usage

uplot_cluster(mfd, grp = "file_id", int_col = "norm_int", ...)

Arguments

Details

Plot Cluster Analysis and Multi-Dimensional Scaling

Value

A named list with two elements:

dendrogram

A recordedplot object containing the hierarchical clustering dendrogram generated from the Bray–Curtis dissimilarity matrix.

mds

A plotly object representing the two-dimensional Multi-Dimensional Scaling (MDS) scatter plot. This can be rendered interactively in HTML or converted to a static ggplot object if needed.

The function always returns a list with these two components.

Note

This function requires the vegan package for the Bray-Curtis dissimilarity and MDS calculations.

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

# Example with demo data
  out <- uplot_cluster(mfd = mf_data_demo, grp = "file", int_col = "norm_int")
  out$dendrogram
  out$mds

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).

The function can optionally add a branding label ("UltraMassExplorer") and can optionally return an interactive Plotly version of the plot.

Usage

uplot_hc_vs_m(
  df,
  int_col = "norm_int",
  palname = "redblue",
  size_dots = 1.2,
  gg_size = 12,
  logo = TRUE,
  plotly = FALSE,
  ...
)

Arguments

Value

A ggplot2 scatter plot, 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

Details

The measured ^{13}\mathrm{C} signal provides an intrinsic validation of molecular formula assignments.

For a molecule containing n carbon atoms with a natural abundance of 1.07% for ^{13}\mathrm{C}, the theoretical relative intensity of the isotope peak ^{13}\mathrm{C}_{1}^{12}\mathrm{C}_{n-1} is:

I_{theo} = n \times 0.0107

The measured intensity I_{meas} provides an independent estimate of the number of carbon atoms:

n_{calc} = \frac{I_{meas}}{0.0107}

From this, the deviation in carbon number can be defined:

C_{dev} = n_{assigned} - n_{calc}

A value of C_{dev} = 0 indicates perfect agreement between the formula assignment and the isotope-based estimate. Negative values indicate that the measured isotope abundance is lower than expected.

Isotope precision is assessed by evaluating the distribution of C_{dev} across peaks with sufficient signal quality. C_{dev} becomes small and stable at higher signal-to-noise ratios (S/N). Therefore, isotopic peak ratios for intense mass signals provide an internal metric for validating molecular formula assignments. The function visualizes the deviation between measured and theoretical ^{13}\mathrm{C} isotope ratios. Supports optional data reduction (binning) to enhance interactive rendering speed in Plotly.

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_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), 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()

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

Kendrick Mass Defect (KMD) vs. Nominal Mass Plot

Description

This function generates a scatter plot of Kendrick Mass Defect (KMD) versus nominal mass (nm), with color-coding based on a specified variable (z_var). Optionally, the plot can be returned as an interactive Plotly object.

Usage

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

Arguments

Details

Kendrick Mass Defect (KMD) vs. Nominal Mass Plot

Value

A ggplot or plotly object.

References

Kendrick E. (1963). A mass scale based on CH_2 = 14.0000 for high resolution mass spectrometry of organic compounds. Analytical Chemistry, 35, 2146–2154.

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

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_heteroatoms(), uplot_isotope_precision(), 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()

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_heteroatoms(), uplot_isotope_precision(), 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_kmd(mf_data_demo, z_var = "norm_int")

Internal: Apply UME layout styling to plotly figures

Description

Internal helper function used by UME plotting functions to add consistent layout styling and an optional UME logo annotation to Plotly figures.

This function is not exported. End users should not call it.

Usage

uplot_layout(fig, margin = TRUE, ...)

Arguments

Value

A modified plotly object with UME styling applied.

Plot LC-MS Spectrum (or fallback MS if no RT available)

Description

Creates a 3D LC–MS plot (RT x m/z x intensity) when retention time is available. If no retention-time column exists (e.g., with DI-FTMS demo data), the function gracefully falls back to uplot_ms() and issues an informative message.

Usage

uplot_lcms(
  pl,
  mass = "mz",
  peak_magnitude = "i_magnitude",
  retention_time = "ret_time_min",
  label = "file_id",
  logo = FALSE,
  ...
)

Arguments

Value

A plotly 3D visualization (LC-MS) or a 2D MS spectrum fallback.

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_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Plot Mass Accuracy vs m/z

Description

Generates a UME-style scatter plot showing mass accuracy (ppm) versus mass-to-charge ratio (m/z).

Summary statistics (median, 2.5% and 97.5% quantiles) are displayed as horizontal reference lines and an annotation panel.

The plot is returned as a ggplot2 object by default, with optional plotly conversion for interactivity.

Usage

uplot_ma_vs_mz(mfd, ma_col = "ppm", logo = FALSE, plotly = FALSE, ...)

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_dbe_vs_o(), uplot_freq_ma(), uplot_freq_vs_ppm(), uplot_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ms(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_ma_vs_mz(mf_data_demo, ma_col = "ppm")

Plot Mass Spectrum

Description

Plots a mass spectrum, showing peak magnitude versus mass-to-charge ratio (m/z).

Optionally reduces the dataset by selecting the most abundant peaks per spectrum.

Usage

uplot_ms(
  pl,
  mass = "mz",
  peak_magnitude = "i_magnitude",
  label = "file_id",
  logo = FALSE,
  plotly = TRUE,
  data_reduction = 1,
  ...
)

Arguments

Value

A ggplot 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_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_n_mf_per_sample(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_ms(pl = peaklist_demo, data_reduction = 0.1, plotly = TRUE)
uplot_ms(pl = peaklist_demo, data_reduction = 1, plotly = FALSE)

Number of Molecular Formulas per Sample Plot

Description

Creates a bar plot showing how many molecular formulas were assigned per sample (file_id). The plot title contains the mean and standard deviation of assigned molecular formulas across samples. Optionally, the plot can be converted to an interactive Plotly plot or display the UltraMassExplorer logo.

Usage

uplot_n_mf_per_sample(
  df,
  col = "grey",
  logo = TRUE,
  width = 0.3,
  gg_size = 12,
  plotly = FALSE
)

Arguments

Details

Number of Molecular Formulas per Sample / File

Value

A ggplot 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_hc_vs_m(), uplot_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_pca(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

uplot_n_mf_per_sample(mf_data_demo)

Plot PCA Results

Description

Performs Principal Component Analysis (PCA) on molecular formula intensity data and visualizes the results as a PCA score plot and a Van Krevelen plot colored by PC1 loadings.

Usage

uplot_pca(
  mfd,
  grp,
  int_col = "norm_int",
  palname = "viridis",
  col_bar = TRUE,
  ...
)

Arguments

Details

Principal Component Analysis (PCA) Plotting

The PCA is performed on a wide matrix with one row per group defined by grp and one column per molecular formula (mf). Intensities are aggregated using the mean if multiple values occur for the same combination of grp and mf.

Columns with zero variance are removed before PCA because they cannot be scaled. The argument grp defines the observational unit for the PCA, for example "file_id", "sample_id", or "ms_id".

Value

A list containing:

pca

The PCA model object returned by stats::prcomp().

t_score

A data.table with PCA scores for each group.

fig_vk

A Van Krevelen plot colored by PC1 loadings.

fig_pca

A PCA score plot of PC1 versus PC2.

mfd

The input molecular formula data augmented with PC1/PC2 scores and PC1/PC2 loadings.

Note

The function uses stats::prcomp() for PCA and uplot_vk() for the Van Krevelen plot.

See Also

uplot_vk()

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_heteroatoms(), uplot_isotope_precision(), uplot_kmd(), uplot_lcms(), uplot_ma_vs_mz(), uplot_ms(), uplot_n_mf_per_sample(), uplot_ratios(), uplot_reproducibility(), uplot_ri_vs_sample(), uplot_vk()

Examples

res <- uplot_pca(
  mfd = mf_data_demo,
  grp = "file_id",
  int_col = "norm_int"
)

res$fig_pca
res$fig_vk

Plot Median of Mass Accuracy per Sample (ppm)

Description

This function generates a bar plot showing the median of mass accuracy (ppm) for each sample. It also provides the option to convert the plot into an interactive plotly object.

Usage

uplot_ppm_avg(df, cex.axis = 12, cex.lab = 15, plotly = FALSE, ...)

Arguments