From af708f062e0f30484a88ada53f405aa13b69b72c Mon Sep 17 00:00:00 2001 From: Michael Osthege Date: Sat, 11 May 2024 15:17:09 +0200 Subject: [PATCH] Add documentation-build Closes #9 --- .readthedocs.yaml | 24 +++++++ README.md | 5 +- docs/Makefile | 20 ++++++ docs/make.bat | 35 +++++++++++ docs/requirements.txt | 6 ++ docs/source/conf.py | 63 +++++++++++++++++++ docs/source/index.rst | 52 +++++++++++++++ .../Investigation_doublepeak_separation.ipynb | 15 +++-- .../notebooks/Investigation_noise_sigma.ipynb | 17 +++-- docs/source/pp_models.rst | 9 +++ docs/source/pp_pipeline.rst | 9 +++ docs/source/pp_plots.rst | 9 +++ 12 files changed, 254 insertions(+), 10 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/pp_models.rst create mode 100644 docs/source/pp_pipeline.rst create mode 100644 docs/source/pp_plots.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..833db14 --- /dev/null +++ b/.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: . diff --git a/README.md b/README.md index f9b0ed4..109cb47 100644 --- a/README.md +++ b/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 `___.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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..ffaa18c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +sphinx +myst-nb +numpydoc +nbsphinx +sphinx-book-theme +sphinxcontrib.mermaid diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..aacae2d --- /dev/null +++ b/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"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..cf0494d --- /dev/null +++ b/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 `_. + +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 diff --git a/docs/source/notebooks/Investigation_doublepeak_separation.ipynb b/docs/source/notebooks/Investigation_doublepeak_separation.ipynb index 7858ab2..edc62d5 100644 --- a/docs/source/notebooks/Investigation_doublepeak_separation.ipynb +++ b/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" ] }, { diff --git a/docs/source/notebooks/Investigation_noise_sigma.ipynb b/docs/source/notebooks/Investigation_noise_sigma.ipynb index becb877..b8c1d01 100644 --- a/docs/source/notebooks/Investigation_noise_sigma.ipynb +++ b/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." diff --git a/docs/source/pp_models.rst b/docs/source/pp_models.rst new file mode 100644 index 0000000..b8c27c0 --- /dev/null +++ b/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: diff --git a/docs/source/pp_pipeline.rst b/docs/source/pp_pipeline.rst new file mode 100644 index 0000000..bf0e86a --- /dev/null +++ b/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: diff --git a/docs/source/pp_plots.rst b/docs/source/pp_plots.rst new file mode 100644 index 0000000..ac571d5 --- /dev/null +++ b/docs/source/pp_plots.rst @@ -0,0 +1,9 @@ +``peak_performance.plots`` +-------------------------- + +The ``plots`` module offer convenience functions for making QC plots. + +.. automodule:: peak_performance.plots + :members: + :undoc-members: + :show-inheritance: