echtes ume_peaklist und ume_mfd
zentrale normalize_ume_names()
manuelles Mapping
flexiblere MFD-Schemas
einheitliche ID-Auflösung
ms_id als bevorzugter Name
vollständige Rückwärtskompatibilität zu file_id
Target Search liefert standardisierbares MFD
Tests für Entry-Points und ID-Migration
Added zero_filling() for documented zero replacement in compositional sample-by-feature matrices, including feature-wise minimum and median replacement as well as optional zCompositions methods. The function uses as_ume_matrix() which was introduced in 1.7.0.
Added calc_logratio() for CLR, ALR, and robust CLR transformations of UME feature matrices using vegan::decostand().
Added calc_time_flattened_mfd() to aggregate chromatographic molecular formula data into a pseudo-direct-infusion-like molecular formula data table by collapsing the retention time dimension. The function automatically detects chromatographic input, validates grouping variables, and supports customizable aggregation and grouping columns.Improved readability of uplot_ri_vs_sample() for larger datasets by
automatically optimizing sample ordering and axis label layout.
Improved documentation: calc_data_summary(), calc_neutral_mass(), data objects
Migrated uplot_hc_vs_m(), uplot_ma_vs_mz(), uplot_isotope_precision(), uplot_ri_vs_sample(), and uplot_reproducibility() to the shared uplot_wrapper() plotting backend (already used by uplot_dbe_vs_c(), uplot_kmd(), uplot_vk(), uplot_ms(), and others). This reduces code duplication and unifies theming, labelling, and interactive/plotly behavior across all uplot_*() functions.
uplot_vk() gained a title argument (default "Van Krevelen Diagram"), allowing callers such as uplot_ratios() to set a custom plot title.
The stats annotation box in uplot_ma_vs_mz() now has a semi-transparent white background (fill = "white", alpha = 0.75) so it stays readable when overlaid on data points.
uplot_hc_vs_m(), uplot_isotope_precision(), uplot_ri_vs_sample(), and uplot_reproducibility() dropped their individual logo (and, where present, cex.axis/cex.lab) arguments in favor of the shared uplot_wrapper() defaults (ume_logo = TRUE, ume_label = FALSE, configurable text sizing via ...). Callers explicitly setting these arguments will need to update their code.
uplot_ri_vs_sample()'s first argument was renamed from df to mfd for consistency with the rest of the package's uplot_*() functions.
Requires ggplot2 (>= 3.5.0): annotation code now uses linewidth instead of the deprecated label.size argument for geom_label()/annotate("label", ...). Added an explicit version constraint in DESCRIPTION to prevent silent rendering differences on older ggplot2 versions.
Fixed uplot_wrapper() silently ignoring the plotly argument: only interactive was evaluated internally, so plotly = TRUE had no effect on any function delegating to the wrapper. plotly is now treated as an alias for interactive.
Fixed uplot_ratios() not applying its custom title: the main argument was passed to uplot_vk(), which had no matching parameter and silently dropped it into an unused .... The plot always showed the default "Van Krevelen Diagram" title instead. uplot_vk() now accepts title directly, and uplot_ratios() passes main through to it.
Fixed uplot_ratios() not applying its palname argument to the underlying Van Krevelen plot: palname was consumed by uplot_ratios()'s own formal arguments and never reached uplot_vk(), so the parameter had no visible effect regardless of value.
Added find_kegg_pathways_by_formula() for optional annotation of molecular formulas with KEGG compounds and associated pathways via the KEGG REST API.
Added as_ume_matrix() for converting long-format UME data into sample-by-feature matrices. This standardized pre-processing function is now used internally for multivariate analyses and provides a common foundation for PCA, clustering, and future machine-learning methods.
Added as_mfd() as a flexible entry point for converting external molecular formula tables into UME-compatible molecular formula data (mfd) objects.
Added filter_multi_assignments() for filtering multiple molecular formula assignments based on Kendrick mass defect subgroups and median mass error statistics.
Added centralized variable and synonym dictionary ume_name_dictionary for:
Added dynamic alias mapping support to as_peaklist() and as_mfd() using ume_name_dictionary. ume_name_dictionary now does all nice labels and external column name mappings. Data objects nice_labels_dt and tab_ume_labels were completely removed.
Added support for automatic mapping of Lambda Miner (UFZ Leipzig) column names in filter_multi_assignments().
Expanded isotope-handling capabilities:
create_isotope_expanded_table().download_library() improved design and user feedback.
Consolidated all UME variable-name, synonym, and label mappings into the centralized dictionary object ume_name_dictionary. This improves interoperability of UME import functions with external naming conventions and third-party software exports.
ume_name_dictionary is now generated from the MarChem database dictionary and serves as the single source of truth for:
add_known_mf() now uses ume_name_dictionary to identify active formula categories instead of relying on tab_ume_labels.
Removed several redundant internal mapping tables and unified name handling across UME workflows.
Improved support for external naming conventions through dictionary-based synonym mappings (e.g. Lambda Miner column names).
Improved robustness of column-name normalization and automatic label handling.
Improved compatibility of internal helper .f_label() with old and new dictionary formats.
Removed unnecessary columns from known_mf.
Updated README and package documentation.
Added public GitHub mirror: https://github.com/boriskoch/ume
All future releases are now archived on Zenodo.
download_library(): addressed a bug, which resulted in a failed sha256 check.
Fixed a miscalculation in calc_number_occurrence().
Improved handling of repeated isotope tokens during molecular formula standardization.
Various fixes related to metadata handling and semantic variable mapping.
Introduced internal helper .get_ume_alias_map().
Reworked internal metadata infrastructure toward centralized semantic variable mapping.
Replaced several hard-coded label mappings with dictionary-based lookups.
Expanded internal support for future object entry points and external data interoperability.
Published on CRAN.
calc_isotope_pattern() returns exact mass, nominal mass, probability, relative abundance, molecular formula (mf), and isotope-specific molecular formula (mf_iso) for each isotope peak.inchi_to_mf(): Extracts molecular formula string from an InChI code.check_neutral_mf(): Is a given string for a neutral molecular formula correct?
calc_nm() and related workflows now correctly preserve input order and duplicate formulas when character vectors are supplied.convert_molecular_formula_to_data_table()
isotope_default. Unspecific element notation such as Mo can now be resolved either to the most abundant isotope ("most_abundant", default) or to the lightest isotope ("lightest").C2H5OH or Cl3[37Cl2][37Cl4].create_isotope_expanded_table() now also accepts character vectors of molecular formulas as input.convert_data_table_to_molecular_formulas() was rewritten to preserve original row order and duplicate entries using internal row identifiers.\check_neutral_mf()
uplot_ms()
validate_isotope_presence(): Validates parent molecular formulas based on the presence or absence of corresponding isotope daughter signals within the same mass spectrum.create_isotope_expanded_table():
create_custom_formula_library() as well.interactive = TRUE for interactive plotly outputadd_known_mf():
categories column.uplot_dbe_vs_ma() replaces uplot_dbe_vs_ppm()
known_mf: AbioS formulas added (after Gomez-Saez et al., 2021)
calc_iterr(): documentation updated and reference added
theme_uplots() to unify the layout of plot functions.download_library() now follows CRAN rules for downloading external data.calc_norm_int() always recalculates n_occurrence and n_assignments, the argument ms_id is passed to calc_number_assignments().calc_norm_int(): Fixed a corrupt message when using verbose = TRUE.This version is the first submission to CRAN.
filter_mf_data: The select_file_ids argument is deprecated.msg is depricated and replaced verbose.add_known_mf now only adds a single column (categories) to mfdcheck_peaklist was renamed as as_peaklist and now allows the import of external peaklists from e.g. csv-files.UME's large molecular formula libraries (15–125 MB) are now hosted on Zenodo (https://doi.org/10.5281/zenodo.17606457) for open and persistent access.
lib_02.rds: medium-sized balanced librarylib_05.rds: extended high-coverage library (default)These library objects are now S3 class objects.
download_library(), allows users to download and load molecular formula libraries from Zenodo:
overwrite = TRUEdata.table.f_label() looks for pretty labels in the table ume::nice_labels_dt.uplot_cluster() now returns a list object with cluster and mds results and figures.uplot_pca() now returns a list object that includes a plotly PCA figure.main_doc.R.msg() for handling messages (verbose).ume_vignette.pdf added to repository and can be accessed via gitlab readme.classify_files() to automatically group files into categories (e.g., blanks, standards, pools, samples) based on pattern rules. The function is fully flexible: both the search column and the returned ID column can be specified by the user.calc_norm_int(): Normalization via "sum_rank" fixed so that the sum is always based on the exact number of argument n_rank.normalize_verbose() to standardize message control across functions. Both verbose (preferred) and the legacy msg argument are supported. If both are provided, verbose takes precedence and a warning is issued.msg is now deprecated in favor of verbose. Existing code using msg will continue to work but may trigger a warning.This version introduces a new nomenclature. All columns carrying information on isotopes are now named according to the official IUPAC nomenclature to avoid ambiguities.
For example, the column 'c' that contains the number of atoms of 12C is now called '12C' (capital "C"!).
This had implications for the entire ume data pipeline. Functions such as check_mfd(), check_formula_library(), and check_peaklist() can now help to enforce the new nomenclature.
calc_recalibrate_ms.R() now expects a filename (file). The new argument insufficient_calibrants (valid argument values: "extrapolate", "remove_spectrum") handles spectra, in which no calibrant masses were identified. The argument value "extrapolate" takes the median of calibration slope and intercept for all spectra that could be calibrated with at least two masses and uses these values to calibrate the spectra that showed no calibration masses. The argument value "remove_spectrum" deletes all peaks of those spectra for which no calibrant masses were identified.get_isotope_info() is now a fundamental function that identifies element / isotope information in any table. It returns the original names of the isotope columns of the table and related IUPAC information on the isotope.identify_isotope_columns() is depricated and merged into get_isotope_info().add_known_mf() now provides a column that contains all category labels. In future versions separate columns for each category (such as "CRAM") will be depricated.assign_formulas(): pl (peaklist) can now also be a numeric mass vector or a single mass. For numeric input, a minimal peaklist is constructed internally. The result data.table is now returned visibly (before: return(invisible(mfd))). The consistency of the numeric peaklist is now checked by the function check- _peaklist().check_peaklist() now allows manual assignment of the column names containing the mass spectrum filename, file identifier (numeric column), the m/z values, and peak magnitude. The columns will be renamed according to the internal naming of these column in ume.check_mfd() and check_formula_library() now enforce the new isotope nomenclature.calc_data_summary(), calc_eval_params(), calc_norm_int(), calc_recalibrate(), convert_molecular_formula_to_data_table(), create_custom_formula_library(), eval_isotopes(), eval_isotopes(), order_columns(), filter functions, and plotting functions were all modified to match the new isotope nomenclature.calc_data_summary(): hard-coded conversion of i_magnitude column to data type numeric.calc_dbe() now stops if the valence of an element in the formula is not provide. Function modified to match new isotope nomenclature.convert_data_table_to_molecular_formulas has a new argument keep_element_sums that provides columns for the count of atoms for each element (sum of isotope counts such as 'C_tot'). Function modified to match new isotope nomenclature.assign_formulas() that was introduced in version 1.2.1 (April 7 2025).convert_molecular_formula_to_data_table: nominal mass (nm) is now also returned.calc_exact_mass: Now returns a single numeric vector. If mfd is a character value, it is interpreted as a molecular formula and evaluated:
calc_exact_mass("C2H4") returns 28.031300129.calc_nm: Now always returns a single numeric vector. If mfd is a character value, it is interpreted as a molecular formula and evaluated:
calc_nm("C2H4") returns 28.uplot_ms(): the column specified by the argument label is now internally converted by as.factor().ume::peaklist_demo: integer column file_id added (to be consistent with changes in version 0.2.4. Column file now contains the names of the MS spectra. Columns m_min, m_max, and m were removed because they can be calculated using calc_neutral_mass() and calc_ma_abs().
Other:
assign_formulas(): The arguments memory_efficient (FALSE / TRUE) and chunk_n (number of peaks in each chunk) allow processing in chunks to be more memory efficient.\remove_blanks(): if a column for retention time is detected or provided (via the ret_time_col argument), blanks will be removed only for a given retention time and not for the entire spectrum. The argument LCMS is deprecated.main_docu.R updated.- `calc_recalibrate_ms()`: argument `formula_library` was removed.
The calibration is now only based on lists of molecular formulas provided
either by `calibr_list` or by `custom_calibr_list`.
- `assign_formulas()` is now much faster for small libraries (n<=10 entries),
because the peaklist is pre-filtered before matching with the library.
- `identify_isotope_columns()`: column names "sn" and "sc" are explicitly
excluded to avoid confusions with element names.
identify_isotope_columns(): Apply this function to a data.table to identify columns that have element or isotope information.
convert_data_table_to_molecular_formulas(): Create molecular formula strings for a table that has element or isotope information.
create_ume_formula_library() completely renovated. The function now excepts any element and isotope by providing two molecular formulas for the upper and lower limit of each isotope in the final library.
Functions calc_dbe(), calc_nm(), calc_exact_mass() now consider all element and isotopes and a flexible usage of spelling.
Major update in package documentation: The internal helper function main_docu() documents arguments that occur in many ume functions (@inheritParams main_docu).
convert_molecular_formula_to_data_table() is now fundamentally faster, recognizes isotopes in a formula (square brackets), and also returns the exact mass of a formula. The function can now be used to build small custom formula libraries. #### Minor changesassign_formulas() now checks if all required function arguments are available.uplot_cluster() now supports custom column names.- `uplot_cluster()`: Cluster + NMDS function added: `uplot_cluster()`
- `uplot_pca()`:
- `uplot_ms()`: Revised and a `data_reduction` argument was added
to accelerate plotting.
- `uplot_ratios()`: For comparing peak intensities of molecular formulas
between two spectra.
- `uplot_cvm()`: new
- `uplot_freq()`: new
- `uplot_freq_ma()`: new
- `uplot_freq_vs_ppm()`: new
- `uplot_hc_vs_m()`: new
- `uplot_heteroatoms()`: new
- `uplot_isotope_precision()`: update
- `uplot_kmd()`: new
- `uplot_layout()`: new
- `uplot_lcms()`: update
- `uplot_ma_vs_mz()`: new
- `uplot_n_mf_per_sample()`: new
- `uplot_pca()`: new
- `uplot_ratios()`: new
- `uplot_reproducibility()`: new
- `uplot_ri_vs_sample()`: new
- `uplot_vk()`: update
- `uplot_ppm_average()`: new
- `uplot_dbe_vs_o()`: new
- `uplot_dbe_vs_c()`: new
- `uplot_dbe_vs_ppm()`: new
- `uplot_dbe_minus_o()`: new
- `ustats_outlier()`: moved from `stats.R`
xml2 has been removed as a dependency. It is only required for the function read_xml_peaklist(), which now checks for the xml2 package installation specifically.known_mf updated to UTF-8 encoding.assign_formulas() and check_formula_library() are now returned invisibly.calc_neutral_mass(): now takes a vector as function argument.remove_blanks(): There was an error for LC data.assign_formulas() adapted for formula libraries containing only one formula (e.g. when assigning the post-column standard in LCMS)calc_recalibrate_ms() adapted for formula libraries containing only one formula (e.g. when assigning the post-column standard in LCMS)ume:::extract_metadata_from_ufz_files()check_formula_library()calc_recalibrate_ms() udated because of changes in calc_neutral_mass()add_known_mf() improved if a molecular formula column is not existing in the source table mfd.add_missing_element_columns()assign_formulas()read_xml_files(). Default folder_path now is NULL, which opens a dialogue box for folder selection.extract_metadata_from_UFZ_files(). Default folder_path now is NULL, which opens a dialogue box for folder selection.calc_db() error handling updated and argument element_names added, which handles the style of element / isotope symbols ("lower case" (default) / "upper case")extract_metadata_from_UFZ_files()This version now includes unit tests. Following versions will allow that functions can be applied to single values and vectors in tables.
calc_ma() and calc_ma_abs():
DT and pander removed from package.create_custom_formula_library())search_for_mf_target())eval_isotopes(): Provide warning, if there is no isotope information available in molecular formula data.convert_molecular_formulas()read_xml_peaklist()search_for_mf_target()ume::known_mf that indicates photo- and biodegradation (Seibt, 2017; PhD thesis)calc_recalibrate_ms() now allows for customized formula lists as reference for calibration.calc_shannon_index(), calc_simpson_index(), calc_pielou_eveness()).data.table::foverlap(), which doubles the speed of formula assignment.process_orbi_data() that reads scans from a list of mzML files and assigns formulas to each scan.create_ume_formula_library() updatedChanges in calibration procedure (calc_recalibrate_ms.R):
calibr_list was extended by "E_coli_metabolome" for the calibration of metabolome samples
Mass accuracy plot (uplot.freq_ma in plot.R):
bug fix: calculation of median and quantile mass accuracies now ignores missing values.
Updates in documentation
calc_eval_params.R: AI will only be calculated for molecular formulas in which C > O + N + P calc_data_summary.R: wa(AI) is now calculated from intensity weighted average element numbers.calc_recalibrate_ms.R: At least 5 calibrants must now be detected in an analyses for recalibration. Otherwise the respective analysis (file_id) will be removed from the recalibration peaklist.NEWS.md file to track changes to the package.assign_formulas_new.R that is more memory efficient and faster (now based on data.table::foverlap())file_id now ALWAYS has to be numeric.