Enhancement API

The enhancement module provides functions for calculating biodiversity units from habitat enhancement, including condition enhancement, distinctiveness enhancement, and off-site scenarios.

Condition Enhancement (On-site)

For improving condition within the same habitat type.

bngmetric.enhancement.get_enhancement_temporal_multiplier(habitat_id: int, start_condition_id: int, target_condition_id: int) → float

Retrieves the temporal multiplier for enhancement within the same distinctiveness band. Looks up time to target years from the 3D enhancement matrix, then converts to multiplier.

bngmetric.enhancement.get_enhancement_difficulty_multiplier(habitat_id: int) → float

Retrieves the difficulty multiplier for enhancing a given habitat ID.

bngmetric.enhancement.calculate_enhancement_bng_unit(habitat_id: int, start_condition_id: int, target_condition_id: int, area: float, strategic_multiplier: float) → float

Calculates the post-enhancement biodiversity units for a single habitat parcel. This represents the units after enhancement, not the uplift.

For same-distinctiveness enhancement (improving condition within same habitat type).

bngmetric.enhancement.calculate_baseline_unit_for_enhancement(habitat_id: int, start_condition_id: int, area: float, strategic_multiplier: float) → float

Calculates the baseline biodiversity units for a parcel before enhancement. Used to compute the uplift from enhancement.

bngmetric.enhancement.calculate_enhancement_uplift(habitat_id: int, start_condition_id: int, target_condition_id: int, area: float, strategic_multiplier: float) → float

Calculates the net biodiversity uplift from enhancement. Uplift = post-enhancement units - baseline units

