export_ume_results: 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()
)

Value

Invisibly returns:

the path to the ZIP file (if zip = TRUE), or
the path to the output directory (if zip = FALSE).

Arguments

pl

data.table containing peak data. Mandatory columns include neutral molecular mass (mass), peak magnitude (i_magnitude), and a peak identifier (peak_id).

mfd

data.table with molecular formula data as derived from ume::assign_formulas. Column names of elements/isotopes must match names in the isotope column of ume::masses; values are integers representing counts per formula.

mfd_filt

data.table or coercible object. Filtered version of the molecular formula dataset (optional).

mfd_filt_tf

data.table or coercible object. Transformed filtered MFD used in downstream calculations (optional).

mfd_filt_tf_pivot

data.table or coercible object. Pivoted / wide-format intensity matrix derived from mfd_filt_tf (optional).

ds_tf

data.table or coercible object. Transformed diagnostic statistics (optional).

outdir

Character. Output directory in which all export files are stored. The directory is created if it does not exist. Must be provided explicitly; no default is used to comply with CRAN policies on writing to the user's filespace. For temporary exports, use e.g. outdir = file.path(tempdir(), "ume_export").

prefix

Character. Prefix for all exported file names (e.g., "SRFA_001"). Default: "ume".

figures

Controls figure export:

FALSE – no figures are exported
TRUE – export all plot-like objects found in env
character vector – export only the listed object names

Recognized plot types are: ggplot, plotly, and recordedplot (base R).

fig_width, fig_height

Numeric. Dimensions of exported figures in inches. Default: 8 × 6.

fig_device

Character. File format for figure export. One of "png" (default) or "pdf".

zip

Logical. If TRUE (default), the exported directory is compressed into a .zip file in the same parent directory as outdir.

metadata

Named list. Additional metadata to write into metadata.R (e.g., analysis settings, instrument parameters, user comments). Default: empty list.

env

Environment. Environment from which figure objects should be collected. Default: parent.frame().

Details

Export UME Analysis Results