Merge branch 'develop' into documentation

.github/workflows/examples.yml

@@ -0,0 +1,40 @@
+name: examples
+
+on:
+  push:
+    branches:
+      - master
+      - develop
+  pull_request:
+  schedule:
+    - cron: '0 4 1 * *'
+
+jobs:
+  examples:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.8", "3.10"]
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v2
+
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          sudo apt-get install dvipng texlive-latex-extra texlive-fonts-recommended cm-super
+          python -m pip install --upgrade pip
+          pip install wheel
+          pip install .
+          pip install pytest
+          pip install nbmake
+
+      - name: Run tests
+        run: pytest -vv --nbmake examples/*.ipynb

CONTRIBUTING.md

@@ -22,9 +22,10 @@ Please add docstrings to any new function, class or method you implement. The do
 When implementing a new feature or fixing a bug please add meaningful tests to the files in the `tests` directory which cover the new code.
 For all pull requests tests are executed for the most recent python releases via
 ```
-pytest --cov=pyerrors -vv
+pytest -vv --cov=pyerrors
+pytest -vv --nbmake examples/*.ipynb
 ```
-requiring `pytest`, `pytest-cov` and `pytest-benchmark`. To get a coverage report in html run
+requiring `pytest`, `pytest-cov`, `pytest-benchmark` and `nbmake`. To get a coverage report in html run
 ```
 pytest --cov=pyerrors --cov-report html
 ```

README.md

@@ -1,4 +1,4 @@
-[![flake8](https://github.com/fjosw/pyerrors/actions/workflows/flake8.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/flake8.yml) [![pytest](https://github.com/fjosw/pyerrors/actions/workflows/pytest.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/pytest.yml) [![docs](https://github.com/fjosw/pyerrors/actions/workflows/docs.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/docs.yml) [![](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![flake8](https://github.com/fjosw/pyerrors/actions/workflows/flake8.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/flake8.yml) [![pytest](https://github.com/fjosw/pyerrors/actions/workflows/pytest.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/pytest.yml) [![examples](https://github.com/fjosw/pyerrors/actions/workflows/examples.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/examples.yml) [![docs](https://github.com/fjosw/pyerrors/actions/workflows/docs.yml/badge.svg)](https://github.com/fjosw/pyerrors/actions/workflows/docs.yml) [![](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 # pyerrors
 `pyerrors` is a python package for error computation and propagation of Markov chain Monte Carlo data.
 

pyerrors/obs.py

@@ -1342,7 +1342,7 @@ def correlate(obs_a, obs_b):
 
 
 def covariance(obs, visualize=False, correlation=False, smooth=None, **kwargs):
-    r'''Calculates the covariance matrix of a set of observables.
+    r'''Calculates the error covariance matrix of a set of observables.
 
     The gamma method has to be applied first to all observables.
 
@@ -1353,7 +1353,7 @@ def covariance(obs, visualize=False, correlation=False, smooth=None, **kwargs):
     visualize : bool
         If True plots the corresponding normalized correlation matrix (default False).
     correlation : bool
-        If True the correlation instead of the covariance is returned (default False).
+        If True the correlation matrix instead of the error covariance matrix is returned (default False).
     smooth : None or int
         If smooth is an integer 'E' between 2 and the dimension of the matrix minus 1 the eigenvalue
         smoothing procedure of hep-lat/9412087 is applied to the correlation matrix which leaves the
@@ -1362,8 +1362,11 @@ def covariance(obs, visualize=False, correlation=False, smooth=None, **kwargs):
 
     Notes
     -----
-    The covariance is estimated by calculating the correlation matrix assuming no autocorrelation and then rescaling the correlation matrix by the full errors including the previous gamma method estimate for the autocorrelation of the observables. The covariance at windowsize 0 is guaranteed to be positive semi-definite
+    The error covariance is defined such that it agrees with the squared standard error for two identical observables
-    $$v_i\Gamma_{ij}(0)v_j=\frac{1}{N}\sum_{s=1}^N\sum_{i,j}v_i\delta_i^s\delta_j^s v_j=\frac{1}{N}\sum_{s=1}^N\sum_{i}|v_i\delta_i^s|^2\geq 0\,,$$ for every $v\in\mathbb{R}^M$, while such an identity does not hold for larger windows/lags.
+    $$\operatorname{cov}(a,a)=\sum_{s=1}^N\delta_a^s\delta_a^s/N^2=\Gamma_{aa}(0)/N=\operatorname{var}(a)/N=\sigma_a^2$$
+    in the absence of autocorrelation.
+    The error covariance is estimated by calculating the correlation matrix assuming no autocorrelation and then rescaling the correlation matrix by the full errors including the previous gamma method estimate for the autocorrelation of the observables. The covariance at windowsize 0 is guaranteed to be positive semi-definite
+    $$\sum_{i,j}v_i\Gamma_{ij}(0)v_j=\frac{1}{N}\sum_{s=1}^N\sum_{i,j}v_i\delta_i^s\delta_j^s v_j=\frac{1}{N}\sum_{s=1}^N\sum_{i}|v_i\delta_i^s|^2\geq 0\,,$$ for every $v\in\mathbb{R}^M$, while such an identity does not hold for larger windows/lags.
     For observables defined on a single ensemble our approximation is equivalent to assuming that the integrated autocorrelation time of an off-diagonal element is equal to the geometric mean of the integrated autocorrelation times of the corresponding diagonal elements.
     $$\tau_{\mathrm{int}, ij}=\sqrt{\tau_{\mathrm{int}, i}\times \tau_{\mathrm{int}, j}}$$
     This construction ensures that the estimated covariance matrix is positive semi-definite (up to numerical rounding errors).