add guidelines section to the docs

README.md

@@ -19,6 +19,7 @@ the developers of spectral library search tools and resources.
   - [Introduction](#introduction)
   - [Development](#development)
   - [Reference implementation](#reference-implementation)
+  - [Guidelines](#guidelines)
   - [Contributing](#contributing)
 
 ---
@@ -69,6 +70,9 @@ A reference implementation of the mzSpecLib format is available in the form of a
 Check out the [mzspeclib-py](https://github.com/HUPO-PSI/mzspeclib-py) repository or the
 [Python package documentation](https://mzspeclib.readthedocs.io/) for more information.
 
+## Guidelines
+
+The mzSpecLib format is flexible, but we have examples showing how to use it in certain ways in
 
 ## Contributing
 

docs/guidelines/index.rst

@@ -0,0 +1,8 @@
+Guidelines
+----------
+
+.. toctree::
+   :caption: Guidelines
+
+   mz_terms
+   mass_terms

docs/guidelines/mass_terms.csv

@@ -0,0 +1,4 @@
+Term,Intended Use
+``MS:1000224|molecular mass``,"Describes the neutral mass of the molecule being measured without the charge carriers"
+``MS:1003243|adduct ion mass``,"Describes the neutral mass of the molecule *plus* the mass of the charge carrier(s)"
+``MS:1001117|theoretical neutral mass``,"Describes the neutral mass of the molecule without the charge carriers calculated directly from the molecule identity"

docs/guidelines/mass_terms.rst

@@ -0,0 +1,11 @@
+Specifying Ion Mass
+-------------------
+
+.. csv-table:: Mass Controlled Vocabulary Terms
+   :file: mass_terms.csv
+   :widths: 30, 70
+   :header-rows: 1
+   :name: ion mass terms
+
+
+TODO

docs/guidelines/mz_terms.csv

@@ -0,0 +1,4 @@
+Term,Intended Use
+``MS:1000744|selected ion m/z``,"The selected precursor ion as reported by the instrument for isolation. Should be used for a `Spectrum`"
+``MS:|experimentally determined monoisotopic m/z``,"The monoisotopic peak of the selected ion as determined by the implementation. Usually used for a `Spectrum`, but for chimeric or ambiguous spectra may also be used in an `Interpretation` or `InterpretationMember`"
+``MS:1003053|theoretical monoisotopic m/z``,"The theoretical m/z for an ion calculated by the implementation. Should be used for an `Analyte`"

docs/guidelines/mz_terms.rst

@@ -0,0 +1,31 @@
+Specifying ion m/z
+------------------
+
+.. csv-table:: M/Z Controlled Vocabulary Terms
+   :file: mz_terms.csv
+   :widths: 30, 70
+   :header-rows: 1
+   :name: m/z terms
+
+Selected Ion M/Z
+================
+
+The :title-reference:`selected ion m/z` term is intended to be used in
+:title-reference:`mzSpecLib` in the same manner as in :title-reference:`mzML`.
+It reflects the assumption that this value is not refined by some other
+method that the implementation used, and carries with it the same uncertainty.
+Because it is not directly related to an `Analyte`'s identity, this attribute
+belongs to the `Spectrum` alone.
+
+Experimentally Determined Monoisotopic M/Z
+==========================================
+
+The :title-reference:`experimentally determined monoisotopic m/z` term
+was created for :title-reference:`mzSpecLib` to indicate that this m/z
+value was refined in some way by the implementation. This implies that
+the value is expected to be *correct* in-so-far as the implementation
+can tell.
+
+Because the determination might be done with information about
+an `Analyte`, this attribute could appear under either the `Spectrum` or
+the `Interpretation` or `InterpretationMember` sections.

docs/index.rst

@@ -10,3 +10,4 @@
    Home <self>
    specification/index
    contributing
+   guidelines/index