Dynamic Habitat Index account ============================= WS4 can attach one published **Dynamic Habitat Index (DHI)** product to a compiled dataset and report the surviving DHI area under a schedule. The account is a static biodiversity surrogate; it does not change growth or claim a species response. Product and provenance ---------------------- The pilot uses the SILVIS Lab **MODIS 6.1 Terra NDVI Composite RGB** product for 2003-2022 at 500 m, in EPSG:4326. The three bands are cumulative DHI (``cum``), minimum DHI (``min``), and variation DHI (``var``); the delivered 8-bit values are divided by 255. The source is public with no restrictions; see . The public page also lists annual 1 km zips; the WCS subset used here is the 2003-2022 composite. No annual layer is claimed by this pilot. A DHI source descriptor is required whenever values are used. It records: ``source_id``, ``source_version``, ``year_range`` The product identity and the version/vintage. ``source_version`` is not optional. ``resolution_m``, ``crs``, ``bands``, ``scale`` The nominal pixel size, raster CRS, band names, and the divisor that maps stored values to the account's 0-1 index. ``bbox``, ``valid_pixels`` The raster subset extent and its count of valid pixels. ``source_path``, ``source_sha256``, ``retrieved_utc``, ``licence`` The exact artifact and when/how it was obtained. The descriptor is validated before the account is used: dropping a required field, an empty source version, a non-positive scale, or a non-positive valid-pixel count fails. A missing source version is never treated as "current". Ingest ------ .. code-block:: bash pip install 'ws4[dhi]' ws4 dhi ingest \ --raster dhi_subset.tif \ --blocks blocks.geojson \ --output dhi_values.csv \ --metadata dhi_metadata.json \ --source-version "MODIS 6.1 Terra NDVI Composite RGB (2003-2022)" ``--blocks`` is a polygon layer with a ``block_id`` column (aliases ``BLOCK``, ``block``, and ``id`` are accepted). Block polygons are reprojected to the raster CRS; each block's mean is calculated over all touched pixels, divided by ``--scale``, and clipped to ``[0, 1]``. A block with no valid pixels is an error: the layer does not cover the AOI. Duplicate block ids are an error. ``--band-names`` defaults to ``cum,min,var``; a raster with fewer bands than names is rejected. ``--resolution-m`` is the nominal product resolution, because an EPSG:4326 raster's transform is in degrees. It defaults to 500 for this product; set it explicitly for another product. The ingest writes: ``dhi_values.csv`` ``block_id,cum,min,var`` (or the requested band names), normalized to 0-1. ``dhi_metadata.json`` The source descriptor above. The pair is a portable contract: a run can be reproduced from the two files and the compiled dataset. The values are joined by ``block_id``; every dataset block must have a value before the simulator records the account. Account semantics ----------------- For each band and each simulated offset, WS4 records: ``feature.DHI.`` **Level**, unit ``index_ha``: sum of block DHI × block area over blocks not yet treated. This is the account to target or plot when the question is "how much DHI-weighted forest remains?". ``feature.DHI..mean`` **Level**, unit ``index``: area-weighted mean DHI over the same surviving blocks. ``feature.DHI.area`` **Level**, unit ``ha``: surviving block area. At offset -1 the account covers the whole dataset. At each later offset a block is removed when any scheduled treatment is applied to it. A block stays removed for the rest of the run. This is deliberately simple: the product is static, and the model does not simulate regrowth, recovery, or species recolonization. Two schedules differ only through which blocks they treat and when. The account is a level, not a flow. It is recorded in ``account_values.csv`` and is therefore available to the normal report, charts, and account API. It does not alter the optimiser objective, growth curves, or treatment eligibility. Run outputs ----------- When ``ws4 simulate`` receives both ``--dhi-values`` and ``--dhi-metadata``, the run directory also holds: ``dhi_values.csv`` The normalized values used by the run. ``dhi_metadata.json`` The source descriptor, so the run explains its own provenance. ``report_dhi.csv`` Written by ``ws4 report``: baseline, final, change, percent change, unit, source fields, and the interpretation caveat for each DHI account. The Python API is ``Simulator.run(..., dhi_account=DhiAccount(...))`` or ``ws4.dhi.read_dhi_account(values_path, metadata_path)``. Web layer --------- ``GET /api/runs/{run}/dhi`` returns the run's source metadata, band names, and block values. ``GET /api/runs/{run}/dhi?format=geojson`` joins those values to the configured ``--geometry`` and returns a ``FeatureCollection`` with one ``dhi`` property (the first band) plus each band's property. Without configured geometry the GeoJSON form is a 404 naming the missing artifact. The layer is a reader over the files the run wrote; it computes no new value. Caveats and limits ------------------ - **Scale.** The pilot product is 500 m. Blocks smaller than a pixel inherit the touched pixel value. Do not treat block values as field measurements, and do not map the account below the product's support. - **Vintage.** The public SILVIS composite covers 2003-2022 as one layer. It is not an annual time series. The trajectory is schedule-driven, not climate-driven. - **No species model.** DHI is a productivity/seasonality surrogate. It is not a species observation, a habitat-suitability model, or evidence of a causal treatment effect. - **No recovery.** A treated block leaves the account permanently for that run. This is a conservative pilot convention, not a regeneration model. - **No optimisation coupling.** The DHI account is reported, not optimised. Targets on it can be added by the ordinary account-target path, but the default objective is unchanged. Pilot ----- ``examples/dhi_pilot`` holds a real WCS subset, four synthetic blocks, two schedules, and the committed values/metadata. Its README gives the end-to-end commands and the expected direction of change. The pilot is a software fixture, not a management recommendation.