Package 'mrmhub'

Description

$ syntax can be used to as a shortcut for getting specific variables and results from a MRMhubExperiment object

Usage

## S4 method for signature 'MRMhubExperiment'
x$name

Arguments

Value

Value with a variable or a tibble

Examples

mexp <- MRMhubExperiment(title = "Test Experiment", analysis_type = "lipidomics")
mexp$analysis_type
mexp$title
mexp$annot_analyses

Description

Metadata provided as a list of tibbles will be validated for consistency against the loaded analysis data of the provided MRMhubExperiment object and then transferred.

Usage

add_metadata(data = NULL, metadata, excl_unmatched_analyses = FALSE)

Arguments

Value

An updated MRMhubExperiment object

See Also

The metadata guide.

Description

Opens an interactive Shiny application that helps you turn your data and metadata files into a runnable Quarto (.qmd) mrmhub workflow. Point the app at your files, tick the processing steps you need, and the app validates the inputs against each step (warning, for example, when normalize_by_istd is selected but no istd_feature_id is defined) while previewing the generated workflow document for download.

Usage

build_workflow()

Value

Invisible NULL. Launches the Shiny app in the default browser.

See Also

generate_workflow_qmd() for the non-interactive generator.

Examples

if (interactive()) {
  build_workflow()
}

Description

Calculates the average molecular weight of one or more chemical formulas, based on the natural isotopic distribution of elements. The calculation uses the enviPat package to retrieve isotopic masses and abundances, and computes the weighted mean of the isotopic distribution.

Usage

calc_average_molweight(formula)

Arguments

Details

This function calculates the average molecular weight (not monoisotopic mass), which reflects the average of the isotopic distribution found in nature.

Isotopes can be specified explicitly in the formula. Atomic mass numbers for isotopes must be enclosed in square brackets (e.g., ⁠[13]C⁠ for carbon-13). Deuterium must be written as D instead of ⁠[2]H⁠.

The function uses the enviPat package to validate and parse chemical formulas, calculate isotopic patterns, and determine the average molecular weight based on weighted means of isotopic abundances.

Value

A numeric vector of average molecular weights, one for each formula; NA for a missing formula.

References

Loos, M., Gerber, C., Corona, F., Hollender, J., & Singer, H. (2015). Accelerated Isotope Fine Structure Calculation Using Pruned Transition Trees. Analytical Chemistry, 87(11), 5738–5744. doi:10.1021/acs.analchem.5b00941

Examples

calc_average_molweight(c("C6H12O6", "[13]C6H12O6", "C8H10N4O2", "D2O"))

Description

Calibration curves are calculated for each feature using ISTD-normalized intensities and the corresponding concentrations of calibration samples, as defined in the qc_concentrations metadata. The regression fit model (linear or quadratic) and the weighting method (either "none", "1/x", "1/x^2", or "1/sqrt(x)") can be defined globally via the arguments fit_model and fit_weighting for all features, if fit_overwrite is TRUE. Alternatively, the model and weighting can be defined individually for each feature in the feature metadata (columns curve_fit_model and curve_fit_weighting). If these details are missing in the metadata, the default values provided via fit_model and fit_weighting will be used.

Usage

calc_calibration_results(
  data = NULL,
  variable = "feature_norm_intensity",
  include_qualifier = TRUE,
  fit_overwrite,
  fit_model,
  fit_weighting,
  ignore_missing_annotation = FALSE,
  include_fit_object = FALSE,
  lod_sigma = c("residual", "intercept"),
  ignore_failed_calibration = FALSE
)

Arguments

Details

A linear curve is also fitted with 2 calibrators, and a single calibrator gives a line through the origin (coef_a = 0). A quadratic curve needs at least 3 calibrators. A zero-concentration calibrator is dropped from weighted fits, so a blank plus one standard is then fitted through the origin. A curve that passes through all its calibrators (e.g. 2 points for a line, 3 for a quadratic) has no R², sigma, LoD or LoQ (NA).

Additionally, the limit of detection (LoD) and limit of quantification (LoQ) are calculated for each feature based on the calibration curve, following the ICH Q2(R1/R2) approach (LoD = 3.3 sigma / S, LoQ = 10 sigma / S). Here S is the slope of the calibration curve, taken at zero concentration (the linear coefficient coef_b). For a quadratic fit the true slope is ⁠b + 2 c x⁠, which reduces to coef_b at zero concentration, so the quadratic term does not contribute to the slope used here. ICH Q2 specifies the slope formula for linear responses only; using the low-concentration tangent slope for a quadratic fit is an approximation beyond the guideline (adequate when the curvature near zero is small).

The response standard deviation sigma is selected via lod_sigma, following the ICH-acceptable choices: "residual" uses the residual standard error of the regression (Sy/x; the default and prior behaviour), while "intercept" uses the standard error of the intercept. The sigma column reported in metrics_calibration is always the residual standard error, independent of this choice.

The results of the regression and the calculated LoD and LoQ values are stored in the metrics_calibration table of the returned MRMhubExperiment object.

Calibration coefficient columns

The fitted curve is stored in ascending power order, following R's lm() / poly() convention. The model is

response = coef_a + coef_b * x + coef_c * x^2

• coef_a — intercept (0th-order term, x^0)

• coef_b — 1st-order (linear) coefficient (x^1); the slope of a linear fit

• coef_c — 2nd-order (quadratic) coefficient (x^2); NA for a linear fit

Only linear and quadratic models are fitted, so there are no higher-order terms. This ascending order is the reverse of the descending a*x^2 + b*x + c form printed by some vendor software (e.g. Agilent MassHunter, where a is the quadratic term). When comparing against such an export, match coefficients by power (coef_a = intercept, coef_c = x^2), not by letter.

Value

A modified MRMhubExperiment object with an updated metrics_calibration table containing the calibration curve results, including concentrations, LoD, and LoQ values for each feature.

References

ICH Harmonised Tripartite Guideline. Validation of Analytical Procedures: Text and Methodology Q2(R1) (2005); Q2(R2) (2023). International Council for Harmonisation of Technical Requirements for Pharmaceuticals for Human Use.

See Also

quantify_by_calibration() for calculating concentrations based on external calibration curves.

Description

Automatically discovers isotopic (M+2) interference relationships between measured features and stores them in the annot_interferences slot, ready for correct_isotopic_interferences(). Two levels are supported:

• "MRM" (default): fragment-based front/back correction for class-based LC-MRM data, derived from the LICAR method (see the manual). Requires precursor and product m/z and an mrm_pattern per feature.

• "MS1": whole-molecule M+2 correction for MS1 / full-scan acquisitions. The factor is the M+2 relative abundance of each species' molecular formula; interfering pairs are matched by precursor m/z (~2 Da apart) within a feature class. Requires precursor m/z only.

Usage

calc_isotopic_interferences(
  data = NULL,
  level = c("MRM", "MS1"),
  mz_tol = 0.5,
  min_contribution = 0,
  check_coelution = FALSE
)

Arguments

Details

Important — MS1 is not a fallback for MRM. For MRM data the isotopic correction must be fragment-based: the contribution of heavy isotopes to a transition depends on the isotope's location relative to the fragmentation (Gao et al. 2021). The whole-molecule ("MS1") level is only valid for genuine MS1/full-scan measurements and must not be used as a substitute for MRM data that happens to lack a product m/z.

Derived factors are sensitive to the enviPat version; version 2.8 is the reference. Existing manual interferences (source == "manual") are preserved; previously derived ("auto") rows are replaced.

How the contribution factor is computed

The contribution K is the fraction of a lighter species' signal that appears at M+2; it is subtracted downstream by correct_isotopic_interferences() as $value_{corrected} = value_{raw} - K \cdot value_{interferer}$.

• MS1 (whole-molecule): $K = \sum ab(\text{peaks within } \pm 0.5 \text{ Da of } M_0 + 2)\, /\, ab(M_0)$, computed from the species' molecular formula with enviPat isopattern (see mN_rel_abundance()).

• MRM (fragment-based, LICAR): the fragment elemental formula is built from the precursor carbon/hydrogen count plus a per-class offset c(C, H, O, N), with $H = 2C + c_H - 2 H_{raw}$; K is that fragment's M+2 isotopologue fraction from enviPat isowrap (centroided, algorithm 2 — chosen over isopattern for parity with published LICAR values). Front vs back distinguishes whether the heavy isotope lands on the retained product ion or the neutral loss; FA/LCB species carry a front + back pair, and LCB inverts the front/back assignment relative to FA.

Value

The MRMhubExperiment with a populated annot_interferences slot.

References

Gao L. et al. (2021). LICAR: An Application for Isotopic Correction of Targeted Lipidomic Data Acquired with Class-Based Chromatographic Separations Using Multiple Reaction Monitoring. Analytical Chemistry, 93(6), 3163-3171. doi:10.1021/acs.analchem.0c04565

Description

Computes various quality control (QC) metrics for each feature in a MRMhubExperiment object. Metrics are derived from different sample types and can be computed either across the full dataset or as medians of batch-wise calculations.

Usage

calc_qc_metrics(
  data = NULL,
  use_batch_medians = FALSE,
  use_robust_cv = FALSE,
  include_norm_intensity_stats = NA,
  include_conc_stats = NA,
  include_response_stats = NA,
  include_calibration_results = NA
)

Arguments

Details

Batch-wise calculations: The function computes the following QC metrics for each feature and for different QC sample types (e.g., SPL, TQC, BQC, PBLK, NIST, LTR)

The format for the metrics is standardized as metric_name_qc_type, where qc_type refers to the specific QC sample type for which the metric is calculated. For example: intensity_min_spl refers to the minimum intensity Statistics of normalized intensities, external calibration, and response curves can be included by setting the relevant arguments (include_norm_intensity_stats, include_conc_stats, include_response_stats, include_calibration_results) to TRUE.

Note when corresponding underlying processed data is not available, the function will not raise an error but will return NA values for the respective metrics. This, however, does not apply for the optional metrics mentioned above. For these cases an error will be raised if the underlying data is missing.

