Merge pull request #13 from JuBiotech/add-docs

Add documentation builds

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
         python-version: "3.10"
     - name: Build package
       run: |
-        pip install twine wheel
+        pip install -r requirements-dev.txt
         python setup.py bdist_wheel
     - name: Check version number match
       run: |

.github/workflows/tests.yml

@@ -19,8 +19,8 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
-        pip install -e .[test]
-        pip install twine wheel
+        pip install -e .
+        pip install -r requirements-dev.txt
     - name: Run tests
       run: |
         pytest -v --cov-report xml --cov=peak_performance --cov-report term-missing peak_performance

.gitignore

@@ -603,3 +603,5 @@ FodyWeavers.xsd
 *.svg
 idata_summary_*.xlsx
 idata_*
+*Sandbox*.ipynb
+!/docs/source/notebooks/*.png

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - requirements: requirements.txt
+    - method: pip
+      path: .

README.md

@@ -1,6 +1,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/peak-performance)](https://pypi.org/project/peak-performance/)
 [![pipeline](https://github.com/jubiotech/peak-performance/workflows/pipeline/badge.svg)](https://github.com/JuBiotech/peak-performance/actions)
 [![coverage](https://codecov.io/gh/jubiotech/peak-performance/branch/main/graph/badge.svg)](https://app.codecov.io/gh/JuBiotech/peak-performance)
+[![documentation](https://readthedocs.org/projects/peak-performance/badge/?version=latest)](https://peak-performance.readthedocs.io/en/latest)
 [![DOI](https://zenodo.org/badge/713469041.svg)](https://zenodo.org/doi/10.5281/zenodo.10255543)
 
 # How to use PeakPerformance
@@ -9,13 +10,15 @@ For instructions regarding the use of PeakPerformance, check out the example not
 
 ## Preparing raw data
 This step is crucial when using PeakPerformance. Raw data has to be supplied as time series meaning for each signal you want to analyze, save a NumPy array consisting of time in the first dimension and intensity in the second dimension (compare example data). Both time and intensity should also be NumPy arrays. If you e.g. have time and intensity of a singal as lists, you can use the following code to convert, format, and save them in the correct manner:
-```
+
+```python
 import numpy as np
 from pathlib import Path
 
 time_series = np.array([np.array(time), np.array(intensity)])
 np.save(Path(r"example_path/time_series.npy"), time_series)
 ```
+
 The naming convention of raw data files is `<acquisition name>_<precursor ion m/z or experiment number>_<product ion m/z start>_<product ion m/z end>.npy`. There should be no underscores within the named sections such as `acquisition name`. Essentially, the raw data names include the acquisition and mass trace, thus yielding a recognizable and unique name for each isotopomer/fragment/metabolite/sample.
 
 ## Model selection

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,6 @@
+sphinx
+myst-nb
+numpydoc
+nbsphinx
+sphinx-book-theme
+sphinxcontrib.mermaid

docs/source/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+from typing import List
+
+from peak_performance import __version__
+
+# -- Project information -----------------------------------------------------
+
+project = "PeakPerformance"
+copyright = "2023, Forschungszentrum Jülich GmbH"
+author = "Michael Osthege"
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "numpydoc",
+    "myst_nb",
+    "sphinx_book_theme",
+    "sphinxcontrib.mermaid",
+]
+nb_execution_mode = "off"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns: List[str] = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,52 @@
+Welcome to the PeakPerformance documentation!
+=============================================
+
+.. image:: https://img.shields.io/pypi/v/peak-performance
+   :target: https://pypi.org/project/peak-performance
+
+.. image:: https://img.shields.io/badge/code%20on-Github-lightgrey
+   :target: https://github.com/JuBiotech/peak-performance
+
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.10255543.svg
+   :target: https://zenodo.org/doi/10.5281/zenodo.10255543
+
+
+``peak_performance`` is a Python toolbox for Bayesian inference of peak areas.
+
+It defines PyMC models describing the intensity curves of chromatographic peaks.
+
+Using Bayesian inference, this enables the fitting of peaks, yielding uncertainty estimates for retention times, peak height, area and much more.
+
+Installation
+============
+
+.. code-block:: bash
+
+   pip install peak-performance
+
+You can also download the latest version from `GitHub <https://github.com/JuBiotech/peak-performance>`_.
+
+Tutorials
+=========
+
+The documentation features various notebooks that demonstrate the usage and investigate certain aspects of peak modeling.
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/Ex1_Simple_Pipeline.ipynb
+   notebooks/Ex2_Custom_Use_of_PeakPerformance.ipynb
+   notebooks/Ex3_Pipeline_with_larger_example_dataset.ipynb
+   notebooks/Investigation_doublepeak_separation.ipynb
+   notebooks/Investigation_noise_sigma.ipynb
+
+
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   pp_models
+   pp_pipeline
+   pp_plots

notebooks/Investigation_doublepeak_separation.ipynb → docs/source/notebooks/Investigation_doublepeak_separation.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Investigation of double-peak separation"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -21,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Load and inspect raw intensity data"
+    "## Load and inspect raw intensity data"
    ]
   },
   {
@@ -56,7 +63,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Define a peak model"
+    "## Define a peak model"
    ]
   },
   {
@@ -367,7 +374,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Inspect priors for separation and retention time"
+    "## Inspect priors for separation and retention time"
    ]
   },
   {
@@ -402,7 +409,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Run MCMC sampling and inspect results"
+    "## Run MCMC sampling and inspect results"
    ]
   },
   {

notebooks/Investigation_noise_sigma.ipynb → docs/source/notebooks/Investigation_noise_sigma.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Investigating the effect of `noise` on the area uncertainty quantification"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -22,7 +29,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Load and inspect raw intensity data"
+    "## Load and inspect raw intensity data"
    ]
   },
   {
@@ -74,7 +81,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Define a peak model"
+    "## Define a peak model"
    ]
   },
   {
@@ -385,7 +392,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Fix the `noise` settings using `pm.do`"
+    "## Fix the `noise` settings using `pm.do`"
    ]
   },
   {
@@ -684,7 +691,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Sample the models with fixed `noise`"
+    "## Sample the models with fixed `noise`"
    ]
   },
   {
@@ -1781,7 +1788,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Conclusion\n",
+    "## Conclusion\n",
     "\n",
     "* At high noise (>200 a.u.), the uncertainty about peak areas increases.\n",
     "* In this case, the model fits a noise of ~115 a.u. so that's well below the critical level."

docs/source/pp_models.rst

@@ -0,0 +1,9 @@
+``peak_performance.models``
+---------------------------
+
+This is the core of PeakPerformance, where the model functions for peaks are defined.
+
+.. automodule:: peak_performance.models
+	:members:
+	:undoc-members:
+	:show-inheritance:

docs/source/pp_pipeline.rst

@@ -0,0 +1,9 @@
+``peak_performance.pipeline``
+-----------------------------
+
+The ``pipeline`` module defines functions for analyzing hundreds of peaks in a data pipeline.
+
+.. automodule:: peak_performance.pipeline
+	:members:
+	:undoc-members:
+	:show-inheritance:

docs/source/pp_plots.rst

@@ -0,0 +1,9 @@
+``peak_performance.plots``
+--------------------------
+
+The ``plots`` module offer convenience functions for visualizing results and enabling quality control.
+
+.. automodule:: peak_performance.plots
+	:members:
+	:undoc-members:
+	:show-inheritance:

notebooks/README.md

@@ -0,0 +1,5 @@
+# Notebooks Moved
+
+Visit [docs/source/notebooks](../docs/source/notebooks).
+
+Or visit https://peak-performance.readthedocs.io.