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.

Confusion Matrix

firebench.metrics.confusion_matrix.binary_performance.binary_accuracy(bcm: ndarray)[source]

Compute the binary classification accuracy from a 2x2 confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

where: - TN: True Negatives - FP: False Positives - FN: False Negatives - TP: True Positives

Accuracy is defined as the proportion of correct predictions out of all predictions:

accuracy = (TP + TN) / (TP + TN + FP + FN)

Parameters:

bcm (numpy.ndarray)

Returns:

The accuracy value, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_f_score(bcm: ndarray)[source]

Compute the F1-score from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

The F1-score is the harmonic mean of precision and recall:

F1 = 2 * (precision * recall) / (precision + recall)

It provides a single metric that balances false positives and false negatives.

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The F1-score, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_false_positive_rate(bcm: ndarray)[source]

Compute the false positive rate (FPR) from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

False Positive Rate measures how often negative samples are incorrectly classified as positive:

FPR = FP / (FP + TN)

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The false positive rate, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_negative_predicted_value(bcm: ndarray)[source]

Compute the negative predictive value (NPV) from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

Negative Predictive Value measures the proportion of predicted negatives that are actually negative:

NPV = TN / (TN + FN)

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The negative predictive value, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_precision(bcm: ndarray)[source]

Compute the precision from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

where: - TN: True Negatives - FP: False Positives - FN: False Negatives - TP: True Positives

Precision (also called Positive Predictive Value, PPV) measures the proportion of positive predictions that are correct:

precision = TP / (TP + FP)

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The precision value, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_recall_rate(bcm: ndarray)[source]

Compute the recall rate (true positive rate, TPR) from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

Recall, also called sensitivity, measures how many actual positives are correctly identified:

recall = TP / (TP + FN)

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The recall value, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.binary_performance.binary_specificity(bcm: ndarray)[source]

Compute the specificity (true negative rate, TNR) from a 2x2 binary confusion matrix.

This function expects a confusion matrix of the form:

[[TN, FP],

[FN, TP]]

Specificity measures the proportion of actual negatives that are correctly identified:

specificity = TN / (TN + FP)

Parameters:

bcm (numpy.ndarray) – A 2x2 array representing the binary confusion matrix.

Returns:

The specificity value, ranging from 0.0 to 1.0.

Return type:

float

firebench.metrics.confusion_matrix.utils.binary_cm(y_true, y_pred)[source]

Compute the binary confusion matrix for two boolean-compatible arrays.

This function compares predicted binary values against ground-truth binary values and computes the 2x2 confusion matrix in the conventional layout:

[[TN, FP],

[FN, TP]]

Both inputs must be broadcastable to the same shape and must contain values that can be interpreted as booleans (e.g., {0,1}, {False,True}, or arrays castable to bool).

The logic is as follows: - True Negative (TN): elements where both y_true and y_pred are False. - False Positive (FP): elements where y_true is False but y_pred is True. - False Negative (FN): elements where y_true is True but y_pred is False. - True Positive (TP): elements where both y_true and y_pred are True.

Parameters:

  • y_true (array_like) – Ground-truth binary values. Must be castable to a boolean NumPy array.

  • y_pred (array_like) – Predicted binary values. Must be castable to a boolean NumPy array.

Returns:

A 2x2 NumPy array of integers arranged as:
[[TN, FP],

[FN, TP]]

Return type:

numpy.ndarray

Examples

>>> binary_confusion_matrix_matrix([0, 1, 1, 0], [0, 1, 0, 0])
array([[2, 0],
       [1, 1]])