fix metrics.md conflicts

README.md

@@ -9,9 +9,9 @@ The Human Proteome Organisation (HUPO) Proteomics Standards Initiative (PSI) def
 The current projects of the QC working group are:
 
 - mzQC: A standard file format for the exchange, transmission, and archiving of quality metrics derived from biological mass spectrometry.
-- QC CV: A controlled vocabulary to represent terms for the definition of quality metrics and related supporting values.
+- QC CV: Integration of controlled vocabulary terms into [PSI-MS CV](https://github.com/HUPO-PSI/psi-ms-CV/) to represent quality metrics and related supporting values.
+- Reference Implementations: The [MS-Quality-hub](https://github.com/MS-Quality-hub/) GitHub organization hosts implementations for mzQC in Python, R and Java.
 
---------------------------------
 ## Our official website is here:
 <div align="center">
    <h1><a href="https://hupo-psi.github.io/mzQC/"><b>hupo-psi.github.io/mzQC/</b></a></h1>

docs/index.md

@@ -33,6 +33,7 @@ and analysts wanting a better insight to the data they analyse.
 
 * If you are familiar with JSON or have an understanding of PSI file formats, are however pressed for time, [mzQC at a glance](use-cases/at-a-glance/) will give you a brief overview of the essentials.
 
+* A in a nutshell exlanation is [here](mzQC-in-a-nutshell/)
 * Find out more about the format in general [here](mzQC-intro/)!
 
 ### Specification Document

docs/pages/cv/howto_create_cv_terms.md

@@ -1,3 +1,8 @@
+---
+layout: page
+title: "Metrics - create"
+permalink: /metrics/create
+---
 # CV Term Creation Guide
 
 New CV terms have to be requested via the [mzQC GitHub issue tracker](https://github.com/HUPO-PSI/mzQC/issues).
@@ -234,12 +239,6 @@ is_a: QC:4000107 ! Column type
 property_value: has_units UO:0000191 ! fraction
 ```
 
-**Matrix:**
-
-```
-TODO
-```
-
 ## New CV terms 
 New CV terms have to be requested via the [mzQC GitHub issue tracker](https://github.com/HUPO-PSI/psi-ms-CV/issues/new?assignees=&labels=&template=new_qc_term.yml). 
 Upon creating a new issue, you should select the "Request for new CV term" option. 
@@ -261,8 +260,4 @@ matrix?
 whether the metric depends on spectrum, peptide, protein, or metabolite 
 identifications; or to describe the metric context.
 
-More information on how to request CV terms and their translation to elements in
-an mzQC file is available in the following CV guides:
-
-- [CV Term Creation Guide](cv/howto_create_cv_terms.md)
-- [CV Term Usage Guide](cv/howto_use_cv_terms.md)
+More information on how use CV terms and their translation to elements in an mzQC file is available in the following CV guide: [CV Term Usage Guide](cv/howto_use_cv_terms.md)

docs/pages/cv/howto_use_cv_terms.md

@@ -1,25 +1,29 @@
+---
+layout: page
+title: "Metrics - use"
+permalink: /metrics/use
+---
 # CV Term Usage Guide
 
-The translation from CV terms to elements in an mzQC file depends on the term's
-value type and is pretty straightforward.
+The translation from CV terms to elements in an mzQC file depends on the term's value type and is pretty straightforward.
+Following, the different value types uses are exemplified .
 
 ## Single Value
 
 To report the number of MS1 scans in a peak file:
 
 ```
 [Term]
-id: QC:4000059
-name: Number of MS1 spectra
-def: "The number of MS1 events in the run." [PSI:QC]
-is_a: QC:4000003 ! single value
-is_a: QC:4000010 ! ID free
-is_a: QC:4000023 ! MS1 metric
-comment: A lower number of MS1 spectra acquired during one sample run compared to similar runs can indicate mismatched instrument settings or issues with the instrumentation or issues with sample amounts.
-relationship: has_relation MS:1000579 ! MS1 spectrum
-relationship: has_relation QC:4000013 ! QC metric relation: single run
-property_value: has_units UO:0000189 ! count unit
-synonym: "MS1-Count" EXACT []
+id: MS:4000059
+name: number of MS1 spectra
+def: "The number of MS1 events in the run." [PSI:MS]
+synonym: "MS1-Count" EXACT [PMID:24494671]
+is_a: MS:4000003 ! single value
+relationship: has_metric_category MS:4000009 ! ID free metric
+relationship: has_metric_category MS:4000012 ! single run based metric
+relationship: has_metric_category MS:4000021 ! MS1 metric
+relationship: has_value_type xsd:int ! The allowed value-type for this CV term
+relationship: has_units UO:0000189 ! count unit
 ```
 
 A corresponding `qualityMetric` object in an mzQC file:
@@ -42,17 +46,19 @@ To report the number of MS2 scans per quantile:
 
 ```
 [Term]
-id: QC:4000062
-name: MS2 density per quantile
-def: "The first to n-th quantile of MS2 scan peak counts." [PSI:QC]
-is_a: QC:4000004 ! n-tuple
-is_a: QC:4000010 ! ID free
-is_a: QC:4000024 ! MS2 metric
-relationship: has_relation MS:1000035 ! peak picking
-relationship: has_relation QC:4000013 ! QC metric relation: single run
-synonym: "MS2-Density-Q1" RELATED []
-synonym: "MS2-Density-Q2" RELATED []
-synonym: "MS2-Density-Q3" RELATED []
+id: MS:4000062
+name: MS2 density quantiles
+def: "The first to n-th quantile of MS2 peak density (scan peak counts). A value triplet represents the original QuaMeter metrics, the quartiles of MS2 density. The number of values in the tuple implies the quantile mode." [PSI:MS]
+synonym: "MS2-Density-Q1" RELATED [PMID:24494671]
+synonym: "MS2-Density-Q2" RELATED [PMID:24494671]
+synonym: "MS2-Density-Q3" RELATED [PMID:24494671]
+is_a: MS:4000004 ! n-tuple
+relationship: has_metric_category MS:4000009 ! ID free metric
+relationship: has_metric_category MS:4000012 ! single run based metric
+relationship: has_metric_category MS:4000022 ! MS2 metric
+relationship: has_value_type xsd:int ! The allowed value-type for this CV term
+relationship: has_value_concept NCIT:C45781 ! Density
+relationship: has_units UO:0000189 ! count unit
 ```
 
 A corresponding `qualityMetric` object in an mzQC file:
@@ -61,11 +67,7 @@ A corresponding `qualityMetric` object in an mzQC file:
 {
     "accession": "MS:4000062",
     "name": "MS2 density quantiles",
-    "value": [
-        162,
-        250,
-        404
-    ],
+    "value": [162, 250, 404],
     "unit": {
         "accession": "UO:0000189",
         "name": "count unit"
@@ -79,62 +81,51 @@ To report the MS/MS precursor charge states:
 
 ```
 [Term]
-id: QC:4000063
+id: MS:4000063
 name: MS2 known precursor charges fractions
-def: "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:QC]
-is_a: QC:4000006 ! table 
-is_a: QC:4000010 ! ID free
-is_a: QC:4000024 ! MS2 metric
-is_a: QC:4000025 ! ion source metric
-relationship: has_relation MS:1000041 ! charge state
-relationship: has_relation QC:4000013 ! QC metric relation: single run
-property_value: has_column: QC:4000238 ! Charge state
-property_value: has_column: QC:4000239 ! Fraction
-synonym: "MS2-PrecZ-1" RELATED []
-synonym: "MS2-PrecZ-2" RELATED []
-synonym: "MS2-PrecZ-3" RELATED []
-synonym: "MS2-PrecZ-4" RELATED []
-synonym: "MS2-PrecZ-5" RELATED []
-synonym: "MS2-PrecZ-more" RELATED []
+def: "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]
+synonym: "MS2-PrecZ-1" NARROW [PMID:24494671]
+synonym: "MS2-PrecZ-2" NARROW [PMID:24494671]
+synonym: "MS2-PrecZ-3" NARROW [PMID:24494671]
+synonym: "MS2-PrecZ-4" NARROW [PMID:24494671]
+synonym: "MS2-PrecZ-5" NARROW [PMID:24494671]
+synonym: "MS2-PrecZ-more" NARROW [PMID:24494671]
+synonym: "IS-3A"  RELATED [PMID:19837981]
+synonym: "IS-3B"  RELATED [PMID:19837981]
+synonym: "IS-3C"  RELATED [PMID:19837981]
+comment: the MS2-PrecZ metrics can be directly read from the table respective table rows, the ratios of IS-3 metrics must be derived from the respective table rows, IS-3A as ratio of +1 over +2, IS-3B as ratio of +3 over +2, IS-3C as +4 over +2.
+is_a: MS:4000005 ! table
+relationship: has_metric_category MS:4000009 ! ID free metric
+relationship: has_metric_category MS:4000012 ! single run based metric
+relationship: has_metric_category MS:4000020 ! ion source metric
+relationship: has_metric_category MS:4000022 ! MS2 metric
+relationship: has_column MS:1000041 ! charge state
+relationship: has_column UO:0000191 ! fraction
 
 [Term]
-id: QC:4000238
-name: Charge state
-def: "The column contains charge states." [PSI:QC]
-is_a: QC:4000107 ! Column type
-property_value: has_units MS:1000041 ! charge state
-
-[Term]
-id: QC:4000239
-name: Fraction
-def: "The column contains fraction values as decimals." [PSI:QC]
-is_a: QC:4000107 ! Column type
-property_value: has_units UO:0000191 ! fraction
+id: MS:1000041
+name: charge state
+def: "Number of net charges, positive or negative, on an ion." [PSI:MS]
+synonym: "z" EXACT []
+is_a: MS:1000455 ! ion selection attribute
+is_a: MS:1000507 ! ion property
+relationship: has_value_type xsd:int ! The allowed value-type for this CV term
+
+[RDF extract]
+id: UO:0000191
+name: fraction
+def: "A dimensionless ratio unit which relates the part (the numerator) to the whole (the denominator). [Wikipedia:Wikipedia]"
 ```
 
 A corresponding `qualityMetric` object in an mzQC file:
 
 ```
 {
-    "accession": "QC:4000063",
+    "accession": "MS:4000063",
     "name": "MS2 known precursor charges fractions",
     "value": {
-        "Charge state": [
-            "1",
-            "2",
-            "3",
-            "4",
-            "5",
-            "6"
-        ],
-        "Fraction": [
-            0.000,
-            0.683,
-            0.305,
-            0.008,
-            0.002,
-            0.002
-        ]
+        "Charge state": ["1","2","3","4","5","6"],
+        "Fraction": [0.000,0.683,0.305,0.008,0.002,0.002]
     },
     "unit": [
         {
@@ -148,9 +139,4 @@ A corresponding `qualityMetric` object in an mzQC file:
     ]
 }
 ```
-
-## Matrix
-
-```
-TODO
-```
+The units of a table instance are implicitly assumed through their respective columns' definition and if available as unit terms, documented in the unit array of the instance for clarity.

docs/pages/metrics.md

@@ -4,6 +4,11 @@ title: Metrics
 permalink: /metrics/
 ---
 
-{% include_relative cv/howto_create_cv_terms.md %}
+The mzQC format owes much of it's _simplicity_ **and** _flexibility_ to the use of controlled vocabulary (CV) terms to define and instantiate quality metric records. 
+You can find out more on how to use and define your own CV terms below.
 
 {% include_relative cv/howto_use_cv_terms.md %} 
+
+{% include_relative cv/howto_create_cv_terms.md %}
+
+

docs/pages/mzqc-in-a-nutshell.md

@@ -0,0 +1,13 @@
+---
+layout: page
+title: "mzQC in a nutshell"
+permalink: mzQC-in-a-nutshell/
+---
+
+![image tooltip here](/pages/figures/mzQC-in-a-nutshell.pptx.jpg)
+
+>(You can download the slide for reuse from [here](/pages/figures/mzQC-in-a-nutshell.pptx)
+)
+
+Here is another summary slide:
+![mzQC-EBI-summary](/pages/figures/mzQC-EBI-summary.pptx.jpg)