bngmetric.enhancement.calculate_batched_enhancement_bng_units(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → Array

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

Original documentation:

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

bngmetric.enhancement.calculate_batched_enhancement_uplift(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → Array

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

Original documentation:

Calculates the net biodiversity uplift from enhancement for multiple parcels. Inputs should be JAX arrays of the same length.

bngmetric.enhancement.calculate_enhancement_bng_from_dataframe(df: DataFrame) → float

Calculates total post-enhancement biodiversity units from a pandas DataFrame.

Expected columns:

• Habitat: habitat type string

• Start_Condition: condition before enhancement

• Target_Condition: condition after enhancement

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

bngmetric.enhancement.calculate_enhancement_uplift_from_dataframe(df: DataFrame) → float

Calculates total net biodiversity uplift from enhancement from a pandas DataFrame.

Expected columns:

• Habitat: habitat type string

• Start_Condition: condition before enhancement

• Target_Condition: condition after enhancement

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

bngmetric.enhancement.calculate_total_enhancement_units_from_jax_arrays(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → float

Calculates the sum of post-enhancement biodiversity units from JAX arrays. This is the function to differentiate for sensitivity analysis.

bngmetric.enhancement.calculate_total_enhancement_uplift_from_jax_arrays(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → float

Calculates the sum of net biodiversity uplift from JAX arrays. This is the function to differentiate for sensitivity analysis on uplift.

Distinctiveness Enhancement

For enhancing to a higher distinctiveness habitat within the same broad type.

bngmetric.enhancement.get_distinctiveness_enhancement_temporal_multiplier(target_habitat_id: int, target_condition_id: int) → float

Retrieves the temporal multiplier for distinctiveness enhancement.

This is used when enhancing from a lower distinctiveness habitat to a higher distinctiveness habitat (within the same broad habitat type).

The temporal lookup is based on the target habitat and target condition. The starting condition of the lower distinctiveness habitat is assumed to match the target condition.

bngmetric.enhancement.calculate_distinctiveness_enhancement_bng_unit(baseline_habitat_id: int, baseline_condition_id: int, target_habitat_id: int, target_condition_id: int, area: float, strategic_multiplier: float) → float

Calculates the post-enhancement biodiversity units for distinctiveness enhancement.

This is for enhancing from a lower distinctiveness habitat to a higher distinctiveness habitat (within the same broad habitat type).

Parameters:

• baseline_habitat_id – ID of the original (lower distinctiveness) habitat

• baseline_condition_id – Condition ID of the baseline habitat

• target_habitat_id – ID of the target (higher distinctiveness) habitat

• target_condition_id – Condition ID of the target habitat

• area – Area in hectares

• strategic_multiplier – Strategic significance multiplier

bngmetric.enhancement.calculate_distinctiveness_enhancement_uplift(baseline_habitat_id: int, baseline_condition_id: int, target_habitat_id: int, target_condition_id: int, area: float, strategic_multiplier: float) → float

Calculates the net biodiversity uplift from distinctiveness enhancement.

Uplift = post-enhancement units - baseline units

Parameters:

• baseline_habitat_id – ID of the original (lower distinctiveness) habitat

• baseline_condition_id – Condition ID of the baseline habitat

• target_habitat_id – ID of the target (higher distinctiveness) habitat

• target_condition_id – Condition ID of the target habitat

• area – Area in hectares

• strategic_multiplier – Strategic significance multiplier

bngmetric.enhancement.calculate_batched_distinctiveness_enhancement_bng_units(baseline_habitat_ids: Array, baseline_condition_ids: Array, target_habitat_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → Array

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

Original documentation:

Calculates post-enhancement biodiversity units for multiple distinctiveness enhancement parcels in a batch.

bngmetric.enhancement.calculate_batched_distinctiveness_enhancement_uplift(baseline_habitat_ids: Array, baseline_condition_ids: Array, target_habitat_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → Array

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

Original documentation:

Calculates the net biodiversity uplift from distinctiveness enhancement for multiple parcels.

bngmetric.enhancement.calculate_distinctiveness_enhancement_bng_from_dataframe(df: DataFrame) → float

Calculates total post-enhancement biodiversity units from distinctiveness enhancement using a pandas DataFrame.

Expected columns:

• Baseline_Habitat: baseline (lower distinctiveness) habitat type string

• Baseline_Condition: condition of baseline habitat

• Target_Habitat: target (higher distinctiveness) habitat type string

• Target_Condition: condition of target habitat

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

bngmetric.enhancement.calculate_distinctiveness_enhancement_uplift_from_dataframe(df: DataFrame) → float

Calculates total net biodiversity uplift from distinctiveness enhancement using a pandas DataFrame.

Expected columns:

• Baseline_Habitat: baseline (lower distinctiveness) habitat type string

• Baseline_Condition: condition of baseline habitat

• Target_Habitat: target (higher distinctiveness) habitat type string

• Target_Condition: condition of target habitat

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

bngmetric.enhancement.calculate_total_distinctiveness_enhancement_units_from_jax_arrays(baseline_habitat_ids: Array, baseline_condition_ids: Array, target_habitat_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → float

Calculates the sum of post-enhancement biodiversity units from JAX arrays for distinctiveness enhancement.

bngmetric.enhancement.calculate_total_distinctiveness_enhancement_uplift_from_jax_arrays(baseline_habitat_ids: Array, baseline_condition_ids: Array, target_habitat_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array) → float

Calculates the sum of net biodiversity uplift from JAX arrays for distinctiveness enhancement.

Off-site Enhancement

For off-site enhancement with spatial risk multiplier.

bngmetric.enhancement.get_spatial_risk_multiplier(spatial_risk_category_id: int) → float

Retrieves the spatial risk multiplier for off-site compensation.

bngmetric.enhancement.calculate_offsite_enhancement_bng_unit(habitat_id: int, start_condition_id: int, target_condition_id: int, area: float, strategic_multiplier: float, spatial_risk_category_id: int) → float

Calculates the post-enhancement biodiversity units for a single off-site condition enhancement parcel. Includes spatial risk multiplier.

bngmetric.enhancement.calculate_offsite_enhancement_uplift(habitat_id: int, start_condition_id: int, target_condition_id: int, area: float, strategic_multiplier: float, spatial_risk_category_id: int) → float

Calculates the net biodiversity uplift from off-site enhancement. Uplift = post-enhancement units - baseline units Note: Baseline units do NOT include spatial risk (they represent existing value).

bngmetric.enhancement.calculate_batched_offsite_enhancement_bng_units(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → Array

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

Original documentation:

Calculates off-site enhancement biodiversity units for multiple parcels.

bngmetric.enhancement.calculate_batched_offsite_enhancement_uplift(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → Array

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

Original documentation:

Calculates off-site enhancement uplift for multiple parcels.

bngmetric.enhancement.calculate_offsite_enhancement_bng_from_dataframe(df: DataFrame) → float

Calculates total off-site enhancement biodiversity units from a DataFrame.

Expected columns:

• Habitat: habitat type string

• Start_Condition: condition before enhancement

• Target_Condition: condition after enhancement

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

• Spatial_Risk: spatial risk category string

bngmetric.enhancement.calculate_offsite_enhancement_uplift_from_dataframe(df: DataFrame) → float

Calculates total off-site enhancement uplift from a DataFrame.

Expected columns:

• Habitat: habitat type string

• Start_Condition: condition before enhancement

• Target_Condition: condition after enhancement

• Area: area in hectares

• Strategic_Significance: strategic significance multiplier

• Spatial_Risk: spatial risk category string

bngmetric.enhancement.calculate_total_offsite_enhancement_units_from_jax_arrays(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → float

Calculates the sum of off-site enhancement biodiversity units from JAX arrays.

bngmetric.enhancement.calculate_total_offsite_enhancement_uplift_from_jax_arrays(habitat_ids: Array, start_condition_ids: Array, target_condition_ids: Array, areas: Array, strategic_multipliers: Array, spatial_risk_category_ids: Array) → float

Calculates the sum of off-site enhancement uplift from JAX arrays.

DataFrame Column Requirements

Condition Enhancement

• Habitat: Habitat type string

• Start_Condition: Condition before enhancement

• Target_Condition: Condition after enhancement

• Area: Area in hectares

• Strategic_Significance: Strategic significance multiplier

Distinctiveness Enhancement

• Baseline_Habitat: Original (lower distinctiveness) habitat type

• Baseline_Condition: Condition of baseline habitat

• Target_Habitat: Target (higher distinctiveness) habitat type

• Target_Condition: Condition of target habitat

• Area: Area in hectares

• Strategic_Significance: Strategic significance multiplier

Off-site Enhancement

All condition enhancement columns plus:

• Spatial_Risk: Spatial risk category string