If use_batch_medians = TRUE, batch-specific QC statistics are computed first, and then the median of these values is returned for each feature. However, response curve and calibration statistics are calculated per curve, irrespective of batches and use_batch_medians settings.

The calculated metrics are stored in the metrics_qc table of the MRMhubExperiment objects and comprises following details

• Feature details: Specific feature information extracted from the feature metadata table, such as feature class, associated ISTD, quantifier status.

• Feature MS method information (if available in the imported data): precursor_mz, product_mz and collision_energy per feature. A value that differs between analyses indicates inconsistent acquisition conditions; it is set to NA with a warning naming the features.

• Missing Value Metrics:

  • missing_intensity_prop_spl: Proportion of missing intensities for the SPL sample type.

  • missing_norm_intensity_prop_spl: Proportion of missing normalized intensities for SPL samples.

  • missing_conc_prop_spl: Proportion of missing concentration values for SPL samples.

  • na_in_all: Indicator if a feature has all missing intensities across all samples

• Retention Time (RT) Metrics: Requires that retention time data are available.

  • ⁠rt_min_*⁠: Minimum retention time across different QC sample types (e.g., SPL, BQC, TQC).

  • ⁠rt_max_*⁠: Maximum retention time across different QC sample types.

  • ⁠rt_median_*⁠: Median retention time for specific QC sample types like PBLK, SPL, BQC, TQC, etc.

• Intensity Metrics:

  • n_bqc, n_tqc, n_spl: Number of analyses with a non-missing intensity per QC type, i.e. the replicates behind the %CV and D-ratio (the median of the per-batch counts with use_batch_medians = TRUE). %CV and D-ratio are NA below 3 replicates.

  • ⁠intensity_min_*⁠: Minimum intensity value for features across different QC sample types such as SPL, TQC, BQC, etc.

  • ⁠intensity_max_*⁠: Maximum intensity values across sample types.

  • ⁠intensity_median_*⁠: Median intensity for various QC sample types.

  • ⁠intensity_cv_*⁠: Coefficient of variation (CV) of intensity values for specific QC types.

  • ⁠sb_ratio_*⁠: Signal-to-blank ratios such as the ratio of intensity values for SPL vs PBLK, UBLK, or SBLK. Blank medians count a blank analysis without detected signal (a missing value or no row for the feature) as zero, giving a ratio of Inf.

  • ⁠intensity_q10_*⁠: The 10th percentile of intensity values for the SPL sample type.

• Normalized Intensity Metrics (only if include_norm_intensity_stats = TRUE): Requires that raw intensities were normalized, see normalize_by_istd() for details.

  • ⁠norm_intensity_cv_*⁠: Coefficient of variation (CV) of normalized intensities for QC sample types like TQC, BQC, SPL, etc.

• Concentration Metrics (only if include_conc_stats = TRUE): Requires that concentration were calculated, see quantify_by_istd() or quantify_by_calibration() for details.

  • ⁠conc_median_*⁠: Median concentration values for different QC sample types like TQC, BQC, SPL, NIST, and LTR.

  • ⁠conc_cv_*⁠: Coefficient of variation (CV) for concentration values.

  • ⁠conc_dratio_sd_*⁠: The ratio of standard deviations of concentration between BQC or TQC and SPL samples.

  • ⁠conc_dratio_mad_*⁠: The ratio of median absolute deviations (MAD) between BQC or TQC and SPL concentrations.

