dwdpheno 1.0.0__tar.gz

dwdpheno-1.0.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-13
+
+First public release.
+
+### Added
+- `stations()` – the DWD phenology station table (annual and immediate reporters) enriched with
+  county (BKG VG2500 point-in-polygon, English county types), nearest place (GeoNames) and
+  reporter type, with selection
+  by id, name, state, county, city, lat/lon + radius, nearest *k*, bounding box, polygon,
+  reporter and activity. With `crops=` (and `years=`, `partition=`, quality filters) only the
+  stations that have observations of those crops are returned, with `n_observations`,
+  `first_year` and `last_year` (`dwdpheno stations --crops ...`).
+- `crops()` – catalog of every species on the DWD server with English, German and Latin names
+  from DWD's plant table (latest historical file version only).
+- `phases()`, `find_bbch()`, `bbch_for()` – English phase names with BBCH codes.
+- `download()` – tidy observations with station metadata, plant and phase names, BBCH codes and
+  decoded quality flags; historical/recent overlap de-duplicated (recent wins). Crops are named
+  in English, German or as DWD token (exact name first, otherwise word prefixes).
+- `series()` – BBCH time series with data-driven season detection and a shape-preserving PCHIP
+  curve; `summary()` – day-of-year statistics with an OLS trend; `plot_station()`.
+- Data quality: `quality=` (DWD quality bytes 1 2 3 5 8 0) and `quality_level=` (1 2 7 10) on
+  `download`, `series`, `summary` and `plot_station` (`--quality`, `--quality-level`); by
+  default nothing is filtered. `series` point rows carry the quality columns, `summary` counts
+  the observations per quality byte and lists the quality levels, and the plot marks corrected,
+  confirmed, doubtful and incorrect observations.
+- `series()` has a `season_doy` column (day of the season, 1 = 1 January of the harvest year,
+  negative for the autumn before) for comparing seasons, stations and crops on one axis.
+- `plot_series()` – BBCH series of several stations, crops and seasons in one plot or as small
+  multiples (`x="date"|"season_doy"`, `color_by="crop"|"station"|"season"`,
+  `facet="station"|"crop"`); `plot_station()` is a shorthand for it.
+- `plot_phase_trend()` – day of year of phases against year with OLS trend lines (days per
+  decade in the legend). CLI: `dwdpheno plot --x --color-by --facet` with several station ids,
+  and `dwdpheno plot-trend`.
+- `places()` – search of the bundled German place list.
+- On-disk cache (historical files never expire, everything else after `max_age_days`) and
+  `offline=True`.
+- `dwdpheno` command line tool with `stations crops phases download series summary places plot
+  version` (CSV or JSON output).

dwdpheno-1.0.0/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use dwdpheno in your work, please cite it as below and acknowledge the data source (Deutscher Wetterdienst)."
+type: software
+title: "dwdpheno: download plant-phenology observations of the German Weather Service (DWD)"
+version: 1.0.0
+date-released: 2026-11-13
+license: MIT
+repository-code: "https://github.com/Bluerrror/DWDPheno"
+url: "https://github.com/Bluerrror/DWDPheno"
+authors:
+  - family-names: Shojaeezadeh
+    given-names: Shahab A.
+    email: shahab2710@gmail.com
+keywords:
+  - phenology
+  - DWD
+  - BBCH
+  - crops
+  - agriculture
+  - climate
+  - open data
+references:
+  - type: data
+    title: "Phenological observations in Germany (annual and immediate reporters)"
+    authors:
+      - name: "Deutscher Wetterdienst (DWD), Climate Data Center"
+    url: "https://opendata.dwd.de/climate_environment/CDC/observations_germany/phenology/"
+    license: CC-BY-4.0

dwdpheno-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Bug reports, ideas and pull requests are welcome at
+<https://github.com/Bluerrror/DWDPheno/issues>.
+
+## Development setup
+
+```bash
+git clone https://github.com/Bluerrror/DWDPheno
+cd DWDPheno
+python -m venv .venv
+# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
+pip install -e ".[test,plot]"
+pytest                 # offline tests (DWD responses are served from tests/fixtures)
+pytest -m network      # one small live download from opendata.dwd.de
+```
+
+## Guidelines
+
+- Keep the dependencies to `pandas` and `numpy` (`matplotlib` stays optional) and use the
+  standard library for HTTP.
+- Keep the column names and their order stable: they are part of the public API.
+- The package must work with pandas 1.5 through 3.x (copy-on-write, default string dtype) and
+  Python 3.9+.
+- Every behaviour change needs a test. Tests must run offline: add a trimmed real DWD file to
+  `tests/fixtures/` and route its URL in `tests/conftest.py`.
+- Update `CHANGELOG.md`.
+
+## Reference data
+
+`dwdpheno/data/` (administrative boundaries and places) is generated by
+`python tools/build_data.py`, which downloads BKG VG2500 and the GeoNames dump. Commit the
+regenerated files together with a note in the changelog.
+
+## Releasing
+
+1. Bump `__version__` in `dwdpheno/__init__.py`, update `CHANGELOG.md` and `CITATION.cff`.
+2. Create a GitHub release; the `publish` workflow builds the package and uploads it to PyPI
+   (trusted publishing).

dwdpheno-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shahab A. Shojaeezadeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dwdpheno-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md CHANGELOG.md CITATION.cff CONTRIBUTING.md
+recursive-include dwdpheno/data *.txt *.geojson
+graft tests
+graft tools
+global-exclude __pycache__ *.py[cod]