Skip to content

Commit

Permalink
Merge pull request #73 from HUPO-PSI/metadata-docs
Browse files Browse the repository at this point in the history
Add sphinx documentation with Python API/CLI and metadata attributes
  • Loading branch information
edeutsch authored Sep 29, 2023
2 parents 6dcceb4 + 9ac0e0a commit af6685f
Show file tree
Hide file tree
Showing 22 changed files with 821 additions and 70 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/python-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest setuptools jsonschema
pip install flake8 pytest
- name: Lint with flake8
run: |
# stop the build if there are Python syntax errors or undefined names
Expand All @@ -27,7 +27,7 @@ jobs:
flake8 implementations/python --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
- name: Install python package
run: |
pip install --editable implementations/python
pip install --editable implementations/python[test]
- name: Test with pytest
env:
MZSPECLIB_PEAK_ANNOTATION_SCHEMA_LOCATION: "specification/peak-annotation-format/annotation-schema.json"
Expand Down
55 changes: 41 additions & 14 deletions .github/workflows/scripts/generate_metadata_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,48 @@
from collections import defaultdict
from functools import partial
from glob import glob
from typing import Dict, Iterable, Iterator, List

import psims
from jsonschema import validate
from tomark import Tomark
import psims


def rules_to_markdown(rules):
def _add_ols_links(lines: Iterable[str]) -> Iterator[str]:
"""Add links to OLS for all ontology accessions."""
add_links = partial(
re.sub,
pattern=r"MS:(\d{7})",
repl=r"[\g<0>](https://www.ebi.ac.uk/ols4/ontologies/ms/classes/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FMS_\g<1>)",
)
for line in lines:
yield add_links(string=line)


def rules_to_markdown(rules: Dict, level_descriptions: Dict) -> List[str]:
"""
Convert JSON metadata rules to markdown documentation.
Parameters
----------
rules
Metadata rules
level_descriptions
Title, description, and sub-groups for each metadata level
"""
cv = psims.load_psims() # load a fresh copy of the PSI-MS CV mapping

# Group rules by path and requirement level
rule_dict = defaultdict(lambda: defaultdict(list))
for rule in rules["rules"]:
rule_dict[rule["path"]][rule["requirement_level"]].append(rule)

lines = []
lines.append(f"# {rules['name'].upper()}\n")
# lines.append(f"## {rules['name'].upper()}\n")
for path, path_rules in rule_dict.items():
lines.append(f"## `{path}`\n")
lines.append(f"### {level_descriptions[path]['title']}\n")
lines.append(level_descriptions[path]["description"] + "\n")
for level, level_rules in path_rules.items():
# Combine all rule attributes into single list (#TODO: how to handle combination logic?)
rule_attrs = []
Expand Down Expand Up @@ -80,25 +105,26 @@ def rules_to_markdown(rules):

fields.append(field)

lines.append(f"### {level}\n")
lines.append(f"#### {level}\n")
# lines.append(f"Combination logic: `{rule['combination_logic']}`\n")
lines.append("\n")
lines.append(Tomark.table(fields))
lines.append("\n")

# Add link to OLS for all accessions
add_links = partial(
re.sub,
pattern=r"MS:(\d{7})",
repl=r"[\g<0>](https://www.ebi.ac.uk/ols4/ontologies/ms/classes/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FMS_\g<1>)",
)
lines = [add_links(string=line) for line in lines]
lines.append("\n")
lines = _add_ols_links(lines)

return lines


def main():
lines = []

with open(
LEVEL_DESCRIPTIONS_FILENAME, "rt", encoding="utf-8"
) as level_descriptions_file:
level_descriptions = json.load(level_descriptions_file)

for json_filename in glob(JSON_FILES_GLOB):
# Read JSON rules
with open(json_filename, "rt", encoding="utf-8") as json_file:
Expand All @@ -110,10 +136,10 @@ def main():
validate(rules, schema)

# Convert to markdown
lines.extend(rules_to_markdown(rules))
lines.extend(rules_to_markdown(rules, level_descriptions))

# Write to file
with open(MD_FILENAME, "wt") as md_file:
with open(MD_FILENAME, "wt", encoding="utf-8") as md_file:
for line in lines:
md_file.write(line)

Expand All @@ -124,6 +150,7 @@ def main():
)
# JSON_FILES_GLOB = "implementations/python/mzlib/validate/rules/*.json"
JSON_FILES_GLOB = "implementations/python/mzlib/validate/rules/all.json"
LEVEL_DESCRIPTIONS_FILENAME = ".github/workflows/scripts/level-information.json"
MD_FILENAME = "docs/metadata-rules.md"

