Create an 'MzQCqualityMetric' object from two inputs (id and value).

Usage

toQCMetric(
  id,
  value,
  on_violation = c("error", "warn"),
  allow_unknown_id = FALSE
)

Arguments

id: The CV accession
value: The data, as computed by some QC software in the required format.
on_violation: What to do when 'value' is not of the correct type (according to the given 'id')? Default: "error"; or "warn"
allow_unknown_id: Allows invalid accession, and also does not check the value type; if 'FALSE' this function errors

Value

An MzQCanalysisSoftware object

Details

The inputs are:

an ID of a QC metric, e.g. "MS:4000059" (number of MS1 spectra)
a value

The value must be in the correct format depending on the metric. The value type (see below) is checked (a warning/error is given if mismatching): The following requirements for values apply:

single value: R single value; the unit is deduced from the CVs 'has_units'
n-tuple: an R vector, e.g. using c(1,2,3), i.e. all values have the same type; the unit is deduced from the CVs 'has_units'
table: an R list(); all columns defined using CVs 'has_column' must be present (a warning/error is given otherwise)
matrix: an R matrix, i.e. all values have the same type; the unit is deduced from the CVs 'has_units'

Upon violation of the value type (e.g. data.frame instead of single value), an error or a warning is emitted (see @p on_violation):


   toQCMetric(id = "MS:4000059", value = data.frame(n = 1)) # errors: wrong value format

Examples

   ## single value
   toQCMetric(id = "MS:4000059", value = 13405) # number of MS1 spectra
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Reference class object of class "MzQCqualityMetric"
#> Field "accession":
#> [1] "MS:4000059"
#> Field "name":
#> [1] "number of MS1 spectra"
#> Field "description":
#> [1] "\"The number of MS1 events in the run.\" [PSI:MS]"
#> Field "value":
#> [1] 13405
#> Field "unit":
#> list()

   ## n-tuple
   toQCMetric(id = "MS:4000051", value = c(31.3, 35.99, 38.44)) # XIC-FWHM quantiles
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Reference class object of class "MzQCqualityMetric"
#> Field "accession":
#> [1] "MS:4000051"
#> Field "name":
#> [1] "XIC-FWHM quantiles"
#> Field "description":
#> [1] "\"The first to n-th quantile of peak widths for XICs. A metric's value triplet represents the related QuaMeter metrics of XIC-FWHM-Q1,Q2,Q3.\" [PSI:MS]"
#> Field "value":
#> [1] 31.30 35.99 38.44
#> Field "unit":
#> list()

   ## table
   toQCMetric(id = "MS:4000063",  # MS2 known precursor charges fractions
              value = list("MS:1000041" = 1:3,
                           "UO:0000191" = c(0.7, 0.6, 0.8)))
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Reference class object of class "MzQCqualityMetric"
#> Field "accession":
#> [1] "MS:4000063"
#> Field "name":
#> [1] "MS2 known precursor charges fractions"
#> Field "description":
#> [1] "\"The fraction of MS/MS precursors of the corresponding charge. The fractions [0,1] are given in the 'Fraction' column, corresponding charges in the 'Charge state' column. The highest charge state is to be interpreted as that charge state or higher.\" [PSI:MS]"
#> Field "value":
#> $`MS:1000041`
#> [1] 1 2 3
#> 
#> $`UO:0000191`
#> [1] 0.7 0.6 0.8
#> 
#> Field "unit":
#> list()

   ## test an invalid CV accession/id
   toQCMetric(id = "MS:0000", value = "ID_is_not_valid", allow_unknown_id = TRUE)
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Warning: Could not find id 'MS:0000' in CV list (length: 6806)
#> Reference class object of class "MzQCqualityMetric"
#> Field "accession":
#> [1] "MS:0000"
#> Field "name":
#> character(0)
#> Field "description":
#> character(0)
#> Field "value":
#> [1] "ID_is_not_valid"
#> Field "unit":
#> list()

   # \donttest{
   ## matrix (there is no example in the CV yet, so this cannot be tested)
   toQCMetric(id = "MS:400000?", value = matrix(1:12, nrow = 3, ncol = 4)) # ???
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Warning: Could not find id 'MS:400000?' in CV list (length: 6806)
#> Error in toQCMetric(id = "MS:400000?", value = matrix(1:12, nrow = 3,     ncol = 4)): The ID 'MS:400000?' is unknown in the current CV. Either fix the ID or use a more recent CV (see getCVSingleton()).
   # does not work since the 'id' is not derived from a valid value type
   toQCMetric(id = "MS:0000000", value = "ID_is_not_valid")
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Error: ... in toQCMetric: The ID 'MS:0000000' does not have a 'is_a' entry and thus cannot be derived from a matrix, n-tuple, etc.
#> Please use the correct CV term (possibly modifying the psi-ms cv file, see 'getCVSingleton()')
#> or obtain a template using `getQualityMetricTemplate()` if your CV term is unknown.

   # does not work, since the ID is unknown and 'allow_unknown_id' is FALSE by default
   toQCMetric(id = "MS:0000", value = "ID_is_not_valid")
#> Superclass Singleton has cloneable=FALSE, but subclass CV_ has cloneable=TRUE. A subclass cannot be cloneable when its superclass is not cloneable, so cloning will be disabled for CV_.
#> Warning: Could not find id 'MS:0000' in CV list (length: 6806)
#> Error in toQCMetric(id = "MS:0000", value = "ID_is_not_valid"): The ID 'MS:0000' is unknown in the current CV. Either fix the ID or use a more recent CV (see getCVSingleton()).
   # }