rainfallqc 0.0.9__tar.gz

rainfallqc-0.0.9/LICENSE

@@ -0,0 +1,33 @@
+GNU GENERAL PUBLIC LICENSE
+                      Version 3, 29 June 2007
+
+    Quality control procedure for rainfall data
+    Copyright (C) 2025  Tom Keel
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<http://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<http://www.gnu.org/philosophy/why-not-lgpl.html>.
+

rainfallqc-0.0.9/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: rainfallqc
+Version: 0.0.9
+Summary: Quality control for rainfall data
+Author-email: Tom Keel <tomkee@ceh.ac.uk>
+Maintainer-email: Tom Keel <tomkee@ceh.ac.uk>
+Requires-Python: >=3.10.0
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: numpy
+Requires-Dist: polars
+Requires-Dist: pandas
+Requires-Dist: xarray
+Requires-Dist: bottleneck
+Requires-Dist: geopy
+Requires-Dist: pip ; extra == "dev"
+Requires-Dist: numpy ; extra == "dev"
+Requires-Dist: bump-my-version ; extra == "dev"
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: black ; extra == "dev"
+Requires-Dist: pre_commit ; extra == "dev"
+Requires-Dist: pylint ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: matplotlib ; extra == "dev"
+Requires-Dist: sphinx ; extra == "dev"
+Requires-Dist: sphinx ; extra == "docs"
+Requires-Dist: sphinx-copybutton ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme ; extra == "docs"
+Requires-Dist: mypy ; extra == "lint"
+Requires-Dist: ruff ; extra == "lint"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-cov ; extra == "test"
+Project-URL: bugs, https://github.com/thomasjkeel/RainfallQC/issues
+Project-URL: changelog, https://github.com/thomasjkeel/RainfallQC/blob/master/changelog.md
+Project-URL: homepage, https://github.com/thomasjkeel/RainfallQC
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lint
+Provides-Extra: test
+
+===============================================
+RainfallQC - Quality control for rainfall data
+===============================================
+
+..
+    image:: https://img.shields.io/pypi/v/rainfallqc.svg
+        :target: https://pypi.python.org/pypi/rainfallqc
+
+..
+    image:: https://readthedocs.org/projects/rainfallqc/badge/?version=latest
+        :target: https://rainfallqc.readthedocs.io/en/latest/?version=latest
+        :alt: Documentation Status
+
+
+Provides methods for running QC frameworks.
+
+**NOTEBOOK DEMO AVAILABLE** `HERE <https://github.com/Thomasjkeel/RainfallQC-notebooks/blob/main/notebooks/demo/rainfallQC_demo.ipynb>`_
+
+Please email tomkee@ceh.ac.uk if you have any questions.
+
+Project To Do:
+
+- add flag descriptions
+- Use timestep str maker to the checks
+
+Example use
+-----------
+
+Example 1. - Individual quality checks on single rain gauge
+===========================================================
+
+.. code-block:: python
+
+        # Load two types of QC'ing modules from RainfallQC
+        from rainfallqc import gauge_checks, comparison_checks
+
+        # 1. Simple 1 gauge QC
+        # 1.1. Run 1 qc method for 1 gauge
+        intermittency_flag = gauge_checks.check_intermittency(data, rain_col="rain_mm")
+
+        # 1.2. Run 1 qc method for 1 gauge using in-built comparison dataset
+        wr_flags = comparison_checks.check_exceedance_of_rainfall_world_record(data, rain_col="rain_mm", time_res='hourly')
+
+        # 1.3. Run 1 qc method for 1 gauge using in-built comparison dataset and location of gauge
+        rx1day_flags = comparison_checks.check_annual_exceedance_etccdi_rx1day(data, rain_col="rain_mm", gauge_lon=1.0, gauge_lat=55.0)
+
+
+Example 2. - Individual quality checks on networks of rain gauges
+=================================================================
+
+.. code-block:: python
+
+        # 2. Run neighbour/network checks on a subset of a rain gauge network
+        from rainfallqc import neighbourhood_checks
+        from rainfallqc.utils import data_readers
+
+        # 2.1. Read in GDSR gauge network metadata
+        gdsr_obj = data_readers.GDSRNetworkReader(path_to_gdsr_dir="./tests/data/GDSR/")
+
+        # 2.2. subset by max 10 gauges within 50 km and with at least 500 days of overlap
+        nearby_ids = list(
+            gdsr_obj.get_nearest_overlapping_neighbours_to_target(
+                target_id="DE_00310", distance_threshold=50, n_closest=10, min_overlap_days=500
+            )
+        )
+        nearby_ids.append(target_id)
+        nearby_data_paths = gdsr_obj.metadata.filter(pl.col("station_id").is_in(nearby_ids))["path"]
+
+        # 2.3. Load those nearest gauges from network metadata
+        gdsr_network = gdsr_obj.load_network_data(data_paths=nearby_data_paths)
+
+        # 2.4 Run a neighbourhood check (checking if suspiciously large rainfall values were seen in neighbours)
+        extreme_wet_flags = neighbourhood_checks.check_wet_neighbours(
+            gdsr_network,
+            target_gauge_col="rain_mm_DE_02483",
+            neighbouring_gauge_cols=gdsr_network.columns[1:],  # exclude time
+            time_res="hourly",
+            wet_threshold=1.0, # threshold for rainfall intensity to be considered
+            min_n_neighbours=5, # number of neighbours needed for comparison
+            n_neighbours_ignored=0, # ignore no neighbours and include all
+        )
+
+Example 3. - Applying a framework of QC methods (e.g. IntenseQC)
+================================================================
+
+.. code-block:: python
+
+        # 3. Applying multiple QC methods in framework (e.g. IntenseQC)
+        from rainfallqc.qc_frameworks import apply_qc_framework
+
+        # 3.1. Decide which QC methods of IntenseQC will be run
+        qc_framework = "IntenseQC"
+        qc_methods_to_run = ["QC1", "QC8", "QC9", "QC10", "QC11", "QC12", "QC14", "QC15", "QC16"]
+
+        # 3.2 Decide which parameters for QC
+        qc_kwargs = {
+            "QC1": {"quantile": 5},
+            "QC14": {"wet_day_threshold": 1.0, "accumulation_multiplying_factor": 2.0},
+            "QC16": {
+                "neighbouring_gauge_cols": daily_gpcc_network.columns[2:],
+                "wet_threshold": 1.0,
+                "min_n_neighbours": 5,
+                "n_neighbours_ignored": 0,
+            },
+            # Shared defaults applied to all
+            "shared": {
+                "rain_col": "rain_mm_DE_02483",
+                "target_gauge_col": "rain_mm_DE_02483",
+                "gauge_lat": gpcc_metadata["latitude"],
+                "gauge_lon": gpcc_metadata["longitude"],
+                "time_res": "daily",
+                "data_resolution": 0.1,
+            },
+        }
+
+        # 3.3. Run QC methods on network data
+        qc_result = apply_qc_framework.run_qc_framework(
+            daily_gpcc_network, qc_framework=qc_framework, qc_methods_to_run=qc_methods_to_run, qc_kwargs=qc_kwargs
+        )
+
+
+Other examples
+===================
+Also see example Jupyter Notebooks here: https://github.com/Thomasjkeel/RainfallQC-notebooks/tree/main
+
+Documents
+---------
+* Free software: GNU General Public License v3
+* Documentation: https://rainfallqc.readthedocs.io.
+
+
+Features
+--------
+
+- 25 rainfall QC methods (all from IntenseQC)
+- editable parameters so you can tweak thresholds, streak or accumulation lengths, and distances to neighbouring gauges
+
+Credits
+-------
+Based on the IntenseQC: https://github.com/nclwater/intense-qc/tree/master
+
+
+This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
+
+.. _Cookiecutter: https://github.com/audreyr/cookiecutter
+.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
+

