AMAROC-847 ampycloud release v2.1 (#142)

* Add manual trigger for pypi release * Update copyright in tag * Upate citatiuon details * Fix typo * Fix format of CITATION.cff * Amaroc 841 localized base height calculation (#137) * AMAROC-835 add ceilo id query for base height calculation * AMAROC-835 request minimum amount of hits for base height calculation * AMAROC-841 localized cloud base height calculation * AMAROC-842 resolve version conflict * AMAROC-841 AMAROC-842 adapt changelog * AMAROC-841 raise warning if we do not filter but filter is set + adapt test * AMAROC-841 add documentation * AMAROC-841 fix doc referencing * AMAROC-841 exclude instead of keep ceilos (#140) * AMAROC-847 Set new release version (#141) --------- Co-authored-by: Frédéric P.A. Vogt <[email protected]>
MeteoSwiss · Sep 4, 2024 · b8ae022 · b8ae022
1 parent be88291
commit b8ae022
Show file tree

Hide file tree

Showing 12 changed files with 208 additions and 11 deletions.
diff --git a/.github/workflows/CI_pypi.yml b/.github/workflows/CI_pypi.yml
@@ -3,12 +3,14 @@
 # at the repo or organization levels to upload the package via API authentification.
 #
 # It will trigger the moment a new release or pre-release is being published.
+# Edit 12.07.2024: added the option for a manual trigger
 #
-# Copyright (c) 2022-2023 fpavogt; [email protected]
+# Copyright (c) 2022-2024 fpavogt; [email protected]
 
 name: CI_pypi
 
 on:
+  workflow_dispatch:  # Allows to trigger the release to pypi manually
   release:
     types: [published]
 
@@ -18,9 +20,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
 
-    - name: Checkout current repository
+    - name: Checkout current repository (auto release)
+      if: ${{ github.event_name == 'release' }}
       uses: actions/checkout@v4
 
+    - name: Checkout current repository (manual release from master)
+      if: ${{ github.event_name == 'workflow_dispatch' }}
+      uses: actions/checkout@v4
+      with:
+        repository: MeteoSwiss/ampycloud
+        ref: master
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:

diff --git a/CHANGELOG b/CHANGELOG
@@ -3,6 +3,12 @@ All notable changes to ampycloud will be documented in this file.
 The format is inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v2.1.1]
+### Added:
+ - [regDaniel, 2024-10-28] Feature to calculate cloud base height with a subset of instruments only
+### Fixed:
+ - [regDaniel, 2024-10-28] Incompatibility of scipy and statsmodels
+
 ## [v2.0.0]
 ### Added:
  - [fpavogt, 2024-06-26] Add ability to trigger weekly tests manually.

diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,60 @@
+
+cff-version: 1.2.0
+message: If ampycloud was useful for your research, please cite both the dedicated article (from preferred-citation) and the software itself.
+type: software
+authors:
+  - family-names: Vogt
+    given-names: Frédéric P.A.
+  - family-names: Foresti
+    given-names: Loris
+  - family-names: Regenass
+    given-names: Daniel
+  - family-names: Réthoré
+    given-names: Sophie
+  - family-names: Tarin Burriel
+    given-names: Néstor
+title: ampycloud
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.8399683
+    description: Zenodo entry
+repository-code: 'https://github.com/MeteoSwiss/ampycloud/'
+url: 'https://meteoswiss.github.io/ampycloud/'
+license: BSD-3-Clause
+preferred-citation:
+  title: "ampycloud: an open-source algorithm to determine cloud base heights and sky coverage fractions from ceilometer data"
+  abstract: |
+    Ceilometers are used routinely at aerodromes worldwide to derive the height and sky coverage fraction of cloud layers. This information, possibly combined with direct observations by human observers, contributes to the production of meteorological aerodrome reports (METARs). Here, we present ampycloud, a new algorithm, and its associated Python package for automatic processing of ceilometer data with the aim of determining the sky coverage fraction and base height of cloud layers above aerodromes. The ampycloud algorithm was developed at the Swiss Federal Office of Meteorology and Climatology (MeteoSwiss) as part of the AMAROC (AutoMETAR/AutoReport rOund the Clock) program to help in the fully automatic production of METARs at Swiss civil aerodromes. ampycloud is designed to work with no direct human supervision. The algorithm consists of three distinct, sequential steps that rely on agglomerative clustering methods and Gaussian mixture models to identify distinct cloud layers from individual cloud base hits reported by ceilometers. The robustness of the ampycloud algorithm stems from the first processing step, which is simple and reliable. It constrains the two subsequent processing steps that are more sensitive but also better suited to handling complex cloud distributions. The software implementation of the ampycloud algorithm takes the form of an eponymous, pip-installable Python package developed on GitHub and made publicly accessible.
+  type: article
+  journal: Atmospheric Measurement Techniques
+  issue: 16
+  languages:
+    - eng
+  pages: 4891-4914
+  volume: 17
+  url: https://amt.copernicus.org/articles/17/4891/2024/
+  authors:
+    - family-names: Vogt
+      given-names: Frédéric P. A.
+    - family-names: Foresti
+      given-names: Loris
+    - family-names: Regenass
+      given-names: Daniel
+    - family-names: Réthoré
+      given-names: Sophie
+    - family-names: Tarin Burriel
+      given-names: Néstor
+    - family-names: Bibby
+      given-names: Mervyn
+    - family-names: Juda
+      given-names: Przemysław
+    - family-names: Balmelli
+      given-names: Simone
+    - family-names: Hanselmann
+      given-names: Tobias
+    - family-names: du Preez
+      given-names: Pieter
+    - family-names: Furrer
+      given-names: Dirk
+  date-published: 2024-08-27
+  doi: 10.5194/amt-17-4891-2024
diff --git a/docs/source/acknowledge.rst b/docs/source/acknowledge.rst
@@ -9,11 +9,25 @@ Acknowledging ampycloud
 
    ampycloud |version| |doi|
 
-2. If ampycloud was useful for your research, please cite the dedicated article:
+2. If ampycloud was useful for your research, please cite the `dedicated article <https://doi.org/10.5194/amt-17-4891-2024>`_:
 
-   .. todo::
+   .. code-block:: latex
+
+        @Article{Vogt2024,
+        AUTHOR = {Vogt, F. P. A. and Foresti, L. and Regenass, D. and R\'ethor\'e, S. and
+                  Tarin Burriel, N. and Bibby, M. and Juda, P. and Balmelli, S. and
+                  Hanselmann, T. and du Preez, P. and Furrer, D.},
+        TITLE = {ampycloud: an open-source algorithm to determine cloud base heights and
+                 sky coverage fractions from ceilometer data},
+        JOURNAL = {Atmospheric Measurement Techniques},
+        VOLUME = {17},
+        YEAR = {2024},
+        NUMBER = {16},
+        PAGES = {4891--4914},
+        URL = {https://amt.copernicus.org/articles/17/4891/2024/},
+        DOI = {10.5194/amt-17-4891-2024}
+        }
 
-      When the time comes, include here the link to the dedicated ampycloud article.
 
 3. ampycloud relies on external Python libraries that require & deserve to be acknowledged in their
    own right. The following LaTeX blurb is one way to do so:

diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -0,0 +1,29 @@
+.. include:: ./substitutions.rst
+
+.. _changes:
+
+Scientific changes since v2.0.0
+===============================
+
+The scientific documentation of Ampycloud v2.0.0 can be found
+`here <https://amt.copernicus.org/articles/17/4891/2024/>`_. In this page, we
+list all changes since v.2.0.0 that go beyond bugfixing, refactoring, patching,
+etc. and have an impact on the science of the algorithm. More detailed
+information on changes can be found in the `changelog <changelog>`.
+
+
+v2.1.0: Enable ceilometer filtering for calculation of cloud base height
+------------------------------------------------------------------------
+
+There might be situations, where it is beneficial to calculate the cloud base
+height from a subset of ceilometer hits reported by specific ceilometers. For
+example:
+- If the cloud height is supposed to be representative for a given location, but
+you still want to use as many ceilometers as possible to infer the amount.
+- If you use different ceilometer models and know that you want to calculate the
+height only from hits of a specific ceilometer model to avoid implementing
+complicated correction factors.
+To this end, the parameter ``EXCLUDE_FOR_BASE_HEIGHT_CALC`` was implemented in
+this version. The default value is an empty list. In order to activate the
+filtering, it is sufficient to enter the ceilometer IDs of the ceilos to exclude
+from the base height calculation.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -40,7 +40,8 @@ Welcome to the ampycloud documentation
 * **Who:** ampycloud is being developed at `MeteoSwiss <https://www.meteoswiss.admin.ch>`__.
   See also the code's :ref:`license & copyright <license:License & Copyright>` information.
 
-* **How:** a scientific article describing the ampycloud **algorithm** is currently in preparation.
+* **How:** a scientific article describing the ampycloud **algorithm** is published
+  `here <https://amt.copernicus.org/articles/17/4891/2024/>`_.
   This article will be complemented by these webpages, that contain the official documentation of
   the ampycloud **Python package**.
 
@@ -64,6 +65,7 @@ Table of contents
     troubleshooting
     acknowledge
     license
+    changes
     changelog
     Contributing <https://github.com/MeteoSwiss/ampycloud/blob/develop/CONTRIBUTING.md>
     Github repository <https://github.com/MeteoSwiss/ampycloud>