From ab907c439acfbe17720fb7edc5917389f353d076 Mon Sep 17 00:00:00 2001
From: Joshua Klein <mobiusklein@gmail.com>
Date: Sat, 2 Nov 2024 15:39:59 -0400
Subject: [PATCH] add guidelines section to the docs

---
 README.md                      |  4 ++++
 docs/guidelines/index.rst      |  8 ++++++++
 docs/guidelines/mass_terms.csv |  4 ++++
 docs/guidelines/mass_terms.rst | 11 +++++++++++
 docs/guidelines/mz_terms.csv   |  4 ++++
 docs/guidelines/mz_terms.rst   | 31 +++++++++++++++++++++++++++++++
 docs/index.rst                 |  1 +
 7 files changed, 63 insertions(+)
 create mode 100644 docs/guidelines/index.rst
 create mode 100644 docs/guidelines/mass_terms.csv
 create mode 100644 docs/guidelines/mass_terms.rst
 create mode 100644 docs/guidelines/mz_terms.csv
 create mode 100644 docs/guidelines/mz_terms.rst

diff --git a/README.md b/README.md
index f202ab0..9cc8811 100644
--- a/README.md
+++ b/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
 
diff --git a/docs/guidelines/index.rst b/docs/guidelines/index.rst
new file mode 100644
index 0000000..a17cd03
--- /dev/null
+++ b/docs/guidelines/index.rst
@@ -0,0 +1,8 @@
+Guidelines
+----------
+
+.. toctree::
+   :caption: Guidelines
+
+   mz_terms
+   mass_terms
\ No newline at end of file
diff --git a/docs/guidelines/mass_terms.csv b/docs/guidelines/mass_terms.csv
new file mode 100644
index 0000000..001a76c
--- /dev/null
+++ b/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"
\ No newline at end of file
diff --git a/docs/guidelines/mass_terms.rst b/docs/guidelines/mass_terms.rst
new file mode 100644
index 0000000..73f5956
--- /dev/null
+++ b/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
diff --git a/docs/guidelines/mz_terms.csv b/docs/guidelines/mz_terms.csv
new file mode 100644
index 0000000..69a738f
--- /dev/null
+++ b/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`"
\ No newline at end of file
diff --git a/docs/guidelines/mz_terms.rst b/docs/guidelines/mz_terms.rst
new file mode 100644
index 0000000..f2950ef
--- /dev/null
+++ b/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.
diff --git a/docs/index.rst b/docs/index.rst
index 2f481c6..1a07d6b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,3 +10,4 @@
    Home <self>
    specification/index
    contributing
+   guidelines/index