rainfallqc-0.0.9/README.rst

@@ -0,0 +1,146 @@
+===============================================
+RainfallQC - Quality control for rainfall data
+===============================================
+
+..
+    image:: https://img.shields.io/pypi/v/rainfallqc.svg
+        :target: https://pypi.python.org/pypi/rainfallqc
+
+..
+    image:: https://readthedocs.org/projects/rainfallqc/badge/?version=latest
+        :target: https://rainfallqc.readthedocs.io/en/latest/?version=latest
+        :alt: Documentation Status
+
+
+Provides methods for running QC frameworks.
+
+**NOTEBOOK DEMO AVAILABLE** `HERE <https://github.com/Thomasjkeel/RainfallQC-notebooks/blob/main/notebooks/demo/rainfallQC_demo.ipynb>`_
+
+Please email tomkee@ceh.ac.uk if you have any questions.
+
+Project To Do:
+
+- add flag descriptions
+- Use timestep str maker to the checks
+
+Example use
+-----------
+
+Example 1. - Individual quality checks on single rain gauge
+===========================================================
+
+.. code-block:: python
+
+        # Load two types of QC'ing modules from RainfallQC
+        from rainfallqc import gauge_checks, comparison_checks
+
+        # 1. Simple 1 gauge QC
+        # 1.1. Run 1 qc method for 1 gauge
+        intermittency_flag = gauge_checks.check_intermittency(data, rain_col="rain_mm")
+
+        # 1.2. Run 1 qc method for 1 gauge using in-built comparison dataset
+        wr_flags = comparison_checks.check_exceedance_of_rainfall_world_record(data, rain_col="rain_mm", time_res='hourly')
+
+        # 1.3. Run 1 qc method for 1 gauge using in-built comparison dataset and location of gauge
+        rx1day_flags = comparison_checks.check_annual_exceedance_etccdi_rx1day(data, rain_col="rain_mm", gauge_lon=1.0, gauge_lat=55.0)
+
+
+Example 2. - Individual quality checks on networks of rain gauges
+=================================================================
+
+.. code-block:: python
+
+        # 2. Run neighbour/network checks on a subset of a rain gauge network
+        from rainfallqc import neighbourhood_checks
+        from rainfallqc.utils import data_readers
+
+        # 2.1. Read in GDSR gauge network metadata
+        gdsr_obj = data_readers.GDSRNetworkReader(path_to_gdsr_dir="./tests/data/GDSR/")
+
+        # 2.2. subset by max 10 gauges within 50 km and with at least 500 days of overlap
+        nearby_ids = list(
+            gdsr_obj.get_nearest_overlapping_neighbours_to_target(
+                target_id="DE_00310", distance_threshold=50, n_closest=10, min_overlap_days=500
+            )
+        )
+        nearby_ids.append(target_id)
+        nearby_data_paths = gdsr_obj.metadata.filter(pl.col("station_id").is_in(nearby_ids))["path"]
+
+        # 2.3. Load those nearest gauges from network metadata
+        gdsr_network = gdsr_obj.load_network_data(data_paths=nearby_data_paths)
+
+        # 2.4 Run a neighbourhood check (checking if suspiciously large rainfall values were seen in neighbours)
+        extreme_wet_flags = neighbourhood_checks.check_wet_neighbours(
+            gdsr_network,
+            target_gauge_col="rain_mm_DE_02483",
+            neighbouring_gauge_cols=gdsr_network.columns[1:],  # exclude time
+            time_res="hourly",
+            wet_threshold=1.0, # threshold for rainfall intensity to be considered
+            min_n_neighbours=5, # number of neighbours needed for comparison
+            n_neighbours_ignored=0, # ignore no neighbours and include all
+        )
+
+Example 3. - Applying a framework of QC methods (e.g. IntenseQC)
+================================================================
+
+.. code-block:: python
+
+        # 3. Applying multiple QC methods in framework (e.g. IntenseQC)
+        from rainfallqc.qc_frameworks import apply_qc_framework
+
+        # 3.1. Decide which QC methods of IntenseQC will be run
+        qc_framework = "IntenseQC"
+        qc_methods_to_run = ["QC1", "QC8", "QC9", "QC10", "QC11", "QC12", "QC14", "QC15", "QC16"]
+
+        # 3.2 Decide which parameters for QC
+        qc_kwargs = {
+            "QC1": {"quantile": 5},
+            "QC14": {"wet_day_threshold": 1.0, "accumulation_multiplying_factor": 2.0},
+            "QC16": {
+                "neighbouring_gauge_cols": daily_gpcc_network.columns[2:],
+                "wet_threshold": 1.0,
+                "min_n_neighbours": 5,
+                "n_neighbours_ignored": 0,
+            },
+            # Shared defaults applied to all
+            "shared": {
+                "rain_col": "rain_mm_DE_02483",
+                "target_gauge_col": "rain_mm_DE_02483",
+                "gauge_lat": gpcc_metadata["latitude"],
+                "gauge_lon": gpcc_metadata["longitude"],
+                "time_res": "daily",
+                "data_resolution": 0.1,
+            },
+        }
+
+        # 3.3. Run QC methods on network data
+        qc_result = apply_qc_framework.run_qc_framework(
+            daily_gpcc_network, qc_framework=qc_framework, qc_methods_to_run=qc_methods_to_run, qc_kwargs=qc_kwargs
+        )
+
+
+Other examples
+===================
+Also see example Jupyter Notebooks here: https://github.com/Thomasjkeel/RainfallQC-notebooks/tree/main
+
+Documents
+---------
+* Free software: GNU General Public License v3
+* Documentation: https://rainfallqc.readthedocs.io.
+
+
+Features
+--------
+
+- 25 rainfall QC methods (all from IntenseQC)
+- editable parameters so you can tweak thresholds, streak or accumulation lengths, and distances to neighbouring gauges
+
+Credits
+-------
+Based on the IntenseQC: https://github.com/nclwater/intense-qc/tree/master
+
+
+This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
+
+.. _Cookiecutter: https://github.com/audreyr/cookiecutter
+.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage

