# Bärindex lingonberry habitat — research data package

**Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).**

Species: lingonberry / lingon (*Vaccinium vitis-idaea*).
Creator and licensor: **Emil Hessman**. Project: Bärindex.
Dataset landing page: <https://xn--brindex-5wa.se/data/>.
Contact: <kontakt@svampindex.se>.
Model release: `bar_habitat_release_v4`, 23 August 2026.
Package version: `lingonberry-habitat-v4-2026-10-30`.
Source surface: `bar_habitat_national_shadow_v3.parquet`. The `v3` filename
contains the selected **v4** model output; it is not a separate model version.

This package contains model predictions, not survey records. It describes
relative habitat suitability for NFI-observed lingonberry plant occurrence in
Sweden. It does **not** estimate vegetation cover, flowering, fruit set,
berry yield, crop quantity or ripeness.

## Files and grid

- `lingonberry-habitat.tif`: two-band Float32 Cloud Optimized GeoTIFF (COG).
- `lingonberry-quality.tif`: two-band UInt8 COG on exactly the same grid.
- `manifest.json`: source hashes, software versions, grid and band metadata,
  map-parity verification, and checksums of the two rasters and this README.
- `SHA256SUMS.txt`: checksums of all other package files, including the manifest.

CRS: **SWEREF 99 TM, EPSG:3006**, coordinates in metres. Pixels are areas,
1,000 × 1,000 m, north-up. Extent (west, south, east, north):
269000, 6134000, 918000, 7672000. Dimensions: 649 columns × 1538 rows.
The northwest pixel centre is (269500, 7671500).

There are 447,940 source grid cells: 446,606 scored and 1,334 excluded from
scoring. Pixels not present in the source grid are outside the dataset;
the bounding rectangle is not a national boundary or land mask. Neither
outside-dataset nor excluded cells mean ecological absence.

Both rasters use lossless DEFLATE compression, internal tiles and
nearest-neighbour overviews. Base-resolution scores are copied unchanged
from the source Float32 columns; no re-ranking, smoothing or reprojection
is applied. Overviews are for display; use the native resolution for analysis.

## Band definitions

| File / band | Name | Values and interpretation |
| --- | --- | --- |
| habitat / 1 | `habitat_score` | 0–1, arithmetic mean of positive-class predictions from the five spatial-fold models. Higher means more suitable habitat for the training target. |
| habitat / 2 | `habitat_percentile` | 0–1, rank among all eligible Swedish grid cells, using average rank for ties divided by the number of eligible cells. This drives the website map. It is not a probability. |
| quality / 1 | `score_eligible` | 1 = scored; 0 = present in the source dataset but excluded from scoring; 255 = outside dataset / NoData. |
| quality / 2 | `uncertainty_tier` | 1 = low; 2 = medium; 3 = high; 255 = outside dataset / NoData. Excluded cells retain the source category high (3); use quality band 1 to identify them. |

Both habitat bands use **-9999** as NoData, for both excluded and
outside-dataset pixels. Both quality bands use **255** as NoData. Zero is
not a NoData value. All bands have scale 1 and offset 0. Percentiles are
stored as fractions, not 0–100 values.

The habitat score is a classifier output, not an established probability
of finding plants at an arbitrary point or berries on a visit. The percentile
is relative to this Swedish release and is not directly comparable with
percentiles for another species, country or model release.

Eligibility requires finite fold-mean scores and fold disagreement, and at
least 50% observed neighbourhood coverage for each of the six core land-cover
features. It is not a requirement that every ecological predictor is observed.

Uncertainty categories are **heuristics, not confidence intervals**. They use
fold-model disagreement, feature coverage and extrapolation beyond the
training features' 1st–99th percentile ranges:

- Low: eligible, no range exceedance, fold-score standard deviation below its
  national eligible-cell 75th percentile, and mean observed fraction close to 1.
- Medium: eligible, not low, at most 20% of features outside their training
  ranges, disagreement below its 90th percentile, and mean coverage at least 75%.
- High: all remaining cells, including excluded cells.

These categories do not capture every source of error and must not be treated
as independently calibrated error probabilities.

## Model, evaluation and limitations

The model is a seven-leaf HistGradientBoostingClassifier with 156 predictors.
Predictors include summaries of land cover, canopy, soil, soil depth, standing timber
volume and soil moisture in centred 3 × 3 neighbourhoods of 1 km cells.
**1 km is the output spacing, not a claim of independent 1 km ecological
resolution.** Adjacent predictions share environmental information.

Training uses 11,694 NFI survey events from 2015–2024. Public permanent-plot
coordinates are deliberately displaced; the pipeline records 1,131 m
coordinate uncertainty. Environmental vintages are not matched to each survey
year. Some forestry predictors themselves use NFI reference plots: validation
therefore has source coupling and is not fully independent of the predictor
production process. This is a static habitat snapshot, not a 2026 crop forecast
or an assessment of recent local forest changes.

Primary evaluation used five spatial folds with 50 km blocks and nested
spatial selection of boosting iterations. Lingonberry ROC AUC was **0.7213**,
top-20% lift **1.2912**, Brier score **0.1939** and expected calibration error
**0.0070**. These describe held-out NFI predictions, not validation at every
mapped cell. The seven-leaf candidate was selected after an exploratory sweep
on the existing folds; the subsequent nested protocol was frozen before its
evaluation. These are not results from an untouched external test set.



## Sources, attribution and redistribution review

