Merge branch 'update-documentation' into 'master'

Update documentation

See merge request IBG-1/micropro/peak-performance!33

How to adapt PeakPerformance to your data.md

@@ -0,0 +1,30 @@
+# How to adapt PeakPerformance to your methods / data
+If your data shows a lack of fit when using the default models and prior probability distributions (priors) implemented in PeakPerformance, there are two main scenarios which differ with regards to the action required:
+
+1. An implemented model should be able to fit your peak data, but it does not converge properly.
+2. No currently implemented model is able to fit your peak data.
+
+## Scenario 1: Update the model priors
+Open the `pipeline.py` file (containing the `pipeline` module) and search for functions starting with "define_".
+These will be the functions defining and returning a model object.
+Search for the function creating the model that should be able to fit your data and check the priors for its parameters.
+An easy way to visualize them is using the `stats` module from the `scipy` package in a seperate notebook and plotting the priors for an example peak of yours.
+Most likely, you will find that one or more priors do not represent your data well, e.g. the noise prior since that is highly dependent on the experimental method utilized to obtain your data in the first place.
+If you find priors that improve the model fit, just override the priors in the `pipeline` module.
+Be aware, though, that they will be overwritten by updates, so you should save them elsewhere and re-apply them when necessary.
+
+## Scenario 2: Implement another model
+To implement a new model to PeakPerformance, you will need to create the following functions:
+
+- In the `models` module: a function to define your model calling upon a separate function defining the posterior probablity distribution.
+- Optional: create unit tests for your model in `test_models.py`.
+- Required by AGPL: Publish your changes open source, for example by uploading the modified code to a public GitHub project. We are also welcoming pull requests that make PeakPerformance more enjoyable to use for everybody.
+
+
+Additionally, you will need to update the following code segments:
+
+- In the `models` module: update the ModelType class with your model.
+- In the `pipeline` module:
+  - Add your model to if-statement around the model definition in the `pipeline_loop()` function.
+  - Add your model to the `selection_loop()` function.
+- Required by AGPL: Publish your changes open source, for example by uploading the modified code to a public GitHub project. We are also welcoming pull requests that make PeakPerformance more enjoyable to use for everybody.

notebooks/Ex2_Custom_Use_of_PeakPerformance.ipynb

@@ -0,0 +1,123 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example 2: Directly access PeakPerformance's functions to create a custom pipeline"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas\n",
+    "import numpy as np\n",
+    "import arviz as az\n",
+    "from pathlib import Path\n",
+    "from peak_performance import pipeline as pl, models, plots"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Define your time series, e.g. by giving a path to the raw data file und loading it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "path = Path(\".\").absolute().parent / \"example\" / \"A1t1R1Part2_110_109.9_110.1.npy\"\n",
+    "timeseries = np.load(path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Decide on a model featured in PeakPerformance and create one based on the time series.  \n",
+    "E.g. for a normally distributed model:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pmodel = models.define_model_skew(\n",
+    "    time=timeseries[0],\n",
+    "    intensity=timeseries[1]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Sample the model with an appropriate number of tuning samples and draws."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "idata = pl.sampling(pmodel, tune=6000, draws=2000)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Define a path for the results plot and its name (identifier), then use e.g. the plots.plot_posterior() function to plot the posterior samples against the raw data. For other plots, check out the plots module or the ArviZ documentation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "path_result = Path(r\"\")\n",
+    "\n",
+    "plots.plot_posterior(\n",
+    "    identifier=\"test_plot\",\n",
+    "    time=timeseries[0],\n",
+    "    intensity=timeseries[1],\n",
+    "    path=path_result,\n",
+    "    idata=idata,\n",
+    "    discarded=False,\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "nutpie_env2",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}