improver.fire_weather package

improver.fire_weather package#

Submodules#

Module contents#

Canadian Forest Fire Weather Index System components.

class FireWeatherBase[source]#

Bases: BasePlugin

Abstract base class for the Canadian Forest Fire Weather Index (CFFWI) System calculations.

This class provides common functionality for all fire weather components, including:

  • Standardised cube loading and validation

  • Fixed unit conversions for all cube types (non-configurable)

  • Output cube creation

  • Process orchestration

The CFFWI system requires specific units for all calculations. These are fixed and cannot be overridden:

  • Temperature: degrees Celsius (Celsius)

  • Precipitation: millimeters (mm)

  • Relative humidity: dimensionless fraction (1)

  • Wind speed: kilometers per hour (km/h)

  • All fire weather indices: dimensionless (1)

Subclasses must define class attributes:

  • METADATA_SOURCE_CUBE: The name of the input cube from which the

    metadata will be sourced for the output_cube. For downstream datasets that take iterative datasets as input this should be the iterative dataset.

  • INPUT_CUBE_NAMES: List of standard names for required input cubes

  • OUTPUT_CUBE_NAME: Standard name for the output cube

  • REQUIRES_MONTH: Boolean indicating if month parameter is required

Subclasses must implement:

  • _calculate(): Method that performs the actual calculation

INPUT_ATTRIBUTE_MAPPINGS: dict[str, str] = {}#
INPUT_CUBE_NAMES: list[str] = []#
METADATA_SOURCE_CUBE: str = ''#
OUTPUT_CUBE_NAME: str = ''#
REQUIRES_MONTH: bool = False#
VALID_OUTPUT_RANGE: tuple[float | None, float | None] | None = None#
_REQUIRED_UNITS: dict[str, str] = {'build_up_index': '1', 'drought_code': '1', 'duff_moisture_code': '1', 'fine_fuel_moisture_code': '1', 'fire_severity_index': '1', 'fire_weather_index': '1', 'initial_spread_index': '1', 'input_dc': '1', 'input_dmc': '1', 'input_ffmc': '1', 'precipitation': 'mm', 'relative_humidity': '1', 'temperature': 'Celsius', 'wind_speed': 'km/h'}#
_VALID_RANGES: dict[str, tuple[float | None, float | None]] = {'build_up_index': (0.0, 500.0), 'fire_weather_index': (0.0, 100.0), 'initial_spread_index': (0.0, 100.0), 'input_dc': (0.0, None), 'input_dmc': (0.0, None), 'input_ffmc': (0.0, 101.0), 'precipitation': (0.0, None), 'relative_humidity': (0.0, 101.0), 'temperature': (-100.0, 100.0), 'wind_speed': (0.0, None)}#
_abc_impl = <_abc._abc_data object>#
abstractmethod _calculate()[source]#

Perform the fire weather calculation.

This method must be implemented by subclasses to perform the specific calculation logic for that component.

Raises:

NotImplementedError – This method must be implemented by subclasses.

Return type:

ndarray

_get_attribute_name(standard_name)[source]#

Convert a cube standard name to an attribute name.

Parameters:

standard_name (str) – The cube’s standard name

Return type:

str

Returns:

The attribute name to use for storing the cube

Examples

“air_temperature” -> “temperature” “lwe_thickness_of_precipitation_amount” -> “precipitation” “fine_fuel_moisture_code” -> “input_ffmc” (if INPUT_ATTRIBUTE_MAPPINGS is set)

_make_output_cube(data, template_cube=None)[source]#

Creates an output cube with specified data and metadata.

For classes that use precipitation data (FFMC, DMC, DC), automatically updates the ‘forecast_reference_time’ and ‘time’ coordinates from the precipitation cube to reflect the 24-hour accumulation period.

Parameters:

  • data (ndarray) – The output data array

  • template_cube (Cube | None) – The cube to use as a template for metadata. If None, uses the first input cube. Defaults to None

Return type:

Cube

Returns:

The output cube containing the output data with proper metadata and coordinates.

_set_metadata(output_cube)[source]#

Add metadata to the output_cube, sourced from either the INPUT_ATTRIBUTE_MAPPING of the METADATA_SOURCE_CUBE, the METADATA_SOURCE_CUBE attribute itself, or a standard name stripped of common prefixes and suffixes.

Parameters:

output_cube (Cube) – The output cube

Raises:

NotImplementedError – If METADATA_SOURCE_CUBE is not defined or the named cube does not contain the necessary metadata

Return type:

None

Note

Metadata is required on all fire weather datasets to monitor the build up period of the iterative datasets (Fine Fuel Moisture Code, Duff Moisture Code and Drought Code).

