Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend documentation #10

Merged
merged 6 commits into from
Nov 15, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Add start for docs
  • Loading branch information
RalfG committed Dec 5, 2023
commit 4818da9a081f1704a63af4c8a48851ed045de0f7
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.venv/
.github/
docs/_build/
specification/annotation-schema.md
55 changes: 55 additions & 0 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
############
Contributing
############

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



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/mzPAF/issues>`_.



Documentation local setup
#########################

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

.. code-block:: sh

pip install -r ./docs/requirements.txt
sphinx-autobuild ./docs/ ./docs/_build/

Then browse to http://localhost:8000 to watch the live preview.



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

- Fork `mzPAF <https://github.com/hupo-psi/mzPAF>`_ 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/mzPAF/actions>`_.
85 changes: 77 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,86 @@
# mzPAF Peak Annotation Format

The mzPAF proposed standard is a specification for a fragment ion peak annotation format for mass spectra, focused on peptides. This provides for a standardized format for describing the origin of fragment ions to be used in spectral libraries, other formats that aim to describe fragment ions, and software tools that annotate fragment ions.
## About

The main home page for mzPAF is at the PSI web site: https://psidev.info/mzPAF
The mzPAF proposed standard is a specification for a fragment ion peak annotation format for mass spectra, focused on
peptides. This provides for a standardized format for describing the origin of fragment ions to be used in spectral
libraries, other formats that aim to describe fragment ions, and software tools that annotate fragment ions.

# Status
- Official mzPAF homepage: [psidev.info/mzPAF](https://psidev.info/mzPAF)
- mzPAF documentation: [mzpaf.readthedocs.io](https://mzpaf.readthedocs.io)

Updated: 2023-02-25

The specification has been submitted to the PSI Document Process and is undergoing review. It will take several months starting January 2023 to undergo rigorous review before potentially becoming a PSI standard.
## Specification status

# Available Materials
- The current DRAFT specification: https://github.com/HUPO-PSI/mzPAF/blob/main/specification/mzPAF_specification_v1.0-draft10.docx?raw=true
Updated: 2023-09-01

The specification has been resubmitted to the PSI Document Process and is undergoing final community review. Ratification to formally become a PSI standard is anticipated near the end of 2023.

Your comments and suggestions are still very much welcome. Please submit an issue at the repo to
provide your feedback and send an e-mail to the HUPO-PSI editor Sylvie Ricard-Blum
(sylvie.ricard-blum@univ-lyon1.fr).


## In short

- mzPAF is a single string of characters, case sensitive, without length limit
- Multiple possible explanations are separated with a comma
- Deltas of observed – theoretical *m/z* values are prefixed with a slash (`/`)
- Confidences can be provided for different annotations prefixed with an asterisk (`*`)

The basic format of each annotation is:

```
annotation1/delta,annotation2/delta,...
```

or:

```
annotation1/delta*confidence,annotation2/delta*confidence,...
```

For example:

```
b2-H2O/3.2ppm,b4-H2O^2/3.2ppm
```

or:

```
b2-H2O/3.2ppm*0.75,b4-H2O^2/3.2ppm*0.25
```

mzPAF supports:

- Annotations of multiple analytes: `1@y12/0.13,2@b9-NH3/0.23`
- Mass deltas in ppm instead of *m/z* unit: `y1/-1.4ppm`
- Confidence levels per annotation: `y1/-1.4ppm*0.75`
- Advanced ion notation: `[ion type](neutral loss)(isotope)(adduct type)(charge)`, e.g.: `y4-H2O+2i[M+H+Na]^2`:
- Ion types:
- Peptide ion series (a, b, c, x, y, z): `y4`
- Unknown ions: `?`
- Immonium ions: `IY`
- Internal fragment ions: `m3:6`
- Intact precursor ions: `p^2`
- A set of reference ions: `r[TMT127N]`
- Named compounds: `_{Urocanic Acid}`
- Chemical formulas: `f{C16H22O}`
- Smiles: `s{CN=C=O}[M+H]`
- Embedded ProForma annotations: `0@b2{LC[Carbamidomethyl]}`
- Neutral gains and losses: `y2+CO-H2O`
- Isotopes: `y2+2i`
- Adduct types: `y2[M+H]`
- Charge states: `^2`
- Multiple peaks per annotation: `&y7/-0.001` and `y7/0.000*0.95`

Read the [full specificiation](https://mzpaf.readthedocs.io/specification) for more details and
examples.


### Available Materials
- The current DRAFT specification: https://github.com/HUPO-PSI/mzPAF/blob/main/specification/mzPAF_specification_v1.0-draft14.docx?raw=true
- The GitHub repo associated with mzPAF: https://github.com/HUPO-PSI/mzPAF
- The GitHub repo assocated with the related mzSpecLib standard: https://github.com/HUPO-PSI/mzSpecLib
- The GitHub repo associated with the related mzSpecLib standard: https://github.com/HUPO-PSI/mzSpecLib

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