Reviewed 30 October 2026. This is a documented source-terms review, not legal
advice. The following sources belong to the frozen habitat model, unlike the
separate seasonal weather and berry-phenology products.

| Input | Version / role | Terms and evidence |
| --- | --- | --- |
| Swedish NFI, SLU / GBIF Sweden | Presence–absence vegetation archive v1.2, published 12 February 2026; training labels | [Dataset rights](https://www.gbif.se/ipt/resource?r=forestinventory-event): CC0 1.0, explicitly allowing copying, modification, distribution and commercial use. GBIF dataset ID `d59ccafb-251e-46cf-9319-37b58d88e7c5`. |
| Naturvårdsverket NMD | NMD2023 base v2.0 with NMD2018 v1.1 fallback; NMD2023 object height/cover v1.0 | Section 4.1 of all three archived product descriptions explicitly states CC0 and permits reuse, distribution and aggregation. [Official product catalogue](https://www.naturvardsverket.se/verktyg-och-tjanster/kartor-och-karttjanster/nationella-marktackedata/ladda-ner-nationella-marktackedata/). |
| SGU | Soil map 1:25,000–1:100,000 and national soil-depth model | [Official geological-data terms](https://www.sgu.se/produkter-och-tjanster/geologiska-data/om-geologiska-data/licensvillkor/): CC0. |
| Skogsstyrelsen / SLU | Standing timber volume and classified SLU soil moisture | [Official open-data terms](https://www.skogsstyrelsen.se/e-tjanster-och-kartor/karttjanster/geodatatjanster/oppna-data): CC0 unless a product states otherwise. Skogliga grunddata is explicitly listed. The archived SLU moisture product description v1.0 (16 October 2020) states no separate reuse licence; reliance here is on the distributor's general terms, not a product-specific CC0 declaration. No exception was found in the checked documents. |

Archived NMD documents checked: `NMD_Produktbeskrivning_NMD2018Basskikt.pdf`,
`NMD2023_Produktbeskrivning_Basskikt_NMD2023_v2_x.pdf` and
`NMD2023_Produktbeskrivning_tillaggsskikt_Objekthojd_objekttackning_v1_0.pdf`.
The model/source hashes in the manifest identify this frozen output; current
upstream downloads should not be assumed to reproduce it.

Preferred dataset citation:

> Emil Hessman (2026). Bärindex: Lingonberry habitat suitability in Sweden. Model release v4, 23 August 2026. https://xn--brindex-5wa.se/data/

For reproducible analyses, also record the package version and checksum.
A compact map credit may read: "Bärindex / Emil Hessman, CC BY 4.0", linked
to the landing page and licence where practicable.

Emil Hessman's copyright and similar rights, to the extent they apply to the
derived rasters and accompanying documentation, are licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
Reuse, adaptation and redistribution, including commercial reuse, are allowed
under that licence. Give appropriate credit, retain supplied licence and
attribution notices, link to the licence and indicate modifications when sharing.
Attribution does not imply endorsement. The material is provided as-is, without
warranties, as set out in the licence.

This grant does not impose new restrictions on the underlying CC0 data or on
uses that require no permission. The upstream organisations are acknowledged
as sources, not as authors or endorsers of this model output.

## Use and reproduction

Unzip the package and open either TIFF directly in a GIS. Select habitat band 1
for scores or band 2 for ranks. Use `score_eligible == 1` as the analysis mask;
additional uncertainty filtering changes the represented population and should
be reported. Do not interpret missing cells as zero or sum scores as berry yield.

Python example (requires Rasterio):

```python
import rasterio

with rasterio.open("lingonberry-habitat.tif") as dataset:
    score = dataset.read(1, masked=True)
    rank = dataset.read(2, masked=True)
    print(dataset.crs, dataset.transform)
```

The package has no dependency on the website or a live API. In the Bärindex
source checkout, regenerate all three species' packages from the frozen
analytical artifacts with:

```sh
uv run --frozen --directory ml python -m scripts.export_bar_research_packages --package-date 2026-10-30
```

The exporter verifies frozen source checksums, compares every scored TIFF value
and quality/missingness code with the source, and reconstructs all six map PNGs
for each species from the TIFFs. Their SHA-256 hashes and map geometry must
match the audited release. Results are recorded in `manifest.json`. This checks
export fidelity, not the ecological accuracy of the model.

The numerical TIFFs are not website screenshots. The website reprojects the
grid, applies colours and transparency, aggregates the 3 km/8 km display levels,
and quantises click-value ranks to 8 bits. Use habitat band 2 at native resolution
for numerical analysis; visual similarity alone is not a fidelity check.

Given identical inputs, exporter code, package date and software environment,
repeated builds produce byte-identical ZIPs. ZIP timestamps, ordering and
permissions are fixed; the TIFFs use lossless compression with one worker.
The ZIP stores its already-compressed TIFFs without a second compression pass.
Use the dependency lock and the software versions in the manifest; different
GDAL builds or platforms are not guaranteed to produce identical bytes.
This repackages frozen predictions; it does not retrain the models or fetch
current upstream data. The source Parquet and audited reports are prerequisites
and are not included in the public ZIP or necessarily in a Git-only checkout.

`--output-dir` selects a parent directory for all three packages. Repeating a
build accepts identical existing files, but refuses to replace different bytes
under the same version. Use a new `--package-date` when changing a published
delivery, keeping earlier downloads intact. `--stage-web` also stages the ZIPs,
READMEs, manifests and download catalogue locally. Publishing is a separate action.