These values are also added to datasets which are not iterative but which take iterative datasets as inputs, because the context of when the build up period was begun and whether the data is ready is important for stakeholders. These downstream datasets include the Initial Spread Index, the Build Up Index, the Fire Weather Index and the Fire Severity Index.

_validate_input_range(cube, attr_name)[source]#

Validate that input data falls within expected physical ranges. If values fall outside the valid range for this input type, then emit a warning.

Parameters:

  • cube (Cube) – The input cube to validate

  • attr_name (str) – The attribute name for the cube

Warns:

UserWarning – If any values fall outside the valid range for this input type

Raises:

ValueError – If data contains NaN or Inf values

Return type:

None

_validate_output_range(output_cube)[source]#

Check if output values fall within expected ranges and issue warnings if not.

Uses the VALID_OUTPUT_RANGE class attribute if defined.

Parameters:

output_cube (Cube) – The output cube to validate

Warns:

UserWarning – If output contains NaN, Inf, or values outside expected ranges

Return type:

None

load_input_cubes(cubes, month=None, input_cube_names=None)[source]#

Loads the required input cubes for the calculation. These are stored internally as Cube objects.

Parameters:

  • cubes (tuple[Cube, ...] | CubeList) – Input cubes containing the necessary data.

  • month (int | None) – Month of the year (1-12), required only if REQUIRES_MONTH is True. Defaults to None.

  • input_cube_names (list[str]) – A list of input_cube_names if different from self.INPUT_CUBE_NAMES Defaults to None.

Raises:

ValueError – If the number of cubes does not match the expected number, if month is required but not provided, or if month is out of range.

process(*cubes, month=None)[source]#

Calculate the fire weather component.

Parameters:

  • cubes (Union[Cube, CubeList]) – Input cubes as specified by INPUT_CUBE_NAMES

  • month (int | None) – Month parameter (1-12), required only if REQUIRES_MONTH is True Defaults to None.

Return type:

Cube

Returns:

The calculated output cube.

Warns:

UserWarning – If output values fall outside typical expected ranges

class IterativeFireWeatherBase[source]#

Bases: FireWeatherBase

Iterative abstract base class for Iterative Fire Weather calculations.

Extends common functionality provided by FireWeatherBase to provide iterative functionality for Fire Weather values that take the previous days outputs as an input to the current days calculation.

Subclasses must define class attributes:

  • INPUT_CUBE_NAMES: List of standard names for required input cubes

  • OUTPUT_CUBE_NAME: Standard name for the output cube

  • REQUIRES_MONTH: Boolean indicating if month parameter is required

  • STARTING_VALUE: Integer providing starting value for iterative

    calculations in the absense of input data for the preceding day.

  • LAG_TIME: Integer representing the number of days needed after

    starting calculations from the STARTING_VALUE, before outputs should be considered scientifically valid.

  • METADATA_SOURCE_CUBE: The name of the input cube from which the

    metadata will be sourced for the output_cube. For iterative fire weather classes this must match the OUTPUT_CUBE_NAME.

Subclasses must implement:

  • _calculate(): Method that performs the actual calculation

LAG_TIME: int#
REFERENCE_CUBE_NAME = 'air_temperature'#
STARTING_VALUE: int#
_abc_impl = <_abc._abc_data object>#
_initialise_baseline_cube(cubes)[source]#

Create a baseline cube from the reference cube and set iteration_start_date.

Parameters:

cubes (tuple[Cube, ...] | CubeList) – Input cubes as specified by INPUT_CUBE_NAMES except OUTPUT_CUBE_NAME

Raises:

  • ValueError – If the REFERENCE_CUBE is not present in cubes

  • ValueError – If the REFERENCE_CUBE has a iteration_start_date attribute

Return type:

Cube

_record_lag_time_state(cube)[source]#

Check metadata attributes and warn if LAG_TIME has not been exceeded.

Parameters:

cube (Cube) – The output cube with metadata values to compare to LAG_TIME

Raises:

ValueError – If cube has missing metadata attributes

Warns:

UserWarning – If runtime is less than LAG_TIME

Return type:

None

process(*cubes, month=None, initialise=False)[source]#
Parameters:

  • cubes (Union[Cube, CubeList]) – One or more input cubes as specified by INPUT_CUBE_NAMES. When initialise is True cubes should exclude the OUTPUT_CUBE_NAME, which should otherwise be given as the iterative input.

  • month (int | None) – Month parameter (1-12), required only if REQUIRES_MONTH is True

  • initialise (bool) – True when starting the iterative process else False

Return type:

Cube

Returns:

The calculated output cube.

Warns:

UserWarning – If output values fall outside typical expected ranges

Raises:

ValueError – If an output cube is given with initialise=True