main()
33 changes: 33 additions & 0 deletions .github/workflows/scripts/level-information.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
{
"/Library": {
"title": "Metadata specific to the library",
"description": "The following attributes describe an entire collection of spectra, the library itself. They should be listed under the tag <mzSpecLib 1.0> and nowhere else in the library.",
"subgroups": [
"Terms that define the library as a collection and how it was constructed",
"Terms that define attribute sets",
"Terms that define clusters of spectra"
]
},
"/Library/Spectrum": {
"title": "Metadata specific to library spectra",
"description": "The second level of metadata provides information specific to each library spectrum. The attributes SHOULD be organized in subcategories: those that pertain to the library spectrum and the origin of the spectrum, those that pertain to the spectrum itself, those that pertain to the interpretation of the spectrum, and those that pertain to the analyte(s) the spectrum is identified to. The following are attributes pertaining to the library spectrum and the origin of the spectrum, including the acquisition method and information about the precursor ion. They MUST be listed under <Spectrum=_>, or listed in library spectrum attribute sets.",
"subgroups": [
"Terms that identify the spectrum",
"Terms that describe how the spectrum is acquired, including the method and the context",
"Terms that describe how the spectrum itself, including steps of data processing leading to it",
"Terms that describe an aggregated spectrum (e.g. a consensus spectrum constructed from multiple replicates)",
"Terms that cross-reference other spectra in the same library or elsewhere",
"Terms that define the additional columns of the peak list"
]
},
"/Library/Spectrum/Interpretation": {
"title": "Metadata specific to the interpretation",
"description": "These attributes describe the details of the interpretation of the spectrum. They MUST be listed under <Interpretation=_>. Additional attributes can be children of PSM-level search engine specific statistics [MS:1001143](https://www.ebi.ac.uk/ols/ontologies/ms/terms?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FMS_1001143), e.g., Comet:xcorr.",
"subgroups": ["Describing details of the interpretation of the spectrum"]
},
"/Library/Spectrum/Analyte": {
"title": "Metadata specific to the analyte",
"description": "These attributes refer to the analyte(s) to which the spectrum is identified. In the present version of the library format, only peptide analytes are supported, but support for other kinds of analytes (e.g. small molecule metabolites) are expected in the future. They MUST be listed under <Analyte=_>",
"subgroups": ["Terms that describe the analyte"]
}
}
2 changes: 1 addition & 1 deletion .github/workflows/validate-json-schemas.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ jobs:
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v1
uses: actions/setup-python@v3
with:
python-version: 3.8
- name: Install dependencies
Expand Down
80 changes: 80 additions & 0 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
############
Contributing
############

This document briefly describes how to contribute to
`mzSpecLib <https://github.com/hupo-psi/mzspeclib>`_.



Before you begin
################

If you have an idea for a feature, use case to add or an approach for a bugfix,
you are welcome to communicate it with the community by opening a
thread in `GitHub Issues <https://github.com/hupo-psi/mzspeclib/issues>`_.



Development setup
#################

Local install
*************

#. Setup Python 3, and preferably create a virtual environment.
#. Clone the `mzSpecLib repository <https://github.com/hupo-psi/mzspeclib>`_.
#. Use pip in editable mode to setup the development environment:

.. code-block:: sh
pip install --editable .[test,docs]
Unit tests
**********

Run tests with ``pytest``:

.. code-block:: sh
pytest ./tests
Documentation
*************

To work on the documentation and get a live preview, install the requirements
and run ``sphinx-autobuild``:

.. code-block:: sh
pip install .[docs]
sphinx-autobuild ./docs/ ./docs/_build/
Then browse to http://localhost:8000 to watch the live preview.



How to contribute
#################

- Fork `mzSpecLib <https://github.com/hupo-psi/mzspeclib>`_ on GitHub to
make your changes.
- Commit and push your changes to your
`fork <https://help.github.com/articles/pushing-to-a-remote/>`_.
- Ensure that the tests and documentation (both Python docstrings and files in
``/docs/``) have been updated according to your changes. Python
docstrings are formatted in the
`numpydoc style <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
- Open a
`pull request <https://help.github.com/articles/creating-a-pull-request/>`_
with these changes. You pull request message ideally should include:

- A description of why the changes should be made.
- A description of the implementation of the changes.
- A description of how to test the changes.

- The pull request should pass all the continuous integration tests which are
automatically run by
`GitHub Actions <https://github.com/hupo-psi/mzspeclib/actions>`_.
21 changes: 21 additions & 0 deletions docs/.readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
version: 2

build:
os: ubuntu-22.04
tools:
python: "3.11"

sphinx:
configuration: docs/conf.py
builder: dirhtml

formats:
- pdf
- epub

python:
install:
- method: pip
path: implementations/python
extra_requirements:
- docs
Loading

0 comments on commit af6685f

Please sign in to comment.