MSdev untargeted workflow

This vignette mirrors the current stock untargeted path used in project records: raw → xcms → spectra → annotation → stats/export → DEP figures per sample.type.

MSdev() / MSdev_load()
    → MSdev_msConvert
    → MSdev_checkSampleInfo
    → MSdev_set_param (CentWave + PeakDensity)
    → MSdev_xcmsProcessing
    → MSdev_extract_Spectra
    → MSdev_annotation (CompoundDb)
    → MSdev_get_Stat → MSdev_export → MSdev_save
    → DEP PCA / TIC / volcano / heatmap by sample.type

---

1. Create or resume a project

New project from a raw-data directory:

library(MSdev)

object <- MSdev("path/to/rawDataDir")

Resume a saved object (skip create + earlier steps already done):

object <- MSdev_load("path/to/MSdev_YYYY_MM_DD.Rdata")

In practice use one entry point: create for a fresh study, load when continuing.

---

2. Convert and check sample info

object <- MSdev_msConvert(object)
object <- MSdev_checkSampleInfo(object)

• MSdev_msConvert() converts vendor raw files when needed; if inputs are already .mzML / .mzXML, conversion is skipped.
• MSdev_checkSampleInfo() validates sampleInfo (groups, polarity, msLevels, xcmsProcessing, etc.). Fix metadata interactively if prompted.

---

3. Set xcms parameters

Tune peak picking and correspondence before processing (example values from a recent lipidomics run):

object <- MSdev_set_param(
  object,
  findChromPeaks = xcms::CentWaveParam(
    ppm = 25,
    prefilter = c(3, 100),
    peakwidth = c(10, 60),
    snthresh = 10,
    fitgauss = TRUE
  ),
  groupChromPeaks = xcms::PeakDensityParam(
    sampleGroups = "A",
    minFraction = 0.5,
    binSize = 0.005,
    bw = 20,
    ppm = 25
  )
)

Adjust ppm, peakwidth, bw, and minFraction to the instrument and chromatography. sampleGroups in PeakDensityParam is a placeholder here; MSdev_xcmsProcessing() uses the project sample groups when it runs.

---

4. Feature detection and spectra

object <- MSdev_xcmsProcessing(object)
object <- MSdev_extract_Spectra(object)

• MSdev_xcmsProcessing() runs peak picking / grouping (and related xcms steps) into polarity MS1 containers (PositiveMS1 / NegativeMS1).
• MSdev_extract_Spectra() loads MS1/MS2 into @spectra, assigns sp_id, and links MS2 to features (MSdev_assign_MS2).

---

5. Annotation against CompoundDb

Example: LipidBlast SQLite with common lipid adducts and expanded adduct matching:

object <- MSdev_annotation(
  object,
  expand_adduct = TRUE,
  cpdb_path = "path/to/CompoundDB/Lipidblast.sqlite",
  selected_adduct = c(
    "[M]+", "[M+NH4]+", "[M+H]+", "[M+Na]+",
    "[M-H]-", "[M+HCOO]-", "[M+CH3COO]-"
  )
)

Point cpdb_path at any CompoundDb SQLite used for the study. Change selected_adduct for metabolomics vs lipidomics ion modes.

---

6. Stats table, export, and save

object <- MSdev_get_Stat(object, score_thresh = 0.3)
MSdev_export(object)
MSdev_save(object)

• score_thresh filters annotation scores when building the stats / metabolite tables.
• MSdev_export() writes tabular outputs under the project directory.
• MSdev_save() serializes the MSdev object for later MSdev_load().

---

7. Figures and differential analysis

Downstream plots use a SummarizedExperiment from annotated metabolites and DEP helpers. Outputs go under projectDir/Statistic/.

library(patchwork)

proj.dir <- object@projectInfo$projectDir
data.se <- get_MSdev_DEP_se(object, from = "metabolite", QC_RSD = Inf)

7.1 PCA and TIC overview

p.pca <- DEP_plot_PCA(data.se)
export_graph2pdf(
  p.pca,
  file.path(proj.dir, "Statistic", "Figures.pdf"),
  width = 3, height = 3
)

p1 <- plot_xcms_TIC(object@xcmsData$PositiveMS1) +
  labs(title = "Positive TIC")
p2 <- plot_xcms_TIC(object@xcmsData$NegativeMS1) +
  labs(title = "Negative TIC")
p <- p1 + p2 + plot_layout(ncol = 1)
export_graph2pdf(
  p,
  file.path(proj.dir, "Statistic", "Figures.pdf"),
  width = 10, height = 8, append = TRUE
)

7.2 Differential analysis by sample.type

For each non-Blank / non-QC sample.type, write:

• Statistic/<type>/Figures.pdf — volcano (unadjusted then adjusted) + heatmap
• Statistic/<type>/diff.metabolites.xlsx — contrast tables

sample.types <- unique(as.character(data.se$sample.type))
sample.types <- sample.types[!is.na(sample.types) & nzchar(sample.types)] |>
  setdiff(c("Blank", "QC"))

for (stype in sample.types) {
  out.dir <- file.path(proj.dir, "Statistic", stype)
  dir.create(out.dir, recursive = TRUE, showWarnings = FALSE)
  fig.pdf <- file.path(out.dir, "Figures.pdf")
  diff.xlsx <- file.path(out.dir, "diff.metabolites.xlsx")

  data.se1 <- data.se[, data.se$sample.type == stype]
  data.se.p <- DEP_preprocess(data.se1)

  # volcano without p-adjustment
  data.diff <- DEP_test_diff(data.se.p, type = "all")
  data.diff <- DEP_add_rejections(data.diff, p.adjust = FALSE)
  p.diff <- ggplot_sum_patchwork(DEP_plot_volcano(data.diff, "all"))
  export_graph2pdf(p.diff, fig.pdf, width = 10, height = 10)

  # volcano with p-adjustment + export table
  data.diff <- DEP_test_diff(data.se.p)
  data.diff <- DEP_add_rejections(data.diff, p.adjust = TRUE)
  p.diff <- ggplot_sum_patchwork(DEP_plot_volcano(data.diff, "all"))
  export_graph2pdf(p.diff, fig.pdf, width = 10, height = 10, append = TRUE)
  table.diff <- DEP_get_diff_table(data.diff, contrast = "all", keep.all = TRUE)
  xlsx.write.list(table.diff, diff.xlsx)

  # significant features heatmap
  data.diff <- DEP_test_diff(data.se.p, type = "all")
  data.diff <- DEP_add_rejections(data.diff, p.adjust = FALSE)
  data.hm <- DEP_filter_significant(data.diff)
  hm <- DEP_plot_heatmap(data.hm)
  export_graph2pdf(hm, fig.pdf, width = 10, height = 20, append = TRUE)
}

Requires usable sample.type (and contrast design) in the DEP SummarizedExperiment column data. Skip or subset types as needed for exploratory runs (QC_RSD = Inf disables QC-RSD filtering in the example).

---

8. Optional next steps

Step	Function	When
Feature compounding (xcms-style)	MSdev_xcms_group_features()	After xcms, before or with annotation
Custom EIC grouping	MSdev_group_feature_EIC()	When you need stored EIC similarity matrices
Feature chromatograms	MSdev_get_feature_chrom()	Before custom EIC grouping / EIC reports

See also the articles on Spectra backends, chromatogram extraction, and EicSimilarityParam feature grouping.