dhidb 0.1.0__tar.gz

dhidb-0.1.0/.github/workflows/ci-release.yml

@@ -0,0 +1,123 @@
+name: CI and release
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  versioning:
+    name: Compute semantic version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.semver.outputs.version-string }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Compute version from Git history
+        id: semver
+        uses: bitshifted/git-auto-semver@v2
+        with:
+          create_tag: false
+          main_branch: main
+          initial_version: 0.1.0
+      - name: Display version
+        run: echo "Candidate version is ${{ steps.semver.outputs.version-string }}"
+
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package and test dependencies
+        run: python -m pip install -e ".[test]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest --cov=dhidb --cov-report=term-missing
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: [versioning, test]
+    env:
+      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DHIDB: ${{ needs.versioning.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Check distributions
+        run: |
+          python -m pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  release:
+    name: Tag, release, and publish
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [versioning, build]
+    environment:
+      name: pypi
+      url: https://pypi.org/project/dhidb/
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - name: Create semantic version tag
+        env:
+          VERSION: ${{ needs.versioning.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git rev-parse "v${VERSION}" >/dev/null 2>&1; then
+            echo "Tag v${VERSION} already exists"
+          else
+            git tag -a "v${VERSION}" -m "Release v${VERSION}"
+            git push origin "v${VERSION}"
+          fi
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.versioning.outputs.version }}
+          generate_release_notes: true
+          files: dist/*
+      - name: Publish to PyPI using trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI }}

dhidb-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "assetts/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install package and documentation dependencies
+        run: python -m pip install -e ".[docs]"
+      - name: Build Jupyter Book
+        run: jupyter-book build docs
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

dhidb-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+docs/_build/
+.venv/
+.DS_Store

dhidb-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Helmholtz Centre for Environmental Research - UFZ
+
+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.
+

dhidb-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dhidb
+Version: 0.1.0
+Summary: Read-only Python access to the global 300 m Dynamic Habitat Indices database
+Author: Julian Oeser, Ingolf Kühn
+Author-email: Taimur Khan <taimur.khan@ufz.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thisistaimur/dhidb
+Project-URL: Documentation, https://thisistaimur.github.io/dhidb/
+Project-URL: Repository, https://github.com/thisistaimur/dhidb
+Project-URL: Issues, https://github.com/thisistaimur/dhidb/issues
+Keywords: biodiversity,DHI,remote sensing,S3,TileDB
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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 :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: affine>=2.4
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: pyproj>=3.6
+Requires-Dist: rasterio>=1.3
+Requires-Dist: shapely>=2.0
+Requires-Dist: tiledb<0.38,>=0.35
+Requires-Dist: xarray>=2024.1
+Provides-Extra: docs
+Requires-Dist: jupyter-book<2,>=1.0; extra == "docs"
+Requires-Dist: matplotlib>=3.8; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: ruff>=0.9; extra == "test"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/thisistaimur/dhidb/main/assetts/DHIDB_logo_white.png" alt="DHIDB" width="720">
+</p>
+
+# dhidb
+
+`dhidb` provides read-only Python access to the global 300 m Dynamic Habitat
+Indices database stored as a dense TileDB array on public S3-compatible object
+storage. It supports point, bounding-box, and polygon queries without first
+downloading the complete database.
+
+
+## Installation
+
+```bash
+pip install dhidb
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[test,docs]"
+```
+
+## Quick start
+
+```python
+from dhidb import DHIProvider
+
+with DHIProvider() as db:
+    print(db.years)
+    print(db.variables)
+
+    germany = db.query_bbox(
+        bounds=(5.8, 47.2, 15.1, 55.1),
+        years=[2020, 2021, 2022],
+        variables=["dhi_cum", "dhi_min", "dhi_var", "valid_count"],
+    )
+```
+
+## Documentation
+
+The Jupyter Book source is in [`docs/`](docs/). Build it locally with:
+
+```bash
+jupyter-book build docs
+```
+
+## Data variables
+
+| Variable | Meaning | Unit |
+|---|---|---|
+| `dhi_cum` | Cumulative productivity from LSP TPROD | PPI integral (`m2 m-2 day`) |
+| `dhi_min` | Minimum seasonal productivity baseline from LSP MINV | PPI (`m2 m-2`) |
+| `dhi_var` | Inter-period GPP coefficient of variation | dimensionless |
+| `dhi_combined` | Normalized combined DHI, where available | dimensionless |
+| `observed_count` | Number of available 10-day observations | scenes |
+| `valid_count` | Number of accepted 10-day observations | scenes |
+| `qflag_any_count` | Observations carrying any source quality flag | scenes |
+| `qflag_rejected_count` | Observations rejected by quality filtering | scenes |
+
+## License
+
+MIT

dhidb-0.1.0/README.md

@@ -0,0 +1,64 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/thisistaimur/dhidb/main/assetts/DHIDB_logo_white.png" alt="DHIDB" width="720">
+</p>
+
+# dhidb
+
+`dhidb` provides read-only Python access to the global 300 m Dynamic Habitat
+Indices database stored as a dense TileDB array on public S3-compatible object
+storage. It supports point, bounding-box, and polygon queries without first
+downloading the complete database.
+
+
+## Installation
+
+```bash
+pip install dhidb
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[test,docs]"
+```
+
+## Quick start
+
+```python
+from dhidb import DHIProvider
+
+with DHIProvider() as db:
+    print(db.years)
+    print(db.variables)
+
+    germany = db.query_bbox(
+        bounds=(5.8, 47.2, 15.1, 55.1),
+        years=[2020, 2021, 2022],
+        variables=["dhi_cum", "dhi_min", "dhi_var", "valid_count"],
+    )
+```
+
+## Documentation
+
+The Jupyter Book source is in [`docs/`](docs/). Build it locally with:
+
+```bash
+jupyter-book build docs
+```
+
+## Data variables
+
+| Variable | Meaning | Unit |
+|---|---|---|
+| `dhi_cum` | Cumulative productivity from LSP TPROD | PPI integral (`m2 m-2 day`) |
+| `dhi_min` | Minimum seasonal productivity baseline from LSP MINV | PPI (`m2 m-2`) |
+| `dhi_var` | Inter-period GPP coefficient of variation | dimensionless |
+| `dhi_combined` | Normalized combined DHI, where available | dimensionless |
+| `observed_count` | Number of available 10-day observations | scenes |
+| `valid_count` | Number of accepted 10-day observations | scenes |
+| `qflag_any_count` | Observations carrying any source quality flag | scenes |
+| `qflag_rejected_count` | Observations rejected by quality filtering | scenes |
+
+## License
+
+MIT

dhidb-0.1.0/docs/_config.yml

@@ -0,0 +1,35 @@
+title: DHIDB
+author: Taimur Khan, Julian Oeser, and Ingolf Kühn
+copyright: "2026, Helmholtz Centre for Environmental Research - UFZ"
+logo: _static/DHIDB_logo.png
+only_build_toc_files: true
+execute:
+  execute_notebooks: "off"
+parse:
+  myst_enable_extensions:
+    - colon_fence
+    - deflist
+    - dollarmath
+    - linkify
+repository:
+  url: https://github.com/thisistaimur/dhidb
+  branch: main
+html:
+  favicon: _static/DHIDB_logo.png
+  use_issues_button: true
+  use_repository_button: true
+  home_page_in_navbar: true
+  extra_footer: >-
+    DHIDB is developed at the Helmholtz Centre for Environmental Research - UFZ.
+sphinx:
+  extra_extensions:
+    - sphinx.ext.autodoc
+    - sphinx.ext.napoleon
+    - sphinx_copybutton
+  config:
+    html_css_files:
+      - custom.css
+    html_theme_options:
+      logo:
+        text: DHIDB
+      show_nav_level: 2

dhidb-0.1.0/docs/_static/custom.css

@@ -0,0 +1,75 @@
+:root {
+  --dhidb-black: #050505;
+  --dhidb-panel: #111416;
+  --dhidb-purple: #440154;
+  --dhidb-blue: #31688e;
+  --dhidb-green: #35b779;
+  --dhidb-yellow: #fde725;
+  --pst-color-primary: #35b779;
+  --pst-color-link: #35b779;
+  --pst-color-link-hover: #fde725;
+}
+
+html[data-theme="light"],
+html[data-theme="dark"] {
+  --pst-color-background: var(--dhidb-black);
+  --pst-color-on-background: #f4f7f5;
+  --pst-color-surface: var(--dhidb-panel);
+  --pst-color-on-surface: #e8efec;
+  --pst-color-text-base: #eef4f1;
+  --pst-color-text-muted: #aab8b2;
+  --pst-color-border: #27302d;
+}
+
+body,
+.bd-header,
+.bd-sidebar-primary,
+.bd-sidebar-secondary,
+.bd-main .bd-content .bd-article-container {
+  background: var(--dhidb-black);
+  color: #eef4f1;
+}
+
+.bd-header {
+  border-bottom: 1px solid #27302d;
+}
+
+a,
+.toc-entry a.nav-link.active,
+.bd-links .current > a {
+  color: var(--dhidb-green);
+}
+
+a:hover {
+  color: var(--dhidb-yellow);
+}
+
+code {
+  color: #9be26d;
+}
+
+pre,
+div.highlight {
+  background: #0d1110;
+  border: 1px solid #27302d;
+}
+
+.hero-logo {
+  margin: 1rem auto 2rem;
+  max-height: 300px;
+  object-fit: contain;
+}
+
+table {
+  border-color: #27302d;
+}
+
+thead {
+  background: linear-gradient(90deg, var(--dhidb-purple), var(--dhidb-blue));
+}
+
+.admonition {
+  background: var(--dhidb-panel);
+  border-left-color: var(--dhidb-green);
+}
+

dhidb-0.1.0/docs/_toc.yml

@@ -0,0 +1,10 @@
+format: jb-book
+root: index
+chapters:
+  - file: getting-started
+  - file: data-model
+  - file: queries
+  - file: quality
+  - file: api
+  - file: contributing
+

dhidb-0.1.0/docs/api.md

@@ -0,0 +1,11 @@
+# Python API
+
+```{eval-rst}
+.. autoclass:: dhidb.DHIConfig
+   :members:
+
+.. autoclass:: dhidb.DHIProvider
+   :members:
+   :undoc-members:
+```
+

dhidb-0.1.0/docs/contributing.md

@@ -0,0 +1,22 @@
+# Contributing and releases
+
+Install the development environment and run the checks locally:
+
+```bash
+python -m pip install -e ".[test,docs]"
+ruff check src tests
+pytest
+python -m build
+jupyter-book build docs
+```
+
+## Versioning
+
+The CI workflow derives a semantic version from Git history. It computes the
+candidate version for pull requests and pushes, but creates a tag, GitHub
+release, and PyPI distribution only after the test matrix and package build
+have succeeded on `main`.
+
+PyPI publication uses GitHub trusted publishing. Configure the `pypi`
+environment for this repository on PyPI before enabling the first release.
+

dhidb-0.1.0/docs/data-model.md

@@ -0,0 +1,31 @@
+# Data model
+
+DHIDB v1 is a dense TileDB array with dimensions `(time, y, x)`.
+
+| Dimension | Size | Meaning |
+|---|---:|---|
+| `time` | 12 | Annual layers from 2014 through 2025 |
+| `y` | 47,040 | Global raster rows |
+| `x` | 120,960 | Global raster columns |
+
+Each annual layer contains 5,689,958,400 grid cells. The complete logical
+array contains 68,279,500,800 cells before compression and exclusion of
+unwritten fragments.
+
+## Variables
+
+| Variable | Definition | Unit |
+|---|---|---|
+| `dhi_cum` | Sum of LSP TPROD over two growing seasons | PPI integral (`m2 m-2 day`) |
+| `dhi_min` | Minimum of scaled LSP MINV over two growing seasons | PPI (`m2 m-2`) |
+| `dhi_var` | Coefficient of variation of accepted 10-day GPP | dimensionless |
+| `dhi_combined` | Sum of normalized component layers | dimensionless |
+| `observed_count` | Available GPP observations | scenes |
+| `valid_count` | Accepted GPP observations | scenes |
+| `qflag_any_count` | Observations carrying any source QFLAG | scenes |
+| `qflag_rejected_count` | Rejected observations | scenes |
+
+`dhi_cum` and `dhi_min` summarize the smoothed Plant Phenology Index
+trajectory represented by Copernicus LSP. They are not direct annual GPP sums
+or minima. `dhi_var` is calculated from the 10-day GPP time series.
+

dhidb-0.1.0/docs/getting-started.md

@@ -0,0 +1,41 @@
+# Getting started
+
+## Install
+
+```bash
+pip install dhidb
+```
+
+## Connect to public QAS storage
+
+Public reads use unsigned S3 requests. No access key is required.
+
+```python
+from dhidb import DHIProvider
+
+db = DHIProvider()
+print(db.years)
+print(db.variables)
+db.close()
+```
+
+The provider uses the public endpoint and array defaults, so Python needs no
+connection arguments:
+
+```python
+from dhidb import DHIProvider
+
+with DHIProvider() as db:
+    print(db.metadata)
+```
+
+
+## Query safety
+
+The default client refuses a request containing more than 50 million
+space-time cells. This protects laptops from accidentally materializing a
+global array. Raise the limit deliberately when appropriate:
+
+```python
+db = DHIProvider(max_cells=100_000_000)
+```

dhidb-0.1.0/docs/index.md

@@ -0,0 +1,37 @@
+# Global habitat dynamics, queried where you need them
+
+```{image} _static/DHIDB_logo.png
+:alt: DHIDB logo
+:class: hero-logo
+:width: 760px
+:align: center
+```
+
+DHIDB provides direct, read-only access to annual global Dynamic Habitat
+Indices at 300 m resolution. The data remain in a dense TileDB array on public
+S3-compatible object storage; the Python package retrieves only the years,
+variables, and spatial window requested by the user.
+
+The indices describe three complementary dimensions of vegetation dynamics:
+
+- cumulative productivity (`dhi_cum`),
+- the minimum seasonal productivity baseline (`dhi_min`), and
+- inter-period variability in gross primary production (`dhi_var`).
+
+```python
+from dhidb import DHIProvider
+
+with DHIProvider() as db:
+    point = db.query_point(12.37, 51.34, years=range(2014, 2026))
+```
+
+:::{important}
+The provider uses the public QAS endpoint and production array defaults
+automatically. Public reads do not require credentials.
+:::
+
+## Why TileDB?
+
+The database contains 12 annual layers over a grid of 47,040 by 120,960 cells,
+or 68,279,500,800 dense array cells. TileDB exposes this as `(time, y, x)` and
+allows small spatial subsets to be read without transferring the full array.

dhidb-0.1.0/docs/quality.md

@@ -0,0 +1,16 @@
+# Quality information
+
+The database retains observation counts alongside the DHI components so that
+users can evaluate temporal support for each pixel.
+
+`observed_count` records how many 10-day GPP scenes were present.
+`valid_count` records how many contributed after source-quality screening.
+`qflag_any_count` and `qflag_rejected_count` summarize the original
+Copernicus QFLAG observations.
+
+For annual products, a maximum `valid_count` of 36 is expected. The TileDB
+fill value for an unwritten `uint16` cell is 65,535; clients should not
+interpret that value as an observation count. Query only production-complete
+years and use finite DHI values together with plausible count values when
+validating an analysis.
+