Basic R-Usage Guide for rMZQC

This vignette serves as a quickstart guide for R users to create and save an mzQC document.

Target Audience: R users

Read an mzQC file and extract some data

library(rmzqc)
data = readMZQC(system.file("./testdata/test.mzQC", package = "rmzqc", mustWork = TRUE))
cat("This file has ", length(data$runQualities), " runqualities\n")
## This file has  1  runqualities
cat("  - file: ", data$runQualities[[1]]$metadata$inputFiles[[1]]$name, "\n")
##   - file:  special.raw
cat("  - # of metrics: ", length(data$runQualities[[1]]$qualityMetrics), "\n")
##   - # of metrics:  1
cat("    - metric #1 name: ", data$runQualities[[1]]$qualityMetrics[[1]]$name, "\n")
##     - metric #1 name:  number of MS1 spectra
cat("    - metric #1 value: ", data$runQualities[[1]]$qualityMetrics[[1]]$value, "\n")
##     - metric #1 value:  13405

Hint: if you receive an error such as

Error in parse_con(txt, bigint_as_char) : 
lexical error: invalid char in json text.
cursor_int": [ NaN,NaN,NaN,NaN,825282.0,308263
(right here) ------^

when callingreadMZQC this indicates that the mzQC is not valid JSON, since NaN values should be quoted ("NaN") or replaced by null (unquoted), depending on context. In short: null may become an NA in R if part of an array, see https://github.com/jeroen/jsonlite/issues/70#issuecomment-431433773.

Create a minial mzQC document

library(rmzqc)
## we need a proper URI (i.e. no backslashes and a scheme, e.g. 'file:')
## otherwise writing will fail
raw_file = localFileToURI("c:\\data\\special.raw", FALSE)

file_format = getCVTemplate(accession = filenameToCV(raw_file))
## Downloading obo from 'https://github.com/HUPO-PSI/psi-ms-CV/releases/download/v4.1.147/psi-ms.obo' ...
ptxqc_software = toAnalysisSoftware(id = "MS:1003162", version = "1.0.13") ## you could use 'version = packageVersion("PTXQC")' to automate further
run1_qc = MzQCrunQuality$new(metadata = MzQCmetadata$new(label = raw_file,
                         inputFiles = list(MzQCinputFile$new(basename(raw_file),
                                                             raw_file,
                                                            file_format)),
                         analysisSoftware = list(ptxqc_software)),
                         qualityMetrics = list(toQCMetric(id = "MS:4000059", value = 13405) ## number of MS1 scans
                                               )
                         )

mzQC_document = MzQCmzQC$new(version = "1.0.0", 
                             creationDate = MzQCDateTime$new(), 
                             contactName = Sys.info()["user"], 
                             contactAddress = "test@user.info", 
                             description = "A minimal mzQC test document with bogus data",
                             runQualities = list(run1_qc),
                             setQualities = list(), 
                             controlledVocabularies = list(getCVInfo()))

## write it out
mzqc_filename = paste0(getwd(), "/test.mzQC")
writeMZQC(mzqc_filename, mzQC_document)
cat(mzqc_filename, "written to disk!\n")
## C:/Users/bielow/AppData/Local/Temp/Rtmp2fWCUu/Rbuild352c6c695f53/rmzqc/vignettes/test.mzQC written to disk!
## read it again
mq = readMZQC(mzqc_filename)

## print some basic stats
gettextf("This mzQC was created on %s and has %d quality metric(s) in total.", dQuote(mq$creationDate$datetime), length(mq$runQualities) + length(mq$setQualities))
## [1] "This mzQC was created on \"2024-04-15T00:00:00\" and has 1 quality metric(s) in total."