Author: Anton Klåvus, Vilhelm Suksi
Date: 2026-05-18

# Non-targeted metabolomics feature prioritization

Anton Klåvus, Vilhelm Suksi

#### 2026-05-18

# Contents

The statistics functionality in `notameStats` aims to identify interesting features across study groups. See the project example vignette in the notame package and notame website reference index for listing of functions. Similar functionality is available in several packages.

Unless otherwise stated, all functions return separate data frames or other objects with the results. These can be then added to the object feature data using `join_rowData(object, results)`. The reason for not adding these to the objects automatically is that most of the functions return excess information that is not always worth saving. We encourage you to choose which information is important to you.

# 1 Installation

To install `notameStats`, install `BiocManager` first, if it is not installed. Afterwards use the `install` function from `BiocManager` and load `notameStats`.

    if (!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("notameStats")

    library(notame)
    library(notameViz)
    library(notameStats)

    ppath <- tempdir()
    init_log(log_file = file.path(ppath, "log.txt"))

    data(hilic_neg_sample, package = "notame")
    data(toy_notame_set, package = "notame")

# 2 Univariate functions

## 2.1 Summary statistics and effect sizes

It is straightforward to provide summary statistics and effect sizes for all features:

    toy_notame_set <- mark_nas(toy_notame_set, value = 0)

    # Impute missing values, required especially for multivariate methods
    toy_notame_set <- notame::impute_rf(toy_notame_set)

    sum_stats <- summary_statistics(toy_notame_set, grouping_cols = "Group")
    toy_notame_set <- notame::join_rowData(toy_notame_set, sum_stats)

    d_results <- cohens_d(toy_notame_set, group = "Group")
    toy_notame_set <- notame::join_rowData(toy_notame_set, d_results)

    fc <- fold_change(toy_notame_set, group = "Group")
    toy_notame_set <- notame::join_rowData(toy_notame_set, fc)

    colnames(rowData(toy_notame_set))

    ##  [1] "Feature_ID"      "Split"           "Alignment"       "Average_Mz"
    ##  [5] "Average_Rt_min"  "Column"          "Ion_mode"        "Flag"
    ##  [9] "A_mean"          "A_sd"            "A_median"        "A_mad"
    ## [13] "A_min"           "A_Q25"           "A_Q75"           "A_max"
    ## [17] "B_mean"          "B_sd"            "B_median"        "B_mad"
    ## [21] "B_min"           "B_Q25"           "B_Q75"           "B_max"
    ## [25] "QC_mean"         "QC_sd"           "QC_median"       "QC_mad"
    ## [29] "QC_min"          "QC_Q25"          "QC_Q75"          "QC_max"
    ## [33] "B_vs_A_Cohen_d"  "QC_vs_A_Cohen_d" "QC_vs_B_Cohen_d" "B_vs_A_FC"
    ## [37] "QC_vs_A_FC"      "QC_vs_B_FC"

## 2.2 Univariate tests

These functions perform univariate hypothesis tests for each feature, report relevant statistics and correct the p-values using FDR correction. For features, where the model fails for some reason, all statistics are recorded as NA. NOTE setting `all_features = FALSE` does not prevent the tests on the flagged compounds, but only affects p-value correction, where flagged features are not included in the correction and thus do not have an FDR- corrected p-value. To prevent the testing of flagged features altogether, use `notame::drop_flagged` before the tests.

Most of the univariate statistical test functions in this package use the formula interface, where the formula is provided as a character, with one special condition: the word “Feature” will get replaced at each iteration by the corresponding feature name. So for example, when testing if any of the features predict the difference between study groups, the formula would be: “Group ~ Feature”. Or, when testing if group and time point affect metabolite levels, the formula could be “Feature ~ Group + Time + Group:Time”, with the last term being an interaction term (“Feature ~ Group * Time” is equivalent).

    toy_notame_set <- notame::flag_quality(toy_notame_set)
    toy_notame_set <- notame::drop_qcs(toy_notame_set)

    lm_results <- perform_lm(toy_notame_set,
      formula_char = "Feature ~ Group + Time")

Most of the functions allow you to pass extra arguments to the underlying functions performing the actual tests, so you can set custom contrasts etc.

Functions not using the formula interface include correlation tests between molecular features and/or sample information variable (`perform_correlation_tests()`) and area under curve computation (`perform_auc()`).

# 3 Multivariate analysis

## 3.1 MUVR

notame provides a wrapper for the MUVR analysis (Multivariate methods with Unbiased Variable selection in R, [shi2019variable] using the MUVR2 package. MUVR2 allows fitting both RF and PLS models with clever variable selection for both finding a minimal subset of features that achieves a good performance AND for finding all relevant features. There is also a set of useful visualizations in `MUVR2`.

    # nRep = 2 for quick example
    pls_model <- muvr_analysis(toy_notame_set,
      y = "Injection_order", nRep = 2, method = "PLS")

    ## Warning in (function (X, Y, ID, scale = TRUE, nRep = 5, nOuter = 6, nInner, :
    ## Missing ID -> Assume all unique (i.e. sample independence)

    ## Warning: executing %dopar% sequentially: no parallel backend registered

    class(pls_model)

    ## [1] "MUVR"       "Regression" "PLS"

## 3.2 Random forest

For random forest models, we also use the `randomForest` package. We also include a wrapper for getting feature importance.

    rf <- fit_rf(toy_notame_set, y = "Group")

    class(rf)

    ## [1] "randomForest"

    head(importance_rf(rf))

    ##                                          Feature_ID            A            B
    ## HILIC_neg_118_9111a4_1865 HILIC_neg_118_9111a4_1865 -0.008865318  0.008882540
    ## HILIC_pos_255_0094a7_9288 HILIC_pos_255_0094a7_9288 -0.048990937 -0.014950577
    ## RP_neg_139_4456a4_1251       RP_neg_139_4456a4_1251  0.012873304  0.006132756
    ##                           MeanDecreaseAccuracy MeanDecreaseGini
    ## HILIC_neg_118_9111a4_1865         -0.000511560         6.370065
    ## HILIC_pos_255_0094a7_9288         -0.028859344         6.350989
    ## RP_neg_139_4456a4_1251             0.009273948         6.746046

## 3.3 PLS(-DA)

There are also wrappers for PLS(-DA) functions from the mixOmics package.

    pls_res <- mixomics_pls(toy_notame_set, y = "Injection_order", ncomp = 3)

    class(pls_res)

    ## [1] "mixo_pls"

# 4 Session information

    ## R version 4.6.0 Patched (2026-05-01 r89994)
    ## Platform: aarch64-apple-darwin23
    ## Running under: macOS Tahoe 26.3.1
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] pROC_1.19.0.1               notameStats_1.3.0
    ##  [3] notameViz_1.3.0             notame_1.3.0
    ##  [5] SummarizedExperiment_1.43.0 Biobase_2.73.1
    ##  [7] GenomicRanges_1.65.0        Seqinfo_1.3.0
    ##  [9] IRanges_2.47.1              S4Vectors_0.51.2
    ## [11] BiocGenerics_0.59.2         generics_0.1.4
    ## [13] MatrixGenerics_1.25.0       matrixStats_1.5.0
    ## [15] ggplot2_4.0.3               BiocStyle_2.41.0
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] RColorBrewer_1.1-3   jsonlite_2.0.0       shape_1.4.6.1
    ##   [4] magrittr_2.0.5       farver_2.1.2         rmarkdown_2.31
    ##   [7] vctrs_0.7.3          htmltools_0.5.9      S4Arrays_1.13.0
    ##  [10] itertools_0.1-3      missForest_1.6.1     lambda.r_1.2.4
    ##  [13] SparseArray_1.13.2   caret_7.0-1          sass_0.4.10
    ##  [16] parallelly_1.47.0    bslib_0.11.0         plyr_1.8.9
    ##  [19] futile.options_1.0.1 lubridate_1.9.5      cachem_1.1.0
    ##  [22] igraph_2.3.1         lifecycle_1.0.5      iterators_1.0.14
    ##  [25] pkgconfig_2.0.3      Matrix_1.7-5         R6_2.6.1
    ##  [28] fastmap_1.2.0        rbibutils_2.4.1      future_1.70.0
    ##  [31] digest_0.6.39        rARPACK_0.11-0       RSpectra_0.16-2
    ##  [34] ellipse_0.5.0        randomForest_4.7-1.2 timechange_0.4.0
    ##  [37] abind_1.4-8          mgcv_1.9-4           compiler_4.6.0
    ##  [40] rngtools_1.5.2       withr_3.0.2          doParallel_1.0.17
    ##  [43] S7_0.2.2             BiocParallel_1.47.0  psych_2.6.5
    ##  [46] MASS_7.3-65          lava_1.9.1           DelayedArray_0.39.2
    ##  [49] corpcor_1.6.10       MUVR2_0.1.0          ModelMetrics_1.2.2.2
    ##  [52] tools_4.6.0          ranger_0.18.0        otel_0.2.0
    ##  [55] future.apply_1.20.2  nnet_7.3-20          glue_1.8.1
    ##  [58] nlme_3.1-169         grid_4.6.0           reshape2_1.4.5
    ##  [61] recipes_1.3.2        gtable_0.3.6         class_7.3-23
    ##  [64] tidyr_1.3.2          data.table_1.18.4    XVector_0.53.0
    ##  [67] ggrepel_0.9.8        foreach_1.5.2        pillar_1.11.1
    ##  [70] stringr_1.6.0        splines_4.6.0        dplyr_1.2.1
    ##  [73] lattice_0.22-9       survival_3.8-6       tidyselect_1.2.1
    ##  [76] mixOmics_6.37.0      knitr_1.51           gridExtra_2.3
    ##  [79] bookdown_0.46        futile.logger_1.4.9  xfun_0.57
    ##  [82] hardhat_1.4.3        timeDate_4052.112    stringi_1.8.7
    ##  [85] yaml_2.3.12          evaluate_1.0.5       codetools_0.2-20
    ##  [88] tibble_3.3.1         BiocManager_1.30.27  cli_3.6.6
    ##  [91] rpart_4.1.27         Rdpack_2.6.6         jquerylib_0.1.4
    ##  [94] dichromat_2.0-0.1    Rcpp_1.1.1-1.1       globals_0.19.1
    ##  [97] parallel_4.6.0       gower_1.0.2          doRNG_1.8.6.3
    ## [100] listenv_0.10.1       glmnet_5.0           viridisLite_0.4.3
    ## [103] ipred_0.9-15         scales_1.4.0         prodlim_2026.03.11
    ## [106] purrr_1.2.2          rlang_1.2.0          formatR_1.14
    ## [109] mnormt_2.1.2

# 5 References