Creation API

The creation module provides functions for calculating biodiversity units from habitat creation, including both on-site and off-site scenarios.

On-site Creation Functions

bngmetric.creation.get_temporal_multiplier(habitat_id: int, condition_id: int) → float[source]

Retrieves the temporal multiplier for a given number of years by looking up in the creation multipliers matrix.

bngmetric.creation.get_difficulty_multiplier(habitat_id: int) → float[source]

Retrieves the difficulty multiplier for creating a given habitat ID.

bngmetric.creation.calculate_creation_bng_unit(habitat_id: int, condition_id: int, area: float, strategic_multiplier: float) → float[source]

Calculates the biodiversity units for a single habitat creation parcel.

bngmetric.creation.calculate_batched_creation_bng_units(habitat_ids: Array, condition_ids: Array, areas: Array, strategic_multipliers: Array) → Array[source]

Vectorized version of calculate_batched_creation_bng_units. Takes similar arguments as calculate_batched_creation_bng_units but with additional array axes over which calculate_batched_creation_bng_units is mapped.

Original documentation:

Calculates creation biodiversity units for multiple habitat parcels in a batch. Inputs should be JAX arrays of the same length.

bngmetric.creation.calculate_creation_bng_from_dataframe(df: DataFrame) → float[source]

Calculates total creation biodiversity units from a pandas DataFrame. For on-site creation (no spatial risk multiplier).

bngmetric.creation.calculate_total_creation_units_from_jax_arrays(habitat_ids: Array, condition_ids: Array, areas: Array, strategic_multipliers: Array) → float[source]

Calculates the sum of on-site creation biodiversity units from JAX arrays. This is the function to differentiate for sensitivity analysis.

Off-site Creation Functions

bngmetric.creation.get_spatial_risk_multiplier(spatial_risk_category_id: int) → float[source]

Retrieves the spatial risk multiplier for off-site compensation.

bngmetric.creation.calculate_offsite_creation_bng_unit(habitat_id: int, condition_id: int, area: float, strategic_multiplier: float, spatial_risk_category_id: int) → float[source]

Calculates the biodiversity units for a single off-site habitat creation parcel. Includes spatial risk multiplier based on distance from impact site.

Parameters:

  • habitat_id – ID of the habitat being created

  • condition_id – Target condition ID

  • area – Area in hectares

  • strategic_multiplier – Strategic significance multiplier

  • spatial_risk_category_id – Spatial risk category (0=Inside LPA, 1=Neighbouring, 2=Beyond)

bngmetric.creation.calculate_batched_offsite_creation_bng_units(habitat_ids: Array, condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → Array[source]

Vectorized version of calculate_batched_offsite_creation_bng_units. Takes similar arguments as calculate_batched_offsite_creation_bng_units but with additional array axes over which calculate_batched_offsite_creation_bng_units is mapped.

Original documentation:

Calculates off-site creation biodiversity units for multiple parcels in a batch. Inputs should be JAX arrays of the same length.

bngmetric.creation.calculate_offsite_creation_bng_from_dataframe(df: DataFrame) → float[source]

Calculates total off-site creation biodiversity units from a pandas DataFrame.

Expected columns:

  • Habitat: habitat type string

  • Condition: target condition string

  • Area: area in hectares

  • Strategic_Significance: strategic significance multiplier

  • Spatial_Risk: spatial risk category string (‘Inside LPA/NCA’, ‘Neighbouring LPA/NCA’, ‘Beyond neighbouring LPA/NCA’)

bngmetric.creation.calculate_total_offsite_creation_units_from_jax_arrays(habitat_ids: Array, condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → float[source]

Calculates the sum of off-site creation biodiversity units from JAX arrays. This is the function to differentiate for sensitivity analysis.

DataFrame Column Requirements

On-site Creation

  • Habitat: Habitat type string (must match HABITAT_TYPE_TO_ID keys)

  • Condition: Target condition string

  • Area: Area in hectares

  • Strategic_Significance: Strategic significance multiplier (1.0, 1.1, or 1.15)

Off-site Creation

All on-site columns plus:

  • Spatial_Risk: One of:

    • 'Inside LPA/NCA' (multiplier = 1.0)

    • 'Neighbouring LPA/NCA' (multiplier = 0.75)

    • 'Beyond neighbouring LPA/NCA' (multiplier = 0.5)