Merge pull request #13 from btschwertfeger/9-create-a-documentation

Create the documentation

Author: btschwertfeger

.github/workflows/_build_doc.yml

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2023 Benjamin Thomas Schwertfeger
+# Github: https://github.com/btschwertfeger
+#
+# Template workflow to build documentation.
+#
+
+name: Build Doc
+
+on:
+  workflow_call:
+    inputs:
+      os:
+        type: string
+        required: true
+      python-version:
+        type: string
+        required: true
+
+jobs:
+  Build:
+    runs-on: ${{ inputs.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ inputs.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs/requirements.txt
+
+      - name: Build the documentation
+        run: cd docs && make html

.github/workflows/_test.yml

@@ -18,7 +18,7 @@ on:
         required: true
 
 jobs:
-  Test-Spot:
+  Test:
     name: Test ${{ inputs.os }} ${{ inputs.python-version }}
     runs-on: ${{ inputs.os }}
     steps:
@@ -37,5 +37,5 @@ jobs:
       - name: Install package
         run: python -m pip install ".[dev]"
 
-      - name: Testing Spot REST endpoints
+      - name: Run unit tests
         run: pytest tests/

.github/workflows/cicd.yml

@@ -37,6 +37,15 @@ jobs:
       os: ${{ matrix.os }}
       python-version: ${{ matrix.python-version }}
 
+  ##    Build the documentation
+  ##
+  Build-Doc:
+    needs: [Pre-Commit]
+    uses: ./.github/workflows/_build_doc.yml
+    with:
+      os: "ubuntu-latest"
+      python-version: "3.11"
+
   ##    Run the unit tests for Python 3.8 until 3.11
   ##
   Test:

.gitignore

@@ -135,6 +135,7 @@ del*.py
 *.csv
 *.log
 *.zip
+.vscode/
 
 *.egg-info/
 conda.stuff/

.pylintrc

@@ -176,14 +176,14 @@ function-naming-style=snake_case
 
 # Good variable names which should always be accepted, separated by a comma.
 good-names=i,
+           x,
            j,
            k,
            ex,
            Run,
            _,
            X,
            QDM1,
-           a,
            LS_simh,LS_simp,VS_1_simh,VS_2_simp,VS_1_simp,
            CMethods
 
@@ -335,7 +335,7 @@ indent-string='    '
 max-line-length=100
 
 # Maximum number of lines in a module.
-max-module-lines=1000
+max-module-lines=10000
 
 # Allow the body of a class to be on the same line as the declaration if body
 # contains single statement.

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .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 version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt

Makefile

@@ -46,7 +46,7 @@ pre-commit:
 ##		Clean the workspace
 ##
 clean:
-	rm -rf .pytest_cache build/ dist/ python_cmethods.egg-info docs/_build
+	rm -rf .pytest_cache build/ dist/ python_cmethods.egg-info docs/_build examples/.ipynb_checkpoints
 	rm -f .coverage cmethods/_version.py
 
 	find tests -name "__pycache__" | xargs rm -rf

README.md

@@ -14,12 +14,15 @@
 ![release](https://shields.io/github/release-date/btschwertfeger/python-cmethods)
 ![release](https://shields.io/github/v/release/btschwertfeger/python-cmethods?display_name=tag)
 [![DOI](https://zenodo.org/badge/496160109.svg)](https://zenodo.org/badge/latestdoi/496160109)
+[![Documentation Status](https://readthedocs.org/projects/python-cmethods/badge/?version=stable)](https://python-cmethods.readthedocs.io/en/latest/?badge=stable)
 
 </div>
 
 This Python module contains a collection of different scale- and distribution-based bias adjustment techniques for climatic research (see `/examples/examples.ipynb` for help).
 
-### 📍 For the application of bias corrections on _lage data sets_ it is recomanded to use the C++ tool [BiasAdjustCXX](https://github.com/btschwertfeger/Bias-Adjustment-Cpp) since bias corrections are complex statistical transformation which are very slow in Python compared to the C++ implementation.
+The documentation is available at: [https://python-kraken-sdk.readthedocs.io/en/stable/](https://python-kraken-sdk.readthedocs.io/en/stable/)
+
+> ⚠️ For the application of bias corrections on _lage data sets_ it is recomanded to use the command-line tool [BiasAdjustCXX](https://github.com/btschwertfeger/BiasAdjustCXX) since bias corrections are complex statistical transformation which are very slow in Python compared to the C++ implementation.
 
 ---
 
@@ -42,7 +45,7 @@ These programs and data structures are designed to help minimize discrepancies b
 
 <figure>
   <img
-  src="images/biasCdiagram.png?raw=true"
+  src="docs/images/biasCdiagram.png?raw=true"
   alt="Schematic representation of a bias adjustment procedure"
   style="background-color: white; border-radius: 7px">
   <figcaption>Figure 1: Schematic representation of a bias adjustment procedure</figcaption>
@@ -52,7 +55,7 @@ In this way, for example, modeled data, which on average represent values that a
 
 <figure>
   <img
-  src="images/dm-doy-plot.png?raw=true"
+  src="docs/images/dm-doy-plot.png?raw=true"
   alt="Temperature per day of year in modeled, observed and bias-adjusted climate data"
   style="background-color: white; border-radius: 7px">
   <figcaption>Figure 2: Temperature per day of year in observed, modeled, and bias-adjusted climate data</figcaption>
@@ -93,8 +96,7 @@ python3 -m pip install python-cmethods
 
 ```python
 import xarray as xr
-from cmethods.CMethods import CMethods
-cm = CMethods()
+from cmethods.CMethods import CMethods as cm
 
 obsh = xr.open_dataset('input_data/observations.nc')
 simh = xr.open_dataset('input_data/control.nc')
@@ -125,7 +127,7 @@ Notes:
 - When using the `adjust_3d` method you have to specify the method by name.
 - For the multiplicative linear scaling and the delta method as well as the variance scaling method a maximum scaling factor of 10 is defined. This can be changed by the parameter `max_scaling_factor`.
 
-## Examples (see repository on [GitHub](https://github.com/btschwertfeger/Bias-Adjustment-Python))
+## Examples (see repository on [GitHub](https://github.com/btschwertfeger/python-cmethods))
 
 Notebook with different methods and plots: `/examples/examples.ipynb`
 
@@ -153,23 +155,24 @@ python3 do_bias_correction.py         \
 
 ## 5. Notes
 
-- Computation in Python takes some time, so this is only for demonstration. When adjusting large datasets, its best to use the C++ tool [BiasAdjustCXX](https://github.com/btschwertfeger/Bias-Adjustment-Cpp).
+- Computation in Python takes some time, so this is only for demonstration. When adjusting large datasets, its best to use the C++ tool [BiasAdjustCXX](https://github.com/btschwertfeger/BiasAdjustCXX).
 - Formulas and references can be found in the implementations of the corresponding functions.
 
 ### Space for improvements:
 
-Since the scaling methods implemented so far scale by default over the mean values of the respective months, unrealistic long-term mean values may occur at the month transitions. This can be prevented either by selecting `group='time.dayofyear'`. Alternatively, it is possible not to scale using long-term mean values, but using a 31-day interval, which takes the 31 surrounding values over all years as the basis for calculating the mean values. This is not yet implemented in this module, but is available in the C++ implementation [here](https://github.com/btschwertfeger/Bias-Adjustment-Cpp).
+Since the scaling methods implemented so far scale by default over the mean values of the respective months, unrealistic long-term mean values may occur at the month transitions. This can be prevented either by selecting `group='time.dayofyear'`. Alternatively, it is possible not to scale using long-term mean values, but using a 31-day interval, which takes the 31 surrounding values over all years as the basis for calculating the mean values. This is not yet implemented in this module, but is available in the C++ tool [BiasAdjustCXX](https://github.com/btschwertfeger/BiasAdjustCXX).
 
 ---
 
 <a name="references"></a>
 
 ## 6. References
 
-- Schwertfeger, Benjamin Thomas (2022) The influence of bias corrections on variability, distribution, and correlation of temperatures in comparison to observed and modeled climate data in Europe (https://epic.awi.de/id/eprint/56689/)
-- Linear Scaling and Variance Scaling based on: Teutschbein, Claudia and Seibert, Jan (2012) Bias correction of regional climate model simulations for hydrological climate-change impact studies: Review and evaluation of different methods (https://doi.org/10.1016/j.jhydrol.2012.05.052)
-- Delta Method based on: Beyer, R. and Krapp, M. and Manica, A.: An empirical evaluation of bias correction methods for palaeoclimate simulations (https://doi.org/10.5194/cp-16-1493-2020)
-- Quantile and Detrended Quantile Mapping based on: Alex J. Cannon and Stephen R. Sobie and Trevor Q. Murdock Bias Correction of GCM Precipitation by Quantile Mapping: How Well Do Methods Preserve Changes in Quantiles and Extremes? (https://doi.org/10.1175/JCLI-D-14-00754.1)
-- Quantile Delta Mapping based on: Tong, Y., Gao, X., Han, Z. et al. Bias correction of temperature and precipitation over China for RCM simulations using the QM and QDM methods. Clim Dyn 57, 1425–1443 (2021). (https://doi.org/10.1007/s00382-020-05447-4)
+- Schwertfeger, Benjamin Thomas and Lohmann, Gerrit and Lipskoch, Henrik (2023) _"Introduction of the BiasAdjustCXX command-line tool for the application of fast and efficient bias corrections in climatic research"_, SoftwareX, Volume 22, 101379, ISSN 2352-7110, (https://doi.org/10.1016/j.softx.2023.101379)
+- Schwertfeger, Benjamin Thomas (2022) _"The influence of bias corrections on variability, distribution, and correlation of temperatures in comparison to observed and modeled climate data in Europe"_ (https://epic.awi.de/id/eprint/56689/)
+- Linear Scaling and Variance Scaling based on: Teutschbein, Claudia and Seibert, Jan (2012) _"Bias correction of regional climate model simulations for hydrological climate-change impact studies: Review and evaluation of different methods"_ (https://doi.org/10.1016/j.jhydrol.2012.05.052)
+- Delta Method based on: Beyer, R. and Krapp, M. and Manica, A.: _"An empirical evaluation of bias correction methods for palaeoclimate simulations"_ (https://doi.org/10.5194/cp-16-1493-2020)
+- Quantile and Detrended Quantile Mapping based on: Alex J. Cannon and Stephen R. Sobie and Trevor Q. Murdock _"Bias Correction of GCM Precipitation by Quantile Mapping: How Well Do Methods Preserve Changes in Quantiles and Extremes?"_ (https://doi.org/10.1175/JCLI-D-14-00754.1)
+- Quantile Delta Mapping based on: Tong, Y., Gao, X., Han, Z. et al. _"Bias correction of temperature and precipitation over China for RCM simulations using the QM and QDM methods"_. Clim Dyn 57, 1425–1443 (2021). (https://doi.org/10.1007/s00382-020-05447-4)
 
 ---