• Response Curve Metrics (if include_response_stats = TRUE): Calculates response curve statistics for each feature and each curve (where ⁠#⁠ refers to the curve identifier). Requires that response curves are defined in the data. See get_response_curve_stats() for additional details.

  • r2_rqc_#: R² value of the linear regression for the response curve, representing the goodness of fit.

  • slopenorm_rqc_#: Normalized slope of the linear regression for the response curve, indicating the relationship between the response and concentration.

  • y0norm_rqc_#: Normalized intercept of the linear regression for the response curve, representing the baseline or starting value.

• External Calibration Results Incorporates external calibration results, if include_calibration_results = TRUE and calibration curves are defined in the data:

  • fit_model: The regression model used for curve fitting.

  • fit_weighting: The weighting method applied during curve fitting.

  • lowest_cal: The lowest nonzero calibration concentration.

  • highest_cal: The highest calibration concentration.

  • r.squared: R² value indicating the goodness of fit.

  • coef_a: The intercept of the regression line (both linear and quadratic fits).

  • coef_b:

    • For linear fits, the slope of the regression line.

    • For quadratic fits, the coefficient of the linear term (x).

  • coef_c:

    • For quadratic fits, the coefficient of the quadratic term (⁠x²⁠).

    • Set to NA for linear fits.

  • sigma: The residual standard error of the regression model.

  • reg_failed: Boolean flag indicating if regression fitting failed.

Value

A MRMhubExperiment object with an updated metrics_qc table containing computed QC metrics for each feature.

Description

This function calibrates feature abundances based on a specified reference sample. Calibration can be applied to the entire dataset using one or more reference samples, or batch-wise using reference sample analyses present within each batch. For both approaches, multiple measurements of the same reference sample are summarized using either mean (default) or median (set by the summarize_fun argument).

Usage

calibrate_by_reference(
  data,
  variable,
  reference_sample_id,
  absolute_calibration,
  batch_wise = FALSE,
  summarize_fun = "mean",
  store_conc_ratio = NULL,
  undefined_conc_action = NULL,
  store_normalized = FALSE
)

Arguments

Details

Calibration can be performed in two ways, either absolute, resulting in concentrations, or relative, resulting in ratios:

1. Absolute calibration (when absolute_calibration = TRUE)

   Calibrates (or re-calibrates) feature abundances based on known concentrations of the corresponding features defined for a reference sample. The calibrated concentration for a given analyte is calculated as:

   $c_\textrm{cal}^\textrm{Analyte} = \frac{c_\textrm{sample}^\textrm{Analyte}}{c_\textrm{ref}^\textrm{Analyte}} \times c_\textrm{known}^\textrm{Analyte}$

   The input variable can be either conc, norm_intensity, or intensity, whereas the result is always stored under the variable conc (concentration), in the unit defined for the feature concentrations in the reference sample.

   Metadata requirements:

   • sample_id and analyte_id must be defined for the reference sample and features in the analysis and feature metadata, respectively.

   • Known analyte concentrations must be defined in the ⁠QC concentration⁠ metadata for the for the reference sample

   • An error will be raised if no concentrations are defined for any features

   Missing analyte concentrations for the reference sample can be handled via undefined_conc_action with following options:

   • original: Keep original feature values, i.e. the non-calibrated values will be returned. Note: this is only available when variable = conc. Use with caution to avoid mixing units.

   • na: Set affected features values to NA

   • error: The function stops with error in case of any undefined reference sample feature concentration.

   • In case all feature concentrations are undefined, the function will stop with an error.

   The re-calibrated feature concentrations are stored as conc, overwriting existing conc values. The original conc values are stored as conc_beforecal.

   The ratio between the measured and expected (known) concentrations in the reference sample is available via the feature variable feature_conc_ratio and is calculated as follows:

   $c_\textrm{ratio}^\textrm{Analyte} = \frac{c_\textrm{measured}^\textrm{Analyte}}{c_\textrm{expected}^\textrm{Analyte}}$

   where $c_\textrm{measured}$ is the measured (non-calibrated) concentration, and $c_\textrm{expected}$ is the known or reference concentration for the same analyte. A ratio of 1 indicates perfect agreement; values above or below 1 indicate over- or underestimation.

   To export the calibrated concentrations use save_dataset_csv() with variable = "conc", or to export non-calibrated values with variable = "conc_beforecal". When saving the MRMhub XLSX report, the calibrated concentrations will also be stored as conc.

2. Normalization (relative calibration, absolute_calibration = FALSE)

   Normalizes feature abundances with corresponding feature abundances in a reference sample, resulting in ratios. Any available feature abundance variable (i.e., conc, norm_intensity, or intensity) can be used as input. The normalization is calculated for all present features. The resulting output will be stored as ⁠[VARIABLE]_normalized⁠, whereby ⁠[VARIABLE]⁠ is the input variable, e.g., conc_normalized.

   To export the normalized abundances, use save_dataset_csv() with variable = "[VARIABLE]_normalized". When saving the MRMhub XLSX report via save_report_xlsx(), available unfiltered normalized feature abundances will be included by default. To include filtered normalized feature abundances, set filtered_variable = "[VARIABLE]_normalized".

Value

A MRMhubExperiment object with calibrated data

See Also

normalize_by_istd(), quantify_by_istd(), quantify_by_calibration()

Description

Validates that the user's R environment is correctly configured to use mrmhub. Checks R version, key dependencies, and optional packages.

Usage

check_setup(verbose = TRUE)

Arguments

Value

A list (invisibly) with elements r_version, required, and optional, each containing pass/fail status.

Examples

check_setup()

Description

This function performs batch centering correction on each feature. Optionally, the scale of the batches can be equalized across batches. The selected QC types (ref_qc_types) are used to calculate the medians, which are then used to align all other samples. The correction can be applied to one of three variables: "intensity", "norm_intensity", or "conc". The correction can either be applied on top of previous corrections or replace all prior batch corrections.

Usage

correct_batch_centering(
  data = NULL,
  variable,
  ref_qc_types,
  correct_scale = FALSE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  log_transform_internal = TRUE,
  feature_list = NULL,
  replace_exisiting_trendcurves = FALSE,
  ...
)

Arguments

Value

A MRMhubExperiment object containing the corrected data.

See Also

plot_runscatter() for visualizing the correction before and after; the drift-correction tutorial for a worked example.

Description

Adjusts batch effects with the empirical-Bayes ComBat method (Johnson et al. 2007), applied to one of "intensity", "norm_intensity", or "conc". ComBat models a location and scale batch effect per feature and shrinks those estimates across features, which can stabilise many small batches better than simple median centering.

Unlike correct_batch_centering() and correct_batch_serrf(), ComBat estimates batch effects from all study samples and routine QCs (optionally protecting biology via covariates), not only from the reference QCs. Blanks, response curves, calibrants and other analysis types are left out of the fit and keep their uncorrected values. On strongly unbalanced designs this can remove genuine biological signal, so supply covariates when the biological grouping is not balanced across batches. ref_qc_types is used only for the before/after QC-CV report and the plotting trend curves.

Batch correction is performed after normalization and drift correction in the recommended pipeline. Features with any missing or non-finite values in the selected variable are left uncorrected (ComBat requires complete data).

Usage

correct_batch_combat(
  data = NULL,
  variable,
  ref_qc_types,
  covariates = NULL,
  ref_batch = NULL,
  parametric = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  log_transform_internal = TRUE,
  feature_list = NULL,
  replace_exisiting_trendcurves = FALSE
)

Arguments

Value

A MRMhubExperiment with corrected data.

References

Johnson WE, Li C, Rabinovic A (2007). Adjusting batch effects in microarray expression data using empirical Bayes methods. Biostatistics, 8(1), 118-127. doi:10.1093/biostatistics/kxj037

Applied through sva::ComBat() from the sva package. See also Broadhurst D, et al. (2018), Metabolomics, 14, 72 (doi:10.1007/s11306-018-1367-3) on QC-based signal correction.

See Also

correct_batch_centering(), correct_batch_serrf(), correct_drift_loess() and plot_runscatter() for visualisation. The drift and batch correction manual.

Examples

# mexp <- correct_batch_combat(mexp, variable = "conc", ref_qc_types = "BQC")

Description

This is an independent re-implementation of SERRF in mrmhub, adapted from the reference code in the malbacR package (not the original authors' package); see Details. Validate results against the reference SERRF for your data.

Normalises systematic error with SERRF (Systematic Error Removal using Random Forest; Fan et al. 2019). For each feature and batch a random forest is trained on the reference QC samples, using the batch's most-correlated features as predictors, and the learned systematic error is removed from the study samples and routine QCs; blanks, response curves, calibrants and other analysis types keep their uncorrected values. Unlike ComBat, SERRF captures non-linear drift and batch effects jointly and is anchored on the QC samples, matching the QC-based design of the package; it is best suited to larger panels with dense QC coverage.

SERRF operates on the raw abundance scale (no log transform). Features with missing or non-positive values, and batches with fewer than two reference QCs, are left uncorrected. Batch correction is performed after normalization and drift correction in the recommended pipeline.

Usage

correct_batch_serrf(
  data = NULL,
  variable,
  ref_qc_types,
  n_correlated = 10,
  num_trees = 500,
  seed = 1L,
  num_threads = 1L,
  show_progress = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  feature_list = NULL,
  replace_exisiting_trendcurves = FALSE
)

Arguments

Details

The implementation adapts the reference SERRF code in the malbacR package, keeping its normalization arithmetic but selecting each feature's predictors from the per-batch QC-sample Spearman correlation (a simplification of malbacR's QC/sample correlation intersection). Random forests are fit with ranger::ranger() and a fixed seed, so results are reproducible. Users are encouraged to validate results against the reference SERRF implementation for their data.

Batches are corrected independently and in parallel via mirai (through purrr::in_parallel()); set up workers with mirai::daemons() beforehand to use them, otherwise the batches are processed sequentially.

Value

A MRMhubExperiment with corrected data.

References

Fan S, Kind T, Cajka T, et al. (2019). Systematic Error Removal Using Random Forest for Normalizing Large-Scale Untargeted Lipidomics Data. Analytical Chemistry, 91(5), 3590-3596. doi:10.1021/acs.analchem.8b05592

Implementation adapted from the malbacR package (https://github.com/pmartR/malbacR); random forests via ranger (Wright MN, Ziegler A, 2017, Journal of Statistical Software, 77(1), doi:10.18637/jss.v077.i01).

See Also

correct_batch_centering(), correct_batch_combat(), correct_drift_loess() and plot_runscatter() for visualisation. The drift and batch correction manual.

Examples

# mexp <- correct_batch_serrf(mexp, variable = "conc", ref_qc_types = "BQC")

Description

Applies the interference corrections you declared in the feature metadata (the legacy interference_feature_id / interference_contribution columns, and any source == "manual" rows in annot_interferences) to the raw feature intensities, using the same engine and formula as correct_isotopic_interferences(). Use this for in-source fragments, co-eluting isobars or other non-isotopic interferences you know about. Warns and returns the data unchanged if none are defined.

Usage

correct_custom_interferences(
  data = NULL,
  variable = "feature_intensity",
  sequential_correction = TRUE,
  neg_to_na = FALSE
)

Arguments

Value

MRMhubExperiment object with feature intensities corrected.

See Also

correct_isotopic_interferences(), correct_interference_manual(); the interference-correction guide.

Description

Function to correct for run-order drifts within or across batches via a provided custom function

Usage

correct_drift(
  data = NULL,
  smooth_fun,
  variable,
  ref_qc_types,
  batch_wise,
  replace_previous = TRUE,
  log_transform_internal = TRUE,
  conditional_correction = FALSE,
  cv_diff_threshold = 0,
  use_original_if_fail = TRUE,
  ignore_istd = TRUE,
  feature_list = NULL,
  recalc_trend_after = FALSE,
  show_progress = TRUE,
  ...
)

Arguments

Details

The drift correction function needs to be provided by the user. See smooth_fun for details.

Value

MRMhubExperiment object

Description

This function corrects for run-order drifts within or across batches using cubic spline smoothing. The correction is typically based on QC (Quality Control) samples that are measured at specific intervals throughout the run sequence. The smoothed curve derived from the QC samples is then used to adjust all other samples in the dataset. The correction can be applied to "intensity", "norm_intensity", or "conc" data.

The cubic spline smoothing approach, particularly when used with the regularization parameter lambda, is similar but not identical to previously described QC-based drift correction methods, such as QC-RSC (Quality Control Regularized Spline Correction), described in Dunn et al. (Nat Protoc, 2011) and Kirwan et al. (Anal Bioanal Chem, 2013).

By default, the smoothing parameter is determined using cross-validation, which can lead to overfitting. To reduce overfitting the regularization parameter lambda may be defined, with a good starting point being lambda = 0.01. Additionally, the global smoothing parameter can be specified via spar.

It is recommended to visually inspect the correction using the plot_runscatter() function. Set the argument recalc_trend_after = TRUE so that the trends after correction are also available for plotting. For further details, refer to the description of plot_runscatter().

The corrections can be applied on a batch-by-batch basis (batch_wise = TRUE, default) or across all batches (batch_wise = FALSE). Existing corrections are either replaced (replace_previous = TRUE) or added on top of them (replace_previous = FALSE).

Furthermore, drift correction can be applied unconditionally (conditional_correction = FALSE) or conditionally, based on whether the sample CV change before and after correction is below a defined threshold (cv_diff_threshold). This conditional correction is assessed independently for each batch if batch_wise = TRUE, where the median of the CV changes across the batch is compared with the threshold.

Note: The function outputs a message indicating the median CV change and the median absolute CV before and after correction for all samples. However, these metrics are experimental and should not be used as definitive criteria for correction (see Details below).

This cubic spline method is implemented using the base R function stats::smooth.spline().

Usage

correct_drift_cubicspline(
  data = NULL,
  variable,
  ref_qc_types,
  batch_wise = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  cv = TRUE,
  spar = NULL,
  lambda = NULL,
  penalty = 1,
  conditional_correction = FALSE,
  recalc_trend_after = FALSE,
  log_transform_internal = TRUE,
  feature_list = NULL,
  cv_diff_threshold = 0,
  use_original_if_fail = FALSE,
  show_progress = TRUE
)

Arguments

Details

In the output message, the median CV change is computed as the median of CV changes for all features in global correction or for features where the correction passed the defined CV difference threshold in case of conditional correction (conditional_correction = TRUE). For batch-wise correction, the change is calculated per batch, with the final median CV change being the median of these batch medians across features.

Value

MRMhubExperiment object

References

Dunn, W., Broadhurst, D., Begley, P. et al. Procedures for large-scale metabolic profiling of serum and plasma using gas chromatography and liquid chromatography coupled to mass spectrometry. Nat Protoc 6, 1060–1083 (2011). https://doi.org/10.1038/nprot.2011.335

Kirwan, J.A., Broadhurst, D.I., Davidson, R.L. et al. Characterising and correcting batch variation in an automated direct infusion mass spectrometry (DIMS) metabolomics workflow. Anal Bioanal Chem 405, 5147–5157 (2013). https://doi.org/10.1007/s00216-013-6856-7

See Also

stats::smooth.spline(); the drift-correction tutorial for a worked example.

Description

This function corrects for run-order drifts within or across batches using Generalized Additive Models (GAMs). The correction uses penalized splines, with automatic selection of smoothing parameters based on cross-validation or penalized likelihood. It is typically based on QC (Quality Control) samples measured at specific intervals throughout the run sequence. The correction can be applied to "intensity", "norm_intensity", or "conc" data.

It is recommended to visually inspect the correction using the plot_runscatter() function. Set the argument recalc_trend_after = TRUE so that the trends after correction are also available for plotting. For further details, refer to the description of plot_runscatter().

The corrections can be applied on a batch-by-batch basis (batch_wise = TRUE, default) or across all batches (batch_wise = FALSE). Existing corrections are either replaced (replace_previous = TRUE) or added on top of them (replace_previous = FALSE).

Furthermore, drift correction can be applied unconditionally (conditional_correction = FALSE) or conditionally, based on whether the sample CV change before and after correction is below a defined threshold (cv_diff_threshold). This conditional correction is assessed independently for each batch if batch_wise = TRUE, where the median of the CV changes across the batch is compared with the threshold.

Note: The function outputs a message indicating the median CV change and the median absolute CV before and after correction for all samples. However, these metrics are experimental and should not be used as definitive criteria for correction (see Details below).

This method is implemented using penalized splines via the mgcv::gam() function.

Usage

correct_drift_gam(
  data = NULL,
  variable,
  ref_qc_types,
  batch_wise = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  bs = "ps",
  k = -1,
  sp = NULL,
  log_transform_internal = TRUE,
  conditional_correction = FALSE,
  recalc_trend_after = FALSE,
  feature_list = NULL,
  cv_diff_threshold = 0,
  use_original_if_fail = FALSE,
  show_progress = TRUE
)

Arguments

Details

In the output message, the median CV change is computed as the median of CV changes for all features in global correction or for features where the correction passed the defined CV difference threshold in case of conditional correction (conditional_correction = TRUE). For batch-wise correction, the change is calculated per batch, with the final median CV change being the median of these batch medians across features.

This smoothing is based on Generalized Additive Models (GAM) using penalized splines, implemented via mgcv::gam().

Value

MRMhubExperiment object

See Also

mgcv::gam(); the drift-correction tutorial for a worked example.

Description

Performs drift correction for run-order effects within or across batches using Gaussian kernel smoothing, as detailed in Teo et al. (2020). The Gaussian kernel estimates the local data trend, with bandwidth defined by the kernel_size parameter. This smoothing approach is mostly used with study samples and should only be applied to datasets with sufficiently randomized or stratified samples to avoid local biases and artifacts. The smoothing can be applied to concentration, norm_intensity, and intensity data.

Corrections can be applied on a batch-by-batch basis (batch_wise = TRUE, default) or across all batches (batch_wise = FALSE). The correction can either replace existing drift or batch corrections (replace_previous = TRUE, default) or applied on top of existing corrections (replace_previous = FALSE).

Drift correction can be applied to all features (conditional_correction = FALSE) or conditionally, based on whether the sample CV difference before and after correction is below a defined threshold (cv_diff_threshold). The conditional correction is applied separately for each batch if batch_wise = TRUE.

It is recommended to visually inspect the correction using the plot_runscatter() function. Set the argument recalc_trend_after = TRUE so that the trends after correction are also available for plotting. For further details, refer to the description of plot_runscatter(). This will double the processing time.

Note: The function outputs a message indicating the median CV change and the median absolute CV before and after correction for all samples. However, these metrics are experimental and should not be used as definitive criteria for correction (see Details below).

Usage

correct_drift_gaussiankernel(
  data = NULL,
  variable,
  ref_qc_types,
  batch_wise = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  kernel_size = 10,
  outlier_filter = FALSE,
  outlier_ksd = 5,
  location_smooth = TRUE,
  scale_smooth = FALSE,
  log_transform_internal = TRUE,
  conditional_correction = FALSE,
  cv_diff_threshold = 0,
  recalc_trend_after = FALSE,
  feature_list = NULL,
  use_original_if_fail = FALSE,
  show_progress = TRUE
)

Arguments

Details

In the output message, the median CV change is computed as the median of CV changes for all features in global correction or for features where the correction passed the defined CV difference threshold in case of conditional correction (conditional_correction = TRUE). For batch-wise correction, the change is calculated per batch, with the final median CV change being the median of these batch medians across features.

Value

Returns a MRMhubExperiment object.

References

Teo G., Chew WS, Burla B, Herr D, Tai ES, Wenk MR, Torta F, & Choi H (2020). MRMkit: Automated Data Processing for Large-Scale Targeted Metabolomics Analysis. Analytical Chemistry, 92(20), 13677–13682. https://doi.org/10.1021/acs.analchem.0c03060

Description

This function corrects for run-order drifts within or across batches using LOESS (Locally Estimated Scatterplot Smoothing). The correction is typically based on QC (Quality Control) samples that were measured at specific intervals throughout the run sequence. The smoothed curve derived from the QC samples is then used to adjust all other samples in the dataset. The correction can be applied to "intensity", "norm_intensity", or "conc" data.

The degree of smoothing is controlled by the span parameter span (default is 0.75). Additionally, the degree parameter can be specified to control the degree of the polynomial used in the local regression (default is 2)

It is recommended to visually inspect the correction using the plot_runscatter() function. Set the argument recalc_trend_after = TRUE so that the trends after correction are also available for plotting. For further details, refer to the description of plot_runscatter().

The LOESS correction only applies to samples that lie within the span of the QC samples used for smoothing. Extrapolation outside this range is not recommended, as it can lead to unreliable corrections or artefacts in the extrapolated regions. However, extrapolation can be activated by setting extrapolate = TRUE. This may be useful in cases where specific drifts occur in segments of the analysis sequence that are not spanned by the QC samples, such as when the analysis was interrupted or the instrument had rapid changes in performance.

The corrections can be applied on a batch-by-batch basis (batch_wise = TRUE, default) or across all batches (batch_wise = FALSE). Existing corrections are either replaced (replace_previous = TRUE) or added on top of them (replace_previous = FALSE).

Furthermore, drift correction can be applied unconditionally (conditional_correction = FALSE) or conditionally, based on whether the sample CV change before and after correction is below a defined threshold (cv_diff_threshold). This conditional correction is assessed independently for each batch if batch_wise = TRUE, where the median of the CV changes across the batch is compared with the threshold.

Note: The function outputs a message indicating the median CV change and the median absolute CV before and after correction for all samples. However, these metrics are experimental and should not be used as definitive criteria for correction (see Details below).

This LOESS method is implemented using the base R function stats::loess().

Usage

correct_drift_loess(
  data = NULL,
  variable,
  ref_qc_types,
  span = 0.75,
  degree = 2,
  batch_wise = TRUE,
  ignore_istd = TRUE,
  replace_previous = TRUE,
  conditional_correction = FALSE,
  recalc_trend_after = FALSE,
  log_transform_internal = TRUE,
  feature_list = NULL,
  cv_diff_threshold = 0,
  use_original_if_fail = FALSE,
  extrapolate = FALSE,
  show_progress = TRUE
)

Arguments

Details

In the output message, the median CV change is computed as the median of CV changes for all features in global correction or for features where the correction passed the defined CV difference threshold in case of conditional correction (conditional_correction = TRUE). For batch-wise correction, the change is calculated per batch, with the final median CV change being the median of these batch medians across features.

Value

MRMhubExperiment object

See Also

The drift-correction tutorial for a worked example.

Description

Subtract a single, user-specified interference from one feature. Use this for a one-off correction or to validate a factor before trusting the automatic derivation; for the metadata-driven paths use correct_isotopic_interferences() (automatic, isotopic) or correct_custom_interferences() (declared). The interference is subtracted as:

$Value_{Corrected} = Value_{Feature} - Factor_{Contribution} * Value_{Interfering Feature}$

Usage

correct_interference_manual(
  data = NULL,
  variable,
  feature,
  interfering_feature,
  interference_contribution,
  neg_to_na = FALSE,
  updated_feature_id = NA
)

Arguments

Value

MRMhubExperiment object

Description

Applies the isotopic (M+2) interference corrections previously discovered by calc_isotopic_interferences() (and any declared interferences, see correct_custom_interferences()) to the raw feature intensities. Aborts with guidance if no interferences have been derived yet.

The subtraction is

$value_{corrected} = value_{raw} - K \cdot value_{interferer}$

applied on the raw feature_intensity. For auto-derived (source == "auto") edges the interferer is clamped at 0 before subtraction and the result clamped at 0 (LICAR parity); declared ("manual") edges are unclamped. See calc_isotopic_interferences() for how K is computed.

A chain (e.g. PC 34:2 > PC 34:1 > PC 34:0) is corrected sequentially by default, each feature using its already-corrected interferer; set sequential_correction = FALSE to correct each from the raw interferer. The raw signal is preserved in feature_intensity_orig, and the correction is idempotent (re-running restores from raw first).

Usage

correct_isotopic_interferences(
  data = NULL,
  variable = "feature_intensity",
  sequential_correction = TRUE,
  neg_to_na = FALSE
)

Arguments

Value

MRMhubExperiment object with feature intensities corrected.

References

Gao L., Ji S, Burla B, Wenk MR, Torta F, & Cazenave-Gassiot A (2021). LICAR: An Application for Isotopic Correction of Targeted Lipidomic Data Acquired with Class-Based Chromatographic Separations Using Multiple Reaction Monitoring. Analytical Chemistry, 93(6), 3163-3171. https://doi.org/10.1021/acs.analchem.0c04565

See Also

The interference-correction guide.

Description

This function computes the percent coefficient of variation of the values in x. If na.rm is TRUE then missing values are removed before computation proceeds.

Usage

cv(x, na.rm = FALSE, use_robust_cv = FALSE, min_n = 1L)

Arguments

Value

a numeric value. If the mean (or the median, for robust CV) is zero, or x is not numeric, NA_real_ is returned

Examples

cv(c(5, 6, 3, 4, 5, NA), na.rm = TRUE)

Description

Computes the percent coefficient of variation (CV) based on the log-transformation of the input data. This can be more robust in certain cases, especially when the data is not normally distributed.

Usage

cv_log(x, na.rm = FALSE)

Arguments

Value

a numeric value. If x contains a zero, then NaN is returned

References

Canchola et al. (2017) Correct use of percent coefficient of variation (% CV) formula for log-transformed data. MOJ Proteomics Bioinform. 2017;6(4):316‒317. DOI: 10.15406/mojpb.2017.06.00200

Examples

cv_log(c(5, 6, 3, 4, 5, NA), na.rm = TRUE)

Description

Load an example MRMhubExperiment dataset: a small, preprocessed subset of a plasma lipidomics dataset (Tan et al., ATVB, 2022).

Usage

data_load_example(data = NULL, dataset = 1)

Arguments

Value

MRMhubExperiment object

Examples

myexp <- MRMhubExperiment()
myexp <- data_load_example(myexp)
myexp

Description

This function sums up feature intensities per analyte_id.

This is useful when you have multiple features (e.g. adducts, isotopes, in-source fragments) or isomers that you want to combine into a single analyte intensity value, such as LPC sn1 and sn2 species.

Usage

data_sum_features(data, qualifier_action = "include")

Arguments

Details

Features are summed when they share an analyte_id (an empty one counts as missing): with qualifier_action = "include" all of them, with "separate" quantifiers and qualifiers each into their own feature (the qualifier sum is named ⁠<analyte_id>_qual⁠), and with "exclude" only the quantifiers, while qualifiers are kept as they are. An analyte with a single feature in its group keeps its feature_id. Only features present in the dataset are summed: excluded features and features listed only in the metadata keep their feature_id and do not affect the sum.

Only raw signal variables are aggregated across the transitions of an analyte: feature_intensity, feature_height and feature_area are summed, and feature_rt is averaged. A sum is NA in an analysis where a constituent is missing, since a partial sum would look like a valid value; a warning reports these analyses. A transition without a value in any analysis is left out of its sum. feature_fwhm, feature_width, feature_int_start and feature_int_end are set to NA for merged analytes: the constituents are separate chromatographic peaks, so no aggregate of their peak widths or borders describes the merged quantity.

Summing transitions redefines feature_intensity, so all values derived from the pre-merge intensities are invalidated and removed: normalized intensities, concentrations, drift/batch correction results and QC metrics. Re-run normalize_by_istd() and the quantitation/correction steps after merging. A message reports this when such values were present.

The summed features must be measured and quantified alike: an error is raised when they combine internal standards with analytes, or differ in istd_feature_id, quant_istd_feature_id, response_factor or interference_feature_id. An error is also raised when a summed id equals the feature_id of another feature. Transitions of one internal standard can be summed; references to summed features in the feature, ISTD and interference metadata are updated, and interferences between transitions summed into one feature are removed. Other metadata (feature_class, feature_label) comes from the first constituent, with a warning when the constituents disagree.

is_quantifier is not inherited but determined by the merge: the merged analyte is a quantifier if any of its constituents is one.

Value

MRMhubExperiment object

Experimental

This function is experimental and its behaviour may change. It overwrites the feature_id of features sharing an analyte_id in both the dataset and the feature metadata, and the original feature_id is not backed up anywhere. Run it after importing metadata and after any exclusions, set_analysis_order() or set_intensity_var(), and before normalization/quantitation: these steps rebuild the dataset from the imported data and stop with an error once features were summed. Running it on a processed object drops the derived variables (see Details).

Description

Retrieves analysis IDs of data outliers based on the principal components (PCA) with SD or MAD fences

Usage

detect_outlier_pca(
  data = NULL,
  variable,
  filter_data,
  pca_component,
  qc_types = NA,
  fence_multiplicator,
  summarize_fun = c("pca", "rma"),
  outlier_detection = c("sd", "mad"),
  log_transform = TRUE
)

Arguments

Value

MRMhubExperiment object

Description

This function excludes specified analyses from a MRMhubExperiment object, either by marking them as invalid for downstream processing. The function also allows to reset the exclusions.

Usage

exclude_analyses(data = NULL, analyses, clear_existing)

Arguments

Value

A modified MRMhubExperiment object with the specified analyses defined as excluded.

Description

This function excludes specified features from a MRMhubExperiment object, either by marking them as invalid for downstream processing. The function also allows to reset the exclusions.

Usage

exclude_features(data = NULL, features, clear_existing)

Arguments

Value

A modified MRMhubExperiment object with the specified features defined as excluded.

Description

Filters a dataset based on quality control (QC) criteria, including intensity, coefficient of variation (CV), signal-to-blank ratios, D-ratio, response curve properties, and proportion of missing values. Criteria apply to different QC types (BQC, TQC) and measurement variables (concentration, intensity, and normalized intensity).

To clear all existing filters, run filter_features_qc() with clear_existing = TRUE and without any filtering criteria.

Usage

filter_features_qc(
  data = NULL,
  clear_existing = TRUE,
  recalc_metrics = FALSE,
  use_batch_medians = FALSE,
  use_robust_cv = FALSE,
  include_qualifier = FALSE,
  include_istd = FALSE,
  features.to.keep = NA,
  max.prop.missing.intensity.spl = NA,
  max.prop.missing.normintensity.spl = NA,
  max.prop.missing.conc.spl = NA,
  min.intensity.lowest.bqc = NA,
  min.intensity.lowest.tqc = NA,
  min.intensity.lowest.spl = NA,
  min.intensity.median.bqc = NA,
  min.intensity.median.tqc = NA,
  min.intensity.median.spl = NA,
  min.intensity.highest.spl = NA,
  min.signalblank.median.spl.pblk = NA,
  min.signalblank.median.spl.ublk = NA,
  min.signalblank.median.spl.sblk = NA,
  max.cv.intensity.bqc = NA,
  max.cv.intensity.tqc = NA,
  max.cv.normintensity.bqc = NA,
  max.cv.normintensity.tqc = NA,
  max.cv.conc.bqc = NA,
  max.cv.conc.tqc = NA,
  response.curves.selection = NA,
  response.curves.summary = NA,
  min.rsquare.response = NA,
  min.slope.response = NA,
  max.slope.response = NA,
  max.yintercept.response = NA,
  max.dratio.sd.conc.bqc = NA,
  max.dratio.sd.conc.tqc = NA,
  max.dratio.mad.conc.bqc = NA,
  max.dratio.mad.conc.tqc = NA,
  max.dratio.sd.normint.bqc = NA,
  max.dratio.sd.normint.tqc = NA,
  max.dratio.mad.normint.bqc = NA,
  max.dratio.mad.normint.tqc = NA
)

Arguments

Details

This function implements filtering criteria based on quality control (QC) samples and additional analytical parameters, following recommendations outlined by Broadhurst et al. (2018). The implemented criteria evaluate data quality through analysis of QC samples, blanks, and study samples.

Value

The input MRMhubExperiment object with the feature filtering criteria applied. Per-criterion verdicts are stored in metrics_qc: pass_minint (the ⁠min.intensity.*⁠ criteria), pass_sb, pass_cva, pass_dratio, pass_linearity and pass_missingval, combined in all_filter_pass. With a response-curve criterion, a feature without response-curve results fails pass_linearity; ISTDs without results are not failed.

References

Broadhurst, D., Goodacre, R., Reinke, S. N., Kuligowski, J., Wilson, I. D., Lewis, M. R., & Dunn, W. B. (2018). Guidelines and considerations for the use of system suitability and quality control samples in mass spectrometry assays applied in clinical studies. Metabolomics, 14(6), 72. doi:10.1007/s11306-018-1367-3

Description

Function for cubic spline-based smoothing with optional cross-validation, for use by correct_drift

Usage

fun_cspline(tbl, ref_qc_types, log_transform_internal, ...)

Arguments

Value

List with a data.frame containing original x and the smoothed y values, and a boolean value indicating whether the fit failed or not.

Description

Function for penalized spline-based smoothing using GAM, for use by correct_drift

Usage

fun_gam_smooth(tbl, ref_qc_types, log_transform_internal = TRUE, ...)

Arguments

Value

List with a data.frame containing original x and the smoothed y values, and a boolean value indicating whether the fit failed or not.

Description

Function for Gaussian kernel-based smoothing, for use by correct_drift.

Usage

fun_gauss.kernel.smooth(tbl, ref_qc_types, log_transform_internal, ...)

Arguments

Value

List with a data.frame containing original x and the smoothed y values, and a boolean value indicting whether the fit failed or not.

Author(s)

Hyung Won Choi

Description

Function for loess-based smoothing, for use by correct_drift

Usage

fun_loess(tbl, ref_qc_types, log_transform_internal, ...)

Arguments

Value

List with a data.frame containing original x and the smoothed y values, and a boolean value indicting whether the fit failed or not.

Description

Assembles a self-contained Quarto document that imports data and metadata and runs the selected processing steps, in canonical order, using the same function calls and defaults as the package tutorials. This is a pure function (no file I/O, no Shiny) so it can be tested and scripted directly; the interactive build_workflow() app calls it to power its live preview.

Usage

generate_workflow_qmd(spec)

Arguments

Value

A length-1 character string containing the .qmd source.

Examples

cat(generate_workflow_qmd(list(
  importer = "mrmhub",
  data_path = "MRMhub_demo.tsv",
  steps = c("normalize_istd", "quantify_istd")
)))

Description

Returns the end time of the analysis, corresponding to the last acquisition_time_stamp from the dataset. Note: if estimate_sequence_end is set to FALSE, the function will return the timestamp of the last analysis in the dataset, corresponding to the start of the last analysis. Set estimate_sequence_end to TRUE to estimate the end time of the analysis sequence, based on the median runtime.

Usage

get_analyis_end(data, estimate_sequence_end)

Arguments

Value

A POSIXct timestamp, or NA_POSIXct_ if the dataset is empty.

Description

Returns the start time of the analysis, corresponding to the earliest acquisition_time_stamp from the dataset.

Usage

get_analyis_start(data)

Arguments

Value

A POSIXct timestamp, or NA_POSIXct_ if the dataset is empty.

Description

Counts the number of interruptions in the analysis, where an interruption is defined as a time gap between consecutive acquisition timestamps that exceeds a given threshold (break_duration_minutes).

Usage

get_analysis_breaks(data, break_duration_minutes)

Arguments

Value

An integer with the number of interruptions, or NA_integer_ if the dataset is empty.

Description

Returns the number of analyses in the dataset, with an optional filter based on qc_types.

Usage

get_analysis_count(data, qc_types = NULL)

Arguments

Value

An integer with the analysis count

Description

This function returns the total duration of the analysis, which is the time difference between the timestamps of the first and last analyses in the sequence.

Usage

get_analysis_duration(data, estimate_sequence_end)

Arguments

Details

If estimate_sequence_end is TRUE, the function will estimate the end time of the analysis sequence by adding the median runtime to the timestamp of the last analysis, instead of simply using the timestamp of the last analysis.

Description

Get the annotated or the originally imported analytical data

Usage

get_analyticaldata(data = NULL, annotated)

Arguments

Value

A tibble with the analytical data in the long format

Description

Returns the lower and upper analysis number (sequence position) spanned by the specified batch or range of batches.

Usage

get_batch_boundaries(data = NULL, batch_indices = NULL)

Arguments

Value

A vector with two elements: the lower and upper analysis number for the specified batch(es).

Description

Extracts calibration fit metrics from a MRMhubExperiment object.

Usage

get_calibration_metrics(
  data = NULL,
  include_qualifier = TRUE,
  with_lod = TRUE,
  with_loq = TRUE,
  with_coefficients = TRUE,
  with_sigma = TRUE,
  summary_table = FALSE
)

Arguments

Details

Requires prior computation of regression results using calc_calibration_results(). See its documentation for details.

Returned Details and Metrics

• feature_id: Feature identifier.

• is_quantifier: Logical, indicates if the feature is a quantifier.

• fit_model: Regression model used for fitting.

• fit_weighting: Weighting method used in fitting.

• lowest_cal: Lowest non-zero calibrator concentration with a response.

• highest_cal: Highest calibrator concentration with a response.

• r2: R² value, indicating goodness of fit. For a weighted fit this is the weighted coefficient of determination (computed from weighted sums of squares), matching the value reported by vendor software such as Agilent MassHunter for the same weighted curve.

• coef_a: Intercept (0th-order term, x^0) of the fitted curve.

• coef_b: 1st-order (linear, x^1) coefficient — the slope in a linear fit, or the linear term in a quadratic fit.

• coef_c: 2nd-order (quadratic, x^2) coefficient in quadratic fits. Returns NA for linear fits.

• sigma: Standard deviation of residuals.

• reg_failed: TRUE if regression fitting failed.

• LoD = 3.3× the sample standard error of residuals / slope of the regression (see Notes).

• LoQ = 10× the sample standard error of residuals / slope of the regression (see Notes).

The coefficients describe the curve in ascending power order (R's lm() / poly() convention): response = coef_a + coef_b * x + coef_c * x^2. This is the reverse of the descending a*x^2 + b*x + c form used by some vendor software (e.g. Agilent MassHunter, where a is the x^2 term), so when comparing against such an export, match by power, not by letter.

Note: LoD/LoQ follow the ICH Q2(R1/R2) approach (3.3 sigma / S and 10 sigma / S). The slope S is the slope of the calibration curve at zero concentration (the linear coefficient coef_b); for a quadratic fit the quadratic term does not contribute to this slope. The response sigma is selectable in calc_calibration_results() via lod_sigma (residual standard error, the default, or the standard error of the intercept); the sigma column reported here is always the residual standard error.

For a weighted fit (1/x, 1/x^2, 1/sqrt(x)) sigma is R's weighted residual standard error, which is not on the raw response scale that the ICH ⁠3.3 sigma / S⁠ formula assumes, so the reported LoD/LoQ are approximate (typically slightly optimistic for 1/x). Use fit_weighting = "none" if you require the strict ICH response-scale Sy/x; the back-calculated concentrations themselves are unaffected.

Value

A tibble with exported calibration metrics.

Description

Returns the number of features in the dataset, with optional filters whether counted features must be internal standard and/or quantifier.

Usage

get_feature_count(data, is_istd = NA, is_quantifier = NA)

Arguments

Value

An integer with the feature count

Description

Returns a vector of annotated feature IDs (feature_id) present in the dataset

Usage

get_featurelist(data, is_istd = NA, is_quantifier = NA)

Arguments

Value

A character vector with feature_id values

Description

Computes the lower and upper boundaries based on Tukey's Interquartile Range (IQR) fences from a numeric vector.

Usage

get_iqr_tails(x, k = 1.5, na.rm = FALSE)

Arguments

Value

A numeric vector of length 2: c(lower_tail, upper_tail).

Description

Computes the lower and upper boundaries based on Median Absolute Deviation (MAD) from a numeric vector. Returns c(NA_real_, NA_real_) if the input vector has less than 2 elements or if no values fall within the computed fences.

Usage

get_mad_tails(x, k, na.rm = FALSE)

Arguments

Value

a numeric vector of length 2 with the lower and upper boundaries.

Description

Computes lower and upper bounds for a numeric vector using one of several methods:

Usage

get_outlier_bounds(
  x,
  method = c("iqr", "mad", "sd", "quantile", "z_normal", "z_robust", "fold_change"),
  k = NULL,
  outlier_log = FALSE,
  na.rm = FALSE
)

Arguments

Details

• "iqr": Tukey's Interquartile Range fences

• "mad": Median Absolute Deviation

• "sd": Standard deviation from mean

• "quantile": Fixed percentile cutoffs

• "z_normal": Standard Z-score using mean & SD

• "z_robust": Modified Z-score using median & MAD

• "fold_change": Median ± log10(k), assumes log-transformed data

Value

A numeric vector of length 2: c(lower_bound, upper_bound) representing the smallest and largest observed values within the computed fences.

Examples

get_outlier_bounds(c(1, 2, 3, 4, 100), "iqr")
get_outlier_bounds(c(1, 2, 3, 4, 100), "mad")
get_outlier_bounds(c(1, 2, 3, 4, 100), "sd")
get_outlier_bounds(c(1, 2, 3, 4, 100), "quantile", k = 0.05)
get_outlier_bounds(c(1, 2, 3, 4, 100), "z_normal")
get_outlier_bounds(c(1, 2, 3, 4, 100), "z_robust")
get_outlier_bounds(log10(c(1, 2, 4, 8)), "fold_change")       # default 2×
get_outlier_bounds(log10(c(1, 2, 4, 8)), "fold_change", k = 3) # 3× fold-change

Description

This function retrieves quality control (QC) bias and variability metrics from a MRMhubExperiment object. It returns a summary of QC metrics for specified QC samples, including bias, absolute bias, and intra-assay coefficient of variation (CV). The standard deviation of the concentration ratio is also included unless it is NA for all analytes, i.e. when no replicates were measured.

Usage

get_qc_bias_variability(
  data,
  qc_types = NA,
  sample_ids = NA,
  wide_format = "none",
  include_qualifier = FALSE,
  with_conc = TRUE,
  with_conc_target = TRUE,
  with_bias = TRUE,
  with_bias_abs = FALSE,
  with_conc_ratio = FALSE,
  with_cv_intra = TRUE,
  with_conc_out_of_range = TRUE,
  summary_table = FALSE
)

Arguments

Details

The standard deviation of concentration is also included unless the number of replicates was 1.

The function uses data from the MRMhubExperiment object and filters it according to the specified QC types and other parameters. It then calculates summary statistics for each feature, such as bias and CV, and organizes the data into a user-specified format.

Value

A data frame containing the calibration results, including metrics such as bias, percentage bias, and intra-assay CV based on specified parameters.

Description

This function calculates linear regression statistics (R², slope, and intercept) for each response curve in the provided MRMhubExperiment object. Each curve is fitted on its points with a non-missing intensity, with a warning when some are missing; a curve with 2 such points has a slope and intercept but no R² (NA), and a curve with fewer gives NA throughout. Before fitting, the analyzed sample amount (x) and feature intensity (y) of these points are each scaled to their maximum (set to 1), so the returned slopenorm and y0norm are on this normalized scale. Optionally, it can include additional statistics from the lancer package (if installed) when with_saturation_stats is set to TRUE.

Usage

get_response_curve_stats(
  data = NULL,
  with_saturation_stats = FALSE,
  limit_to_rqc = FALSE,
  silent_invalid_data = FALSE
)

Arguments

Value

A tibble with linear regression statistics (r2, slopenorm, y0norm) for each curve, or NULL if no data matches the criteria.

Description

Calculates the median run time (in seconds) based of the timestamps differences between consecutive analyses in the sequence.

Usage

get_runtime_median(data)

Arguments

Value

A lubridate time period object, or NA if the dataset is empty.

Description

This function imports analysis results from CSV files in long table format, where each row represents a unique observation of a feature-value pair for an analysis (sample), along with associated feature variables and other metadata. See "Details" below for more information on using this function.

Usage

import_data_csv_long(
  data = NULL,
  path,
  import_metadata = TRUE,
  column_mapping = NULL,
  na_strings = "NA",
  warn_unrecognized_columns = TRUE,
  silent = FALSE
)

Arguments

Details

When no column mapping is provided via the column_mapping argument, the function will automatically detect and import columns with the following names:

Detection of these columns is case-insensitive. Additionally, if feature variable columns use the internal naming convention with prefixes "feature_" or "method_" (e.g. feature_area instead of area), the function will detect and import them automatically.

To import data with different column names, provide a named vector mapping CSV column names to the internal column names used by MRMhubExperiment. The mapping should be in the format: c("analysis_id" = "[CSV column name for analysis]", "feature_id" = "[CSV column name for feature]", ...), where the right-hand side refers to the exact column name in the CSV file header. Columns matching internal names do not require mapping and will be imported automatically. The mapping is case-insensitive.

Note that the dataset must contain an analysis identifier, either as an analysis_id column or via a mapped column.

The function processes all CSV files in the specified directory or the given file(s), combining them into a single dataset. This supports datasets split across multiple files during preprocessing. Each feature and raw data file pair should appear only once to avoid duplication.

The na_strings parameter allows specifying character strings that should be interpreted as NA, ensuring proper handling of missing values.

Value

A MRMhubExperiment object containing the imported data.

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

file_path <- system.file("extdata", "plain_long_dataset.csv", package = "mrmhub")
mexp <- MRMhubExperiment()

# Define the column mapping; right side is the CSV column name
col_map <- c(
  "analysis_id" = "raw_data_filename",
  "qc_type" = "qc_type",
  "feature_id" = "feature_id",
  "feature_class" = "feature_class",
  "istd_feature_id" = "istd_feature_id",
  "feature_rt" = "rt",
  "feature_area" = "area"
)

mexp <- import_data_csv_long(
  data = mexp,
  path = file_path,
  column_mapping = col_map,
  import_metadata = TRUE
)

print(mexp)

Description

Imports analysis result data from wide-format .csv files, where each row corresponds to a single analysis and each feature is stored in its own column. All feature columns hold the same variable type, given by variable_name.

Usage

import_data_csv_wide(
  data = NULL,
  path,
  variable_name,
  analysis_id_col = NA,
  import_metadata = TRUE,
  first_feature_column = NA,
  na_strings = "NA"
)

Arguments

Details

Each row must be identified by an "analysis_id" column (or, if absent, the first column, provided it holds unique values). Every feature is stored in a separate column; the feature columns all contain the single variable type specified by variable_name. Use first_feature_column to mark where the feature columns begin so that leading metadata columns are not mistaken for features.

The variable_name argument specifies the data type represented in the table, which must be one of: "area", "height", "intensity", "norm_intensity", "response", "conc", "conc_raw", "rt", or "fwhm".

If there is no column named analysis_id, it will be inferred from the first column, provided it contains unique values.

When import_metadata is set to TRUE, the following metadata columns will be imported if present:

• analysis_order

• qc_type

• batch_id

• is_quantifier

To prevent additional non-metadata columns from being misinterpreted as features, use the first_feature_column parameter to specify the column where feature data starts.

If a directory path is provided to path, all .csv files in that directory will be processed and merged into a single dataset. This facilitates handling datasets split into multiple files during preprocessing. Ensure each feature and raw data file pair appears only once to avoid duplication errors.

The na_strings parameter allows specifying character strings to be interpreted as missing values (NA). Blank fields are also treated as missing.

Value

A MRMhubExperiment object containing the imported dataset.

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

file_path <- system.file("extdata", "plain_wide_dataset.csv", package = "mrmhub")
mexp <- MRMhubExperiment()
mexp <- import_data_csv_wide(
  data = mexp,
  path = file_path,
  variable_name = "conc",
  import_metadata = TRUE
)
print(mexp)

Description

Imports .csv files exported from Agilent MassHunter Quantitative Analysis software, containing peak integration results. The input files must have analyses (samples) in rows, features/compounds in columns, and either peak areas, peak heights, or response as the values. Additional columns, such as retention time (RT), full-width at half-maximum (FWHM), precursor m/z (PrecursorMZ), and collision energy (CE), will also be imported and made available in the MRMhubExperiment object for downstream analyses.

When a directory path is provided, all matching .csv files in that directory will be imported and merged into a single dataset. This is useful when importing datasets that were pre-processed in blocks, resulting in multiple files. Each unique combination of feature and raw data file must only occur once across all source data files. Duplicate combinations will result in an error.

Usage

import_data_masshunter(
  data = NULL,
  path,
  import_metadata = TRUE,
  expand_qualifier_names = TRUE,
  conc_column = "conc_final",
  silent = FALSE
)

Arguments

Value

MRMhubExperiment object with the imported data

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

mexp <- MRMhubExperiment()
file_path = system.file("extdata", "MHQuant_demo.csv", package = "mrmhub")

mexp <- import_data_masshunter(
  data = mexp,
  path = file_path,
  import_metadata = TRUE,
  expand_qualifier_names = TRUE)

print(mexp)

Description

Imports tabular data files (*.tsv) generated from MRMhub containing peak integration results. The input files must be in a long format with columns for the raw data file name, feature ID, peak intensity, and other columns. Additional information, such as retention time, FWHM, precursor/product m/z, and CE will also be imported and made available in the MRMhubExperiment object for downstream analyses.

When a directory path is provided, all matching files in that directory will be imported and merged into a single dataset. This is useful when importing datasets that were pre-processed in blocks, resulting in multiple files. Each unique combination of feature and raw data file must only occur once across all source data files. Duplicate combinations will result in an error.

Usage

import_data_mrmhub(data = NULL, path, import_metadata = TRUE, silent = FALSE)

Arguments

Value

MRMhubExperiment object with the imported data

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

mexp <- MRMhubExperiment()

file_path = system.file("extdata", "MRMhub_demo.tsv", package = "mrmhub")

mexp <- import_data_mrmhub(
  data = mexp,
  path = file_path,
  import_metadata = TRUE)
print(mexp)

Description

Imports quantitative results from an mzTab-M file (e.g. produced by Lipid Data Analyzer, MS-DIAL or MZmine) into an MRMhubExperiment. Each Small Molecule Feature (SMF) becomes an mrmhub feature and each assay an analysis; the per-assay abundances are imported as feature_intensity.

Usage

import_data_mztab(data = NULL, path, import_metadata = TRUE, silent = FALSE)

Arguments

Details

mzTab-M is a quantification report, so an import is necessarily partial: the single reported abundance per feature is mapped to feature_intensity, and feature identities (name, formula, neutral mass, m/z, retention time) are taken from the SMF/SML sections where available. Internal-standard relationships, QC-type assignments and calibration metadata are not part of mzTab-M and must be supplied afterwards with add_metadata(). study_variable groups are not imported; all analyses are in one batch.

Value

The updated MRMhubExperiment.

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

See Also

import_data_mrmhub(), save_dataset_mztab(), add_metadata()

Examples

## Not run: 
mexp <- MRMhubExperiment()
mexp <- import_data_mztab(mexp, "LDA_export.mzTab")

## End(Not run)

Description

This function imports tabular data files (*.csv) exported from Skyline, containing peak integration results.

Usage

import_data_skyline(
  data = NULL,
  path,
  transition_id_columns = c("name", "mz", "none"),
  import_metadata = TRUE,
  silent = FALSE
)

Arguments

Details

In Skyline, transitions are defined by the ⁠Molecule Name⁠ and corresponding precursor and product m/z values, rather than any identifier. When importing this data, the feature_id is generated using the ⁠Molecule Name⁠ with either precursor/product names or m/z values, unless ⁠Molecule Name⁠ uniquely identifies the features (refer to the transition_id_columns argument below).

The following supported columns from Skyline can be imported:

*Requirements for these columns are described in transition_id_columns.

To export results from Skyline, use the 'Molecule Transition Results' format and include ⁠Replicate Name⁠, ⁠Molecule Name⁠, and either ⁠Precursor Mz⁠/⁠Product Mz⁠ or ⁠Precursor Name⁠/⁠Product Name⁠ columns. At least one feature variable, such as Area or RT, must also be exported.

Value

A MRMhubExperiment object containing the imported data.

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

mexp <- MRMhubExperiment()
file_path <- system.file("extdata", "Skyline_MoleculeTransitionResults.csv", package = "mrmhub")
mexp <- import_data_skyline(
  data = mexp,
  path = file_path,
  transition_id_columns = "mz",
  import_metadata = TRUE
)
print(mexp)

Description

Imports analysis metadata (annotation) from a preloaded data frame or tibble via the data argument, or from data from a file (CSV or Excel) via the path argument. The analysis metadata must contain following columns: analysis_id and qc_type. Additional analysis metadata columns are described under details below.

Usage

import_metadata_analyses(
  data = NULL,
  table = NULL,
  path = NULL,
  sheet = NULL,
  ignore_warnings = FALSE,
  excl_unmatched_analyses = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

mexp <- MRMhubExperiment()
file_path = system.file("extdata", "MHQuant_demo.csv", package = "mrmhub")
mexp <- import_data_masshunter(
  data = mexp,
  path = file_path,
  import_metadata = FALSE)

meta_path = system.file("extdata", "MHQuant_demo_metadata_analyses.csv", package = "mrmhub")

mexp <- import_metadata_analyses(
  data = mexp,
  path = meta_path,
  excl_unmatched_analyses = TRUE)

print(mexp)

Description

Imports feature metadata (annotation) from a preloaded data frame or tibble via the data argument, or from data from a file (CSV or Excel) via the path argument. The feature metadata must contain following column: feature_id. Additional feature metadata columns are described under details below.

Usage

import_metadata_features(
  data = NULL,
  table = NULL,
  path = NULL,
  sheet = NULL,
  ignore_warnings = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Description

Retrieves available metadata from the imported analysis data and associates it with the provided MRMhubExperiment object.

Usage

import_metadata_from_data(data = NULL, qc_type_column_name = "qc_type")

Arguments

Value

An updated MRMhubExperiment object

Description

Imports ISTD metadata (annotation) from a preloaded data frame or tibble via the data argument, or from data from a file (CSV or Excel) via the path argument. The ISTD metadata must contain following columns: istd_feature_id and one of istd_conc_nmolar or istd_conc_ngml.

Usage

import_metadata_istds(
  data = NULL,
  table = NULL,
  path = NULL,
  sheet = NULL,
  ignore_warnings = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Description

Imports metadata from a 'MRMhub Metadata Organizer' file (.xlsx) file and associates it with analysis data.

Usage

import_metadata_msorganiser(
  data = NULL,
  path,
  ignore_warnings = FALSE,
  excl_unmatched_analyses = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Examples

mexp <- MRMhubExperiment()

mexp <- import_data_mrmhub(
  data = mexp,
  path = system.file("extdata", "MRMhub_demo.tsv", package = "mrmhub"),
  import_metadata = TRUE)

mexp <- import_metadata_msorganiser(
 data = mexp,
 path = system.file("extdata", "Example_Metadata_1.xlsx", package = "mrmhub"),
 excl_unmatched_analyses = FALSE,
 ignore_warnings = TRUE)

print(mexp)

Description

Imports calibration curve metadata (annotation) from a preloaded data frame or tibble via the data argument, or from data from a file (CSV or Excel) via the path argument. The calibration curve metadata must contain following columns: sample_id, analyte_id, concentration, and concentration_unit.

Usage

import_metadata_qcconcentrations(
  data = NULL,
  table = NULL,
  path = NULL,
  sheet = NULL,
  ignore_warnings = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Description

Imports response curve metadata (annotation) from a preloaded data frame or tibble via the data argument, or from data from a file (CSV or Excel) via the path argument. The response curve metadata must contain following columns: analysis_id, curve_id, analyzed_amount and analyzed_amount_unit.

Usage

import_metadata_responsecurves(
  data = NULL,
  table = NULL,
  path = NULL,
  sheet = NULL,
  ignore_warnings = FALSE
)

Arguments

Value

An updated MRMhubExperiment object

Identifier normalization

All imported identifiers are whitespace-normalized on import: leading and trailing spaces are removed and internal runs of whitespace are collapsed to a single space (for example "QC 01" becomes "QC 01"). Raw-data file extensions (.mzML, .d, .raw, .wiff, .wiff2, .lcd, .chrom, case-insensitive) are stripped from analysis_id.

The same normalization is applied to both the data and the metadata, which is what lets an analysis_id typed into metadata match the one derived from a data-file name instead of silently failing to join. A consequence is that two identifiers differing only by whitespace collapse to one and are then reported as duplicates.

Description

The labels a feature's mrm_pattern may take, optionally for one product-ion origin. Single source of truth shared by metadata validation and the Excel template dropdown (so they cannot drift).

Usage

licar_pattern_choices(origin = NULL)

Arguments

Value

A character vector of labels.

Description

This demo dataset is included for use in function examples and user testing. It is a small, preprocessed subset of a plasma lipidomics dataset, containing raw peak areas and analytical metadata. The original dataset was published in Tan et al., ATVB, 2022.

Usage

lipidomics_dataset

Format

A MRMhubExperiment object with the following data and metadata:

dataset_orig

A tibble containing the original peak data.

dataset

A tibble with annotated lipidomics data.

annot_analyses

Analysis-level metadata

annot_features

Feature-level metadata

annot_batches

Batch annotations.

annot_istds

ISTD concentrations

annot_responsecurves

Response curves metadata

Description

mrmhub's console feedback is coloured with cli. In an interactive session this works out of the box, but in a non-interactive render (Quarto or R Markdown) cli suppresses colour by default, and its alerts travel on the message stream, which knitr does not colour-convert. Call this once in a setup chunk to (1) advertise colour support to cli via cli.num_colors / crayon.enabled and (2), when rendering to HTML, register a knitr message hook that converts the emitted ANSI sequences to coloured HTML using the fansi package. For PDF and Word the same hook strips the ANSI so messages stay clean plain text. Advertising colour also tints ordinary output (e.g. tibble prints) on the output stream, which knitr leaves untouched, so an output hook strips that ANSI to keep printed data plain text; only the message-stream alerts colour.

Usage

mrmhub_enable_cli_color(num_colors = 256L)

Arguments

Value

Invisibly, the previous values of the options it changed (as returned by options()), so the caller can restore them.

Examples

## Not run: 
# In a Quarto / R Markdown setup chunk:
mrmhub_enable_cli_color()

## End(Not run)

Description

Returns the currently set ⁠mrmhub.*⁠ plot-appearance options as a named list. Options that are not set are omitted.

Usage

mrmhub_get_plot_defaults()

Value

A named list of the active plot defaults (empty if none are set).

See Also

mrmhub_set_plot_defaults()

Examples

mrmhub_set_plot_defaults(font_base_size = 8)
mrmhub_get_plot_defaults()
mrmhub_reset_plot_defaults()

Description

Removes all ⁠mrmhub.*⁠ plot-appearance options set by mrmhub_set_plot_defaults(), restoring the built-in per-function defaults.

Usage

mrmhub_reset_plot_defaults()

Value

Invisibly, the previous option values (as returned by options()).

See Also

mrmhub_set_plot_defaults()

Examples

mrmhub_set_plot_defaults(font_base_size = 8)
mrmhub_reset_plot_defaults()

Description

Sets session-wide defaults for the shared appearance arguments of the ⁠plot_*()⁠ functions, so common choices such as a smaller base font or point size can be made once at the top of a notebook instead of on every call. Defaults are stored as ⁠mrmhub.*⁠ options. The precedence for every argument is: a value passed explicitly to a plotting function wins, then the global default set here, then the function's built-in default (including automatic cols_page-based sizing on faceted plots).

Usage

mrmhub_set_plot_defaults(
  font_base_size = NULL,
  point_size = NULL,
  legend_position = NULL,
  legend_size = NULL,
  show_legend_title = NULL,
  strip_bg_color = NULL,
  units = NULL,
  dpi = NULL
)

Arguments

Details

Only the arguments you supply are changed; the rest are left untouched. Pass NULL (the default) to leave a setting as it is, and use mrmhub_reset_plot_defaults() to clear them all. The previous option values are returned invisibly, so a set can be undone with options(old) or scoped to a block with withr::local_options().

Value

Invisibly, a named list of the option values as they were before this call (as returned by options()).

See Also

mrmhub_reset_plot_defaults(), mrmhub_get_plot_defaults(), save_plot() and the vignette("manual-08-visualization") article.

Examples

old <- mrmhub_set_plot_defaults(font_base_size = 8, point_size = 0.8)
# ... make plots with the smaller defaults ...
options(old) # restore

Description

Prints the full status dashboard for a MRMhubExperiment: sample and feature composition, which metadata tables are populated, the state of each processing step, and any manually excluded analyses or features. Printing the object directly gives the compact one-screen overview instead.

Usage

mrmhub_status(object)

Arguments

Value

The object, invisibly.

Examples

mrmhub_status(MRMhubExperiment(title = "Test", analysis_type = "lipidomics"))

Description

Constructor for the MRMhubExperiment object

Usage

MRMhubExperiment(title = "", analysis_type = NA_character_)

Arguments

Value

MRMhubExperiment object

Description

The MRMhubExperiment object is the core data structure utilized within the MRMhub workflow, encapsulating all relevant experimental data and metadata. It also includes processing results, details of the applied processing steps, and the current status of the data.

Slots

title

Title of the experiment

analysis_type

Analysis type, one of "lipidomics", "metabolomics", "externalcalib", "others"

feature_intensity_var

Feature variable used as default for calculations

conc_analyte_unit

Unit of the analyte amount underlying feature_conc, set when the data are quantitated. "pmol" or "ng" for ISTD quantitation (see quantify_by_istd()), or the calibrant concentration unit (e.g. "nmol/L") for calibration quantitation. Divided by sample_amount_unit by get_conc_unit() to name the unit of feature_conc. NA when not quantitated.

dataset_orig

Original imported analysis data.

dataset

Processed analysis data.

dataset_filtered

QC-filtered processed analysis data.

annot_analyses

Annotation of analyses/runs

annot_features

Annotation of measured features.

annot_istds

Annotation of Internal Standard concs.

annot_responsecurves

Annotation of response curves (RQC).

annot_qcconcentrations

Annotation of calibration curves.

annot_studysamples

Annotation of study samples.

annot_batches

Annotation of batches.

annot_interferences

Interference relationships (feature_id, interference_feature_id, interference_contribution, overlap_type, source) feeding the correction engine; derived (auto) and/or manual.

metrics_qc

QC information for each measured feature

metrics_calibration

Calibration metrics calculated from external calibration curves for each measured feature

status_processing

Status within the data processing workflow

is_istd_normalized

Flag if data has been ISTD normalized

is_quantitated

Flag if data has been quantitated using ISTD and sample amount

is_filtered

Flag if data has been filtered based on QC parameters

is_isotope_corr

Flag if one or more features have been isotope corrected

analyses_excluded

Analyses excluded from processing, plots and reporting, unless explicitly requested

features_excluded

Features excluded from processing, plots and reporting, unless explicitly requested

var_drift_corrected

List indicating which variables are drift corrected

var_batch_corrected

List indicating which variables are batch corrected

Description

Normalize feature intensities by dividing them by the intensities of the corresponding internal standards (ISTDs). Each feature must have a defined internal standard (ISTD) in the feature metadata.

Usage

normalize_by_istd(data = NULL, ignore_missing_annotation = FALSE)

Arguments

Value

A MRMhubExperiment object with normalized feature intensities

Description

This function retrieves lipid class, species and transition names from the feature_id column and adds them as columns to the dataset.

Usage

parse_lipid_feature_names(
  tbl,
  use_as_feature_class = "lipid_class_lcb",
  add_transition_names = FALSE,
  add_chain_composition = TRUE
)

Arguments

Value

The input data frame with added lipid class, species and transition name columns.

Description

Reads and parses one Agilent MassHunter Quant CSV result file

Usage

parse_masshunter_csv(
  path,
  expand_qualifier_names = TRUE,
  silent = FALSE,
  conc_column = "conc_final"
)

Arguments

Value

A tibble with the parse results in the long format

Examples

file_path = system.file("extdata", "MHQuant_demo.csv", package = "mrmhub")

tbl <- parse_masshunter_csv(
  path = file_path,
  expand_qualifier_names = TRUE)

head(tbl)

Description

Parses MRMhub peak integration results into a tibble

Usage

parse_mrmhub_result(path, silent = FALSE)

Arguments

Value

A tibble in the long format

Examples

file_path = system.file("extdata", "MRMhub_demo.tsv", package = "mrmhub")

tbl <- parse_mrmhub_result(path = file_path)

head(tbl)

Description

Parses a CSV table with analysis/samples and feature pairs in rows, columns representing the feature variables.

Usage

parse_plain_long_csv(
  path,
  na_strings = "NA",
  silent = FALSE,
  column_mapping = NULL,
  warn_unrecognized_columns = TRUE,
  ...
)

Arguments

Value

A tibble in the long format

Examples

file_path = system.file("extdata", "plain_long_dataset.csv", package = "mrmhub")

tbl <- parse_plain_long_csv(path = file_path)

head(tbl)

Description

Parses a CSV table with analysis/samples in rows, features values in columns.

Usage

parse_plain_wide_csv(
  path,
  variable_name,
  analysis_id_col = NA,
  import_metadata = TRUE,
  first_feature_column = NA,
  na_strings = "NA"
)