Basic Usage

This guide covers the fundamental operations for calculating biodiversity units using bngmetric.

Understanding the BNG Metric

The Biodiversity Net Gain metric calculates biodiversity value in standardised “biodiversity units”. The core formula is:

\[\text{Units} = \text{Area} \times \text{Distinctiveness} \times \text{Condition} \times \text{Strategic Significance}\]

Where:

Area: Size in hectares
Distinctiveness: Ecological value of the habitat type (V.Low to V.High)
Condition: Current health/quality of the habitat (Poor to Good)
Strategic Significance: Alignment with local biodiversity priorities

Calculating Baseline Units

The first step in any BNG assessment is calculating the baseline biodiversity value of the site before development.

Using DataFrames

The simplest approach is to use pandas DataFrames:

import pandas as pd
from bngmetric.core_calculations import calculate_bng_from_dataframe

# Define your baseline habitats
baseline = pd.DataFrame({
    'Habitat': [
        'Grassland - Lowland meadows',
        'Woodland - Lowland mixed deciduous woodland',
        'Heathland and shrub - Lowland heathland'
    ],
    'Condition': ['Moderate', 'Good', 'Poor'],
    'Area': [2.5, 1.0, 0.5],
    'Strategic_Significance': [1.15, 1.0, 1.1]
})

total_units = calculate_bng_from_dataframe(baseline)
print(f"Total baseline units: {total_units:.2f}")

Using JAX Arrays Directly

For performance or when integrating with JAX workflows:

import jax.numpy as jnp
from bngmetric.core_calculations import calculate_batched_baseline_bng_units
from bngmetric.constants import HABITAT_TYPE_TO_ID, CONDITION_CATEGORY_TO_ID

# Convert to numerical IDs
habitat_ids = jnp.array([
    HABITAT_TYPE_TO_ID['Grassland - Lowland meadows'],
    HABITAT_TYPE_TO_ID['Woodland - Lowland mixed deciduous woodland']
])
condition_ids = jnp.array([
    CONDITION_CATEGORY_TO_ID['Moderate'],
    CONDITION_CATEGORY_TO_ID['Good']
])
areas = jnp.array([2.5, 1.0])
strategic = jnp.array([1.15, 1.0])

# Calculate units for each parcel
parcel_units = calculate_batched_baseline_bng_units(
    habitat_ids, condition_ids, areas, strategic
)
print(f"Per-parcel units: {parcel_units}")
print(f"Total: {jnp.sum(parcel_units):.2f}")

Available Habitat Types

bngmetric includes all habitat types from the UK Habitat Classification:

from bngmetric.constants import HABITAT_TYPE_TO_ID

# List all available habitats
for habitat in sorted(HABITAT_TYPE_TO_ID.keys()):
    print(habitat)

Condition Categories

The following condition categories are available:

Good
Fairly Good
Moderate
Fairly Poor
Poor
Condition Assessment N/A
N/A - Other

from bngmetric.constants import CONDITION_CATEGORY_TO_ID

print(CONDITION_CATEGORY_TO_ID)
# {'Good': 0, 'Fairly Good': 1, 'Moderate': 2, ...}

Strategic Significance

Strategic significance multipliers reflect alignment with local biodiversity strategies:

1.15: High strategic significance (formally identified in local strategy)
1.10: Medium strategic significance (ecologically desirable location)
1.00: Low strategic significance (not in local strategy)