Merge pull request #8 from sede-open/update_documentation

Update documentation

.github/workflows/code_formatting.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Run isort and black when required and commit back
         if: ${{ failure() || steps.checks.outcome == 'failure'}}
         env:
-          GITHUB_ACCESS_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           isort .
           black .

.github/workflows/manual_release.yml

@@ -27,7 +27,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Get version
         env:
-          GITHUB_ACCESS_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         id: version
         run: |
           version=$(python .github/get_version.py)
@@ -36,4 +36,4 @@ jobs:
       - name: Create Release
         run: gh release create ${{ env.BUMPED_VERSION }} --generate-notes
         env:
-          GITHUB_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release_tagging.yml

@@ -27,7 +27,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Get version
         env:
-          GITHUB_ACCESS_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         id: version
         run: |
           version=$(python .github/get_version.py)
@@ -36,4 +36,4 @@ jobs:
       - name: Create Release
         run: gh release create ${{ env.BUMPED_VERSION }} --generate-notes
         env:
-          GITHUB_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/sonarcloud_analysis.yml

@@ -31,7 +31,7 @@ jobs:
       - name: SonarCloud Scan
         uses: SonarSource/sonarcloud-github-action@master
         env:
-          GITHUB_TOKEN: ${{ secrets.PYELQ_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       - name: Upload SonarCloud Scan Report
         uses: actions/upload-artifact@v4

README.md

@@ -10,7 +10,6 @@ SPDX-License-Identifier: Apache-2.0
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/pyelq-sdk.svg?logo=python&logoColor=FFE873)](https://pypi.org/project/pyelq-sdk/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Code Style Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Tests](https://github.com/sede-open/pyelq/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/sede-open/pyelq/actions/workflows/main.yml)
 
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=pyelq_pyelq&metric=coverage)](https://sonarcloud.io/summary/new_code?id=pyelq_pyelq)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=pyelq_pyelq&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=pyelq_pyelq)
@@ -51,6 +50,26 @@ Use cases where the pyELQ code has been applied are described in the following p
 * IJzermans, R., Jones, M., Weidmann, D. et al. "Long-term continuous monitoring of methane emissions at an oil and gas facility using a multi-open-path laser dispersion spectrometer." Sci Rep 14, 623 (2024). (https://doi.org/10.1038/s41598-023-50081-9)
 
 * Weidmann, D., Hirst, B. et al. "Locating and Quantifying Methane Emissions by Inverse Analysis of Path-Integrated Concentration Data Using a Markov-Chain Monte Carlo Approach." ACS Earth and Space Chemistry 2022 6 (9), 2190-2198  (https://doi.org/10.1021/acsearthspacechem.2c00093)
+
+## Deployment design
+The pyELQ code needs high-quality methane concentration and wind data to be able to provide reliable output on location 
+and quantification of methane emission sources. This requires methane concentration sensors of sufficiently high 
+precision in a layout that allows the detection of relevant methane emission sources, in combination with wind 
+measurements of high enough frequency and accuracy. The optimal sensor layout typically depends on the prevailing 
+meteorological conditions at the site of interest and requires multiple concentration sensors to cover the site under 
+different wind directions. 
+
+## pyELQ data interpretation
+The results from pyELQ come with uncertainty ranges that are representative of probability density functions sampled 
+by a Markov Chain Monte Carlo method. One should take these uncertainty ranges into account when interpreting the pyELQ 
+output data. Remember that absence of evidence for methane emissions does not always imply evidence for absence of 
+methane emissions; for instance, when meteorological conditions are such that there is no sensor downwind of a methane 
+source during the selected monitoring period, then it will be impossible to detect, localize and quantify 
+this particular source. 
+Also, there are limitations to the forward dispersion model which is used in the analysis. 
+For example, the performance of the Gaussian plume dispersion model will degrade at lower wind speeds. 
+Therefore, careful interpretation of the data is always required. 
+
 ***
 # Installing pyELQ as a package
 Suppose you want to use this pyELQ package in a different project.

docs/index.md

@@ -33,6 +33,25 @@ Use cases where the pyELQ code has been applied are described in the following p
 * IJzermans, R., Jones, M., Weidmann, D. et al. "Long-term continuous monitoring of methane emissions at an oil and gas facility using a multi-open-path laser dispersion spectrometer." Sci Rep 14, 623 (2024). (https://doi.org/10.1038/s41598-023-50081-9)
 
 * Weidmann, D., Hirst, B. et al. "Locating and Quantifying Methane Emissions by Inverse Analysis of Path-Integrated Concentration Data Using a Markov-Chain Monte Carlo Approach." ACS Earth and Space Chemistry 2022 6 (9), 2190-2198  (https://doi.org/10.1021/acsearthspacechem.2c00093)
+
+## Deployment design
+The pyELQ code needs high-quality methane concentration and wind data to be able to provide reliable output on location 
+and quantification of methane emission sources. This requires methane concentration sensors of sufficiently high 
+precision in a layout that allows the detection of relevant methane emission sources, in combination with wind 
+measurements of high enough frequency and accuracy. The optimal sensor layout typically depends on the prevailing 
+meteorological conditions at the site of interest and requires multiple concentration sensors to cover the site under 
+different wind directions. 
+
+## pyELQ data interpretation
+The results from pyELQ come with uncertainty ranges that are representative of probability density functions sampled 
+by a Markov Chain Monte Carlo method. One should take these uncertainty ranges into account when interpreting the pyELQ 
+output data. Remember that absence of evidence for methane emissions does not always imply evidence for absence of 
+methane emissions; for instance, when meteorological conditions are such that there is no sensor downwind of a methane 
+source during the selected monitoring period, then it will be impossible to detect, localize and quantify 
+this particular source. 
+Also, there are limitations to the forward dispersion model which is used in the analysis. 
+For example, the performance of the Gaussian plume dispersion model will degrade at lower wind speeds. 
+Therefore, careful interpretation of the data is always required. 
 ***
 # Installing pyELQ as a package
 Suppose you want to use this pyELQ package in a different project.
@@ -59,4 +78,4 @@ For more details on contributing to this repository, see the [Contributing guide
 ***
 # Licensing
 
-Distributed under the Apache License Version 2.0. See the [license file](https://github.com/sede-open/pyELQ/blob/main/LICENSE.md) for more information.
+Distributed under the Apache License Version 2.0. See the [license file](https://github.com/sede-open/pyELQ/blob/main/LICENSE.md) for more information.

pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "pyelq-sdk"
-version = "1.0.4"
+version = "1.0.5"
 description = "Package for detection, localization and quantification code."
 authors = ["Bas van de Kerkhof", "Matthew Jones", "David Randell"]
 homepage = "https://sede-open.github.io/pyELQ/"