rainfallqc-0.0.9/pyproject.toml

@@ -0,0 +1,158 @@
+[build-system]
+requires = ["flit_core >=3.4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "rainfallqc"
+dynamic = ["version"]
+description = "Quality control for rainfall data"
+readme = "README.rst"
+requires-python = ">=3.10.0"
+authors = [{ name = "Tom Keel", email = "tomkee@ceh.ac.uk" }]
+maintainers = [{ name = "Tom Keel", email = "tomkee@ceh.ac.uk" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+license = { file = "LICENSE" }
+dependencies = [
+  "scipy",
+  "numpy",
+  "polars",
+  "pandas",
+  "xarray",
+  "bottleneck",
+  "geopy"
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+docs = ["sphinx", "sphinx-copybutton", "sphinx-rtd-theme"]
+lint = ["mypy", "ruff"]
+dev = [
+  "pip",
+  "numpy",
+  "bump-my-version",
+  "ruff",
+  "black",
+  "pre_commit",
+  "pylint",
+  "pytest",
+  "pytest-cov",
+  "matplotlib",
+  "sphinx",
+]
+
+[project.urls]
+bugs = "https://github.com/thomasjkeel/RainfallQC/issues"
+changelog = "https://github.com/thomasjkeel/RainfallQC/blob/master/changelog.md"
+homepage = "https://github.com/thomasjkeel/RainfallQC"
+
+[tool]
+
+[tool.black]
+target-version = ["py310", "py311", "py312", "py313"]
+
+[tool.bumpversion]
+current_version = "0.0.9"
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+commit_args = ""
+allow_dirty = false
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\-(?P<release>[a-z]+))?"
+serialize = ["{major}.{minor}.{patch}-{release}", "{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+tag = false
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+
+
+[[tool.bumpversion.files]]
+filename = "src/rainfallqc/__init__.py"
+search = "__version__ = \"{current_version}\""
+replace = "__version__ = \"{new_version}\""
+
+[tool.bumpversion.parts.release]
+optional_value = "gamma"
+values = ["alpha", "beta", "gamma"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=rainfallqc"
+markers = ["slow: Marks slow tests"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.setuptools]
+package-dir = { "src" = "src" }
+
+[tool.setuptools.package-data]
+"rainfallqc" = ["data/ETCCDI/*.nc"]
+
+[tool.coverage.run]
+omit = ["tests/*.py", "*__init__.py"]
+relative_files = true
+
+[tool.ruff]
+src = ["src", "tests"]
+include = ["src/**.py"]
+line-length = 120
+
+[tool.ruff.lint]
+ignore = [
+  "D203", # incorrect-blank-line-before-class
+  "D212", # multi-line-summary-first-line
+]
+preview = true
+select = [
+  "A",
+  "B",      # bugbear
+  "D",      # docstrings
+  "E",      # pycodestyle errors
+  "F",      # pyflakes
+  "I",      # imports
+  "W",      # pycodestyle warnings
+  "PLC",
+  "PLE",
+  "PLW",
+  "N816",
+  "ANN001",
+  "ANN201",
+  "ANN202",
+  "ANN205",
+  "ANN206", # TODO
+]
+exclude = ["docs/conf.py", "docs/notebooks/*.ipynb"]
+
+[tool.ruff.lint.flake8-type-checking]
+strict = true
+
+[tool.ruff.lint.isort]
+case-sensitive = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+  "ANN001", "ANN201", "ANN202", # Missing type annotation
+  "D103" # Missing docstring in public function
+]
+
+[tool.mypy]
+files = "."
+
+# Use strict defaults
+strict = true
+warn_unreachable = true
+warn_no_return = true

rainfallqc-0.0.9/src/rainfallqc/__init__.py

@@ -0,0 +1,22 @@
+"""Top-level package for RainfallQC."""
+
+__author__ = """Tom Keel"""
+__email__ = "tomkee@ceh.ac.uk"
+__version__ = "0.0.9"
+
+from rainfallqc.checks import (
+    comparison_checks,
+    gauge_checks,
+    neighbourhood_checks,
+    timeseries_checks,
+)
+from rainfallqc.qc_frameworks import apply_qc_framework
+
+__all__ = [
+    "apply_qc_framework",
+    "comparison_checks",
+    "gauge_checks",
+    "neighbourhood_checks",
+    "timeseries_checks",
+    "apply_qc_framework",
+]

rainfallqc-0.0.9/src/rainfallqc/checks/__init__.py

@@ -0,0 +1 @@
+"""Quality checks."""