Metadata-Version: 2.4
Name: dhidb
Version: 0.2.5
Summary: TileDB access to the global 300 m Dynamic Habitat Indices database
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: 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"
Requires-Dist: scipy>=1.11; extra == "test"
Provides-Extra: netcdf
Requires-Dist: scipy>=1.11; extra == "netcdf"
Provides-Extra: zarr
Requires-Dist: zarr>=2.18; extra == "zarr"
Dynamic: license-file

# dhidb <a href='https://thisistaimur.github.io/dhidb/'><img src='https://raw.githubusercontent.com/thisistaimur/dhidb/main/assetts/DHIDB_logo_white.png' align="right" height="200" /></a>

[![PyPI version](https://img.shields.io/pypi/v/dhidb.svg?logo=pypi&label=PyPI)](https://pypi.org/project/dhidb/)
[![CI and release](https://github.com/thisistaimur/dhidb/actions/workflows/ci-release.yml/badge.svg)](https://github.com/thisistaimur/dhidb/actions/workflows/ci-release.yml)

`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.

DHIs are widely used in spatial ecology as interpretable predictors of habitat
quality and vegetation dynamics, including covariates in species distribution
models (SDMs) and biodiversity assessments.


## Installation

```bash
pip install dhidb
```

For development:

```bash
python -m pip install -e ".[test]"
```

## Requirements and optional dependencies

DHIDB requires Python 3.10 or newer. The runtime dependencies and the
compatibility ranges published by the package are:

| Dependency | Supported version range |
|---|---|
| `affine` | `>=2.4` |
| `numpy` | `>=1.26,<3` |
| `pandas` | `>=2.1` |
| `pyproj` | `>=3.6` |
| `rasterio` | `>=1.3` |
| `shapely` | `>=2.0` |
| `tiledb` | `>=0.35,<0.38` |
| `xarray` | `>=2024.1` |

Optional features are installed with package extras. There is no generic
`dhidb[dependency]` extra; use the feature-specific extra you need:

| Extra | Install command | Adds |
|---|---|---|
| `netcdf` | `pip install "dhidb[netcdf]"` | `scipy>=1.11` for NetCDF export |
| `zarr` | `pip install "dhidb[zarr]"` | `zarr>=2.18` for Zarr export |
| `test` | `pip install "dhidb[test]"` | build, pytest, coverage, Ruff, and SciPy tooling |

For local development and testing:

```bash
python -m pip install -e ".[test,netcdf,zarr]"
```

The documentation website has its own Node.js dependencies in
[`website/package.json`](website/package.json); they are not part of the
Python package extras.

## 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 Docusaurus website source is in [`website/`](website/). Build it locally
with:

```bash
npm --prefix website install
npm --prefix website run start
```

## 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
