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