firebench.metrics

Perimeters

firebench.metrics.perimeter.shape_index.jaccard_binary(mask1: ndarray, mask2: ndarray) → float[source]

Compute the Jaccard Index (Intersection over Union) between two binary fire masks.

Parameters:

  • mask1 (np.ndarray) – First binary mask (burned = 1, unburned = 0).

  • mask2 (np.ndarray) – Second binary mask of the same shape.

Returns:

Jaccard index (IoU) between the two masks. A value in [0, 1], where:

  • 1.0 indicates perfect match,

  • 0.0 indicates no overlap.

Return type:

float

Raises:

ValueError – If the two input masks do not have the same shape.

Notes

Assumes both inputs are co-registered binary masks of equal shape, where burned areas are encoded as 1 and unburned as 0.

firebench.metrics.perimeter.shape_index.jaccard_polygon(polygon1: GeoDataFrame, polygon2: GeoDataFrame, projection: str = 'EPSG:5070') → float[source]

Compute the Intersection over Union (IoU), also known as the Jaccard Index, between two fire perimeters.

The perimeters are assumed to be geospatial polygons (e.g., shapefiles or KMZ imports via GeoPandas). Internally, both input geometries are reprojected to an equal-area projection before computing the metric.

Geometries of different types may be dropped during overlay; to ensure all area-bearing geometries are retained, keep_geom_type=False is used in both intersection and union operations.

Parameters:

  • polygon1 (geopandas.GeoDataFrame) – First perimeter geometry, must be a valid polygon or multipolygon layer.

  • polygon2 (geopandas.GeoDataFrame) – Second perimeter geometry to compare against polygon1.

  • projection (str, optional) –

    EPSG code string of an equal-area CRS used for area calculation. Default is “EPSG:5070”.

    Recommended projections:

    • USA (CONUS): “EPSG:5070”

    • Europe: “EPSG:3035”

    • Canada: “EPSG:102001”

    • Global: “EPSG:6933”

Returns:

Jaccard index (IoU) between the two geometries. A value in [0, 1], where:

  • 1.0 indicates perfect overlap,

  • 0.0 indicates no overlap.

Return type:

float

Raises:

ValueError – If the projection string is not in the allowed list of equal-area projections.

Notes

It is strongly recommended to use only valid, topologically correct polygons.

firebench.metrics.perimeter.shape_index.sorensen_dice_binary(mask1: ndarray, mask2: ndarray) → float[source]

Compute the Sorensen–Dice coefficient between two binary fire masks.

Parameters:

  • mask1 (np.ndarray) – First binary mask (burned = 1, unburned = 0).

  • mask2 (np.ndarray) – Second binary mask of the same shape.

Returns:

Sorensen–Dice index between the two masks. A value in [0, 1], where:

  • 1.0 indicates perfect match,

  • 0.0 indicates no overlap.

Return type:

float

Raises:

ValueError – If the two input masks do not have the same shape.

Notes

Assumes both inputs are co-registered binary masks of equal shape, where burned areas are encoded as 1 and unburned as 0.

firebench.metrics.perimeter.shape_index.sorensen_dice_polygon(polygon1: GeoDataFrame, polygon2: GeoDataFrame, projection: str = 'EPSG:5070') → float[source]

Compute the Sorensen-Dice index between two fire perimeters.

The perimeters are assumed to be geospatial polygons (e.g., shapefiles or KMZ imports via GeoPandas). Internally, both input geometries are reprojected to an equal-area projection before computing the metric.

Geometries of different types may be dropped during overlay; to ensure all area-bearing geometries are retained, keep_geom_type=False is used in the intersection operation.

Parameters:

  • polygon1 (geopandas.GeoDataFrame) – First perimeter geometry, must be a valid polygon or multipolygon layer.

  • polygon2 (geopandas.GeoDataFrame) – Second perimeter geometry to compare against polygon1.

  • projection (str, optional) –

    EPSG code string of an equal-area CRS used for area calculation. Default is “EPSG:5070”.

    Recommended projections:

    • USA (CONUS): “EPSG:5070”

    • Europe: “EPSG:3035”

    • Canada: “EPSG:102001”

    • Global: “EPSG:6933”

Returns:

Sorensen-Dice index between the two geometries. A value in [0, 1], where:

  • 1.0 indicates perfect overlap,

  • 0.0 indicates no overlap.

Return type:

float

Raises:

ValueError – If the projection string is not in the allowed list of equal-area projections.

Notes

It is strongly recommended to use only valid, topologically correct polygons.