xclim.indices.fire package

Fire Indices Submodule

Submodules

xclim.indices.fire._cffwis module

Canadian Forest Fire Weather Index System

This submodule defines the xclim.indices.fire.fire_season(), xclim.indices.fire.drought_code() and xclim.indices.fire.cffwis_indices() indices, which are used by the eponym indicators. Users should read this module’s documentation and the one of fire_weather_ufunc(). They should also consult the information available at Natural Resources Canada [n.d.].

First adapted from Matlab code CalcFWITimeSeriesWithStartup.m from GFWED [Wang et al., 2015] made for using MERRA2 data, which was a translation of FWI.vba of the Canadian Fire Weather Index system. Then, updated and synchronized with the R code of the cffdrs package. When given the correct parameters, the current code has an error below 3% when compared with the Field et al. [2015] data. The cffdrs R package is different from the original 1982 implementation, and so is xclim.

Parts of the code and of the documentation in this submodule are directly taken from Cantin et al. [2014] which was published with the GPLv2 license.

Fire season

Fire weather indexes are iteratively computed, each day’s value depending on the previous day indexes. Additionally and optionally, the codes are “shut down” (set to NaN) in winter. There are a few ways of computing this shut down and the subsequent spring start-up. The fire_season function allows for full control of that, replicating the fireSeason method in the R package. It produces a mask to be given a season_mask in the indicators. However, the fire_weather_ufunc and the indicators also accept a season_method parameter so the fire season can be computed inside the iterator. Passing season_method=None switches to an “always on” mode replicating the fire method of the R package.

The fire season determination is based on three consecutive daily maximum temperature thresholds [Lawson and Armitage, 2008, Wotton and Flannigan, 1993]. A “GFWED” method is also implemented. There, the 12h LST temperature is used instead of the daily maximum. The current implementation is slightly different from the description in Field et al. [2015], but it replicates the Matlab code when temp_start_thresh and temp_end_thresh are both set to 6 degC. In xclim, the number of consecutive days, the start and end temperature thresholds and the snow depth threshold can all be modified.

Overwintering

Additionally, overwintering of the drought code is also directly implemented in fire_weather_ufunc(). The last drought_code of the season is kept in “winter” (where the fire season mask is False) and the precipitation is accumulated until the start of the next season. The first drought code is computed as a function of these instead of using the default DCStart value. Parameters to _overwintering_drought_code() are listed below. The code for the overwintering is based on McElhinny et al. [2020], Van Wagner [1985].

Finally, a mechanism for dry spring starts is implemented. For now, it is slightly different from what the GFWED, uses, but seems to agree with the state of the science of the CFS. When activated, the drought code and Duff-moisture codes are started in spring with a value that is function of the number of days since the last significant precipitation event. The conventional start value increased by that number of days times a “dry start” factor. Parameters are controlled in the call of the indices and fire_weather_ufunc(). Overwintering of the drought code overrides this mechanism if both are activated. GFWED use a more complex approach with an added check on the previous day’s snow cover for determining “dry” points. Moreover, there, the start values are only the multiplication of a factor to the number of dry days.

Examples

The current literature seems to agree that climate-oriented series of the fire weather indexes should be computed using only the longest fire season of each year and activating the overwintering of the drought code and the “dry start” for the duff-moisture code. The following example uses reasonable parameters when computing over all of Canada.

Note

Here the example snippets use the _indices_ defined in this very module, but we always recommend using the _indicators_ defined in the xclim.atmos module.

>>> ds = open_dataset("ERA5/daily_surface_cancities_1990-1993.nc")
>>> ds = ds.assign(
...     hurs=xclim.atmos.relative_humidity_from_dewpoint(ds=ds),
...     tas=xclim.core.units.convert_units_to(ds.tas, "degC"),
...     pr=xclim.core.units.convert_units_to(ds.pr, "mm/d"),
...     sfcWind=xclim.atmos.wind_speed_from_vector(ds=ds)[0],
... )
>>> season_mask = fire_season(
...     tas=ds.tas,
...     method="WF93",
...     freq="YS",
...     # Parameters below are at their default values, but listed here for explicitness.
...     temp_start_thresh="12 degC",
...     temp_end_thresh="5 degC",
...     temp_condition_days=3,
... )
>>> out_fwi = cffwis_indices(
...     tas=ds.tas,
...     pr=ds.pr,
...     hurs=ds.hurs,
...     sfcWind=ds.sfcWind,
...     lat=ds.lat,
...     season_mask=season_mask,
...     overwintering=True,
...     dry_start="CFS",
...     prec_thresh="1.5 mm/d",
...     dmc_dry_factor=1.2,
...     # Parameters below are at their default values, but listed here for explicitness.
...     carry_over_fraction=0.75,
...     wetting_efficiency_fraction=0.75,
...     dc_start=15,
...     dmc_start=6,
...     ffmc_start=85,
... )

Similarly, the next lines calculate the fire weather indexes, but according to the parameters and options used in NASA’s GFWED datasets. Here, no need to split the fire season mask from the rest of the computation as _all_ seasons are used, even the very short shoulder seasons.

>>> ds = open_dataset("FWI/GFWED_sample_2017.nc")
>>> out_fwi = cffwis_indices(
...     tas=ds.tas,
...     pr=ds.prbc,
...     snd=ds.snow_depth,
...     hurs=ds.rh,
...     sfcWind=ds.sfcwind,
...     lat=ds.lat,
...     season_method="GFWED",
...     overwintering=False,
...     dry_start="GFWED",
...     temp_start_thresh="6 degC",
...     temp_end_thresh="6 degC",
...     # Parameters below are at their default values, but listed here for explicitness.
...     temp_condition_days=3,
...     snow_condition_days=3,
...     dc_start=15,
...     dmc_start=6,
...     ffmc_start=85,
...     dmc_dry_factor=2,
... )
xclim.indices.fire._cffwis.build_up_index(dmc, dc)[source]

Build-up index.

Parameters:

  • dmc (array) – Duff moisture code.

  • dc (array) – Drought code.

Returns:

array – Build up index.

xclim.indices.fire._cffwis.cffwis_indices(tas, pr, sfcWind, hurs, lat, snd=None, ffmc0=None, dmc0=None, dc0=None, season_mask=None, season_method=None, overwintering=False, dry_start=None, initial_start_up=True, **params)[source]

Canadian Fire Weather Index System indices.

Computes the 6 fire weather indexes as defined by the Canadian Forest Service: the Drought Code, the Duff-Moisture Code, the Fine Fuel Moisture Code, the Initial Spread Index, the Build Up Index and the Fire Weather Index.

Parameters:

  • tas (xr.DataArray) – Noon temperature.

  • pr (xr.DataArray) – Rain fall in open over previous 24 hours, at noon.

  • sfcWind (xr.DataArray) – Noon wind speed.

  • hurs (xr.DataArray) – Noon relative humidity.

  • lat (xr.DataArray) – Latitude coordinate

  • snd (xr.DataArray) – Noon snow depth, only used if season_method=’LA08’ is passed.

  • ffmc0 (xr.DataArray) – Initial values of the fine fuel moisture code.

  • dmc0 (xr.DataArray) – Initial values of the Duff moisture code.

  • dc0 (xr.DataArray) – Initial values of the drought code.

  • season_mask (xr.DataArray, optional) – Boolean mask, True where/when the fire season is active.

  • season_method ({None, “WF93”, “LA08”, “GFWED”}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given.

  • overwintering (bool) – Whether to activate DC overwintering or not. If True, either season_method or season_mask must be given.

  • dry_start ({None, ‘CFS’, ‘GFWED’}) – Whether to activate the DC and DMC “dry start” mechanism or not, see fire_weather_ufunc().

  • initial_start_up (bool) – If True (default), gridpoints where the fire season is active on the first timestep go through a start_up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points.

  • params – Any other keyword parameters as defined in fire_weather_ufunc() and in default_params.

Return type:

tuple[DataArray, DataArray, DataArray, DataArray, DataArray, DataArray]

Returns:

  • DC (xr.DataArray, [dimensionless])

  • DMC (xr.DataArray, [dimensionless])

  • FFMC (xr.DataArray, [dimensionless])

  • ISI (xr.DataArray, [dimensionless])

  • BUI (xr.DataArray, [dimensionless])

  • FWI (xr.DataArray, [dimensionless])

Notes

See Natural Resources Canada [n.d.], the xclim.indices.fire module documentation, and the docstring of fire_weather_ufunc() for more information. This algorithm follows the official R code released by the CFS, which contains revisions from the original 1982 Fortran code.

References

Wang, Anderson, and Suddaby [2015]

xclim.indices.fire._cffwis.daily_severity_rating(fwi)[source]

Daily severity rating.

Parameters:

fwi (array_like) – Fire weather index

Return type:

ndarray

Returns:

array_like – Daily severity rating.

xclim.indices.fire._cffwis.drought_code(tas, pr, lat, snd=None, dc0=None, season_mask=None, season_method=None, overwintering=False, dry_start=None, initial_start_up=True, **params)[source]

Drought code (FWI component).

The drought code is part of the Canadian Forest Fire Weather Index System. It is a numeric rating of the average moisture content of organic layers.

Parameters:

  • tas (xr.DataArray) – Noon temperature.

  • pr (xr.DataArray) – Rain fall in open over previous 24 hours, at noon.

  • lat (xr.DataArray) – Latitude coordinate

  • snd (xr.DataArray) – Noon snow depth.

  • dc0 (xr.DataArray) – Initial values of the drought code.

  • season_mask (xr.DataArray, optional) – Boolean mask, True where/when the fire season is active.

  • season_method ({None, “WF93”, “LA08”, “GFWED”}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given.

  • overwintering (bool) – Whether to activate DC overwintering or not. If True, either season_method or season_mask must be given.

  • dry_start ({None, “CFS”, ‘GFWED’}) – Whether to activate the DC and DMC “dry start” mechanism and which method to use. See fire_weather_ufunc().

  • initial_start_up (bool) – If True (default), grid points where the fire season is active on the first timestep go through a start_up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points.

  • params – Any other keyword parameters as defined in xclim.indices.fire.fire_weather_ufunc and in default_params.

Return type:

DataArray

Returns:

xr.DataArray, [dimensionless] – Drought code

Notes

See Natural Resources Canada [n.d.], the xclim.indices.fire module documentation, and the docstring of fire_weather_ufunc() for more information. This algorithm follows the official R code released by the CFS, which contains revisions from the original 1982 Fortran code.

References

Wang, Anderson, and Suddaby [2015]

xclim.indices.fire._cffwis.duff_moisture_code(tas, pr, hurs, lat, snd=None, dmc0=None, season_mask=None, season_method=None, dry_start=None, initial_start_up=True, **params)[source]

Duff moisture code (FWI component).

The duff moisture code is part of the Canadian Forest Fire Weather Index System. It is a numeric rating of the average moisture content of loosely compacted organic layers of moderate depth.

Parameters:

  • tas (xr.DataArray) – Noon temperature.

  • pr (xr.DataArray) – Rain fall in open over previous 24 hours, at noon.

  • hurs (xr.DataArray) – Noon relative humidity.

  • lat (xr.DataArray) – Latitude coordinate

  • snd (xr.DataArray) – Noon snow depth.

  • dmc0 (xr.DataArray) – Initial values of the duff moisture code.

  • season_mask (xr.DataArray, optional) – Boolean mask, True where/when the fire season is active.

  • season_method ({None, “WF93”, “LA08”, “GFWED”}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given.

  • dry_start ({None, “CFS”, ‘GFWED’}) – Whether to activate the DC and DMC “dry start” mechanism and which method to use. See fire_weather_ufunc().

  • initial_start_up (bool) – If True (default), grid points where the fire season is active on the first timestep go through a start_up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points.

  • params – Any other keyword parameters as defined in xclim.indices.fire.fire_weather_ufunc and in default_params.

Return type:

DataArray

Returns:

xr.DataArray, [dimensionless] – Duff moisture code

Notes

See Natural Resources Canada [n.d.], the xclim.indices.fire module documentation, and the docstring of fire_weather_ufunc() for more information. This algorithm follows the official R code released by the CFS, which contains revisions from the original 1982 Fortran code.

References

Wang, Anderson, and Suddaby [2015]

xclim.indices.fire._cffwis.fire_season(tas, snd=None, method='WF93', freq=None, temp_start_thresh='12 degC', temp_end_thresh='5 degC', temp_condition_days=3, snow_condition_days=3, snow_thresh='0.01 m')[source]

Fire season mask.

Binary mask of the active fire season, defined by conditions on consecutive daily temperatures and, optionally, snow depths.

Parameters:

  • tas (xr.DataArray) – Daily surface temperature, cffdrs recommends using maximum daily temperature.

  • snd (xr.DataArray, optional) – Snow depth, used with method == ‘LA08’.

  • method ({“WF93”, “LA08”, “GFWED”}) – Which method to use. “LA08” and “GFWED” need the snow depth.

  • freq (str, optional) – If given only the longest fire season for each period defined by this frequency, Every “seasons” are returned if None, including the short shoulder seasons.

  • temp_start_thresh (Quantified) – Minimal temperature needed to start the season. Must be scalar.

  • temp_end_thresh (Quantified) – Maximal temperature needed to end the season. Must be scalar.

  • temp_condition_days (int) – Number of days with temperature above or below the thresholds to trigger a start or an end of the fire season.

  • snow_condition_days (int) – Parameters for the fire season determination. See fire_season(). Temperature is in degC, snow in m. The snow_thresh parameters is also used when dry_start is set to “GFWED”.

  • snow_thresh (Quantified) – Minimal snow depth level to end a fire season, only used with method “LA08”. Must be scalar.

Return type:

DataArray

Returns:

xr.DataArray – Fire season mask

References

Lawson and Armitage [2008], Wotton and Flannigan [1993]

xclim.indices.fire._cffwis.fire_weather_index(isi, bui)[source]

Fire weather index.

Parameters:

  • isi (array) – Initial spread index

  • bui (array) – Build up index.

Returns:

array – Build up index.

xclim.indices.fire._cffwis.fire_weather_ufunc(*, tas, pr, hurs=None, sfcWind=None, snd=None, lat=None, dc0=None, dmc0=None, ffmc0=None, winter_pr=None, season_mask=None, start_dates=None, indexes=None, season_method=None, overwintering=False, dry_start=None, initial_start_up=True, **params)[source]

Fire Weather Indexes computation using xarray’s apply_ufunc.

No unit handling. Meant to be used by power users only. Please prefer using the DC and CFFWIS indicators or the drought_code() and cffwis_indices() indices defined in the same submodule.

Dask arrays must have only one chunk along the “time” dimension. User can control which indexes are computed with the indexes argument.

Parameters:

  • tas (xr.DataArray) – Noon surface temperature in °C

  • pr (xr.DataArray) – Rainfall over previous 24h, at noon in mm/day

  • hurs (xr.DataArray, optional) – Noon surface relative humidity in %, not needed for DC

  • sfcWind (xr.DataArray, optional) – Noon surface wind speed in km/h, not needed for DC, DMC or BUI

  • snd (xr.DataArray, optional) – Noon snow depth in m, only needed if season_method is “LA08”

  • lat (xr.DataArray, optional) – Latitude in °N, not needed for FFMC or ISI

  • dc0 (xr.DataArray, optional) – Previous DC map, see Notes. Defaults to NaN.

  • dmc0 (xr.DataArray, optional) – Previous DMC map, see Notes. Defaults to NaN.

  • ffmc0 (xr.DataArray, optional) – Previous FFMC map, see Notes. Defaults to NaN.

  • winter_pr (xr.DataArray, optional) – Accumulated precipitation since the end of the last season, until the beginning of the current data, mm/day. Only used if overwintering is True, defaults to 0.

  • season_mask (xr.DataArray, optional) – Boolean mask, True where/when the fire season is active.

  • indexes (Sequence[str], optional) – Which indexes to compute. If intermediate indexes are needed, they will be added to the list and output.

  • season_method ({None, “WF93”, “LA08”, “GFWED”}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given.

  • overwintering (bool) – Whether to activate DC overwintering or not. If True, either season_method or season_mask must be given.

  • dry_start ({None, ‘CFS’, ‘GFWED’}) – Whether to activate the DC and DMC “dry start” mechanism and which method to use. See Notes. If overwintering is activated, it overrides this parameter : only DMC is handled through the dry start mechanism.

  • initial_start_up (bool) – If True (default), grid points where the fire season is active on the first timestep go through a start-up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points.

  • carry_over_fraction (float) – Carry over fraction.

  • wetting_efficiency_fraction (float) – Drought code overwintering parameters, see overwintering_drought_code().

  • temp_start_thresh (float) – Starting temperature threshold.

  • temp_end_thresh (float) – Ending temperature threshold.

  • temp_condition_days (int) – The number of days’ temperature condition to consider.

  • snow_thresh (float) – The snow threshold.

  • snow_condition_days (int) – Parameters for the fire season determination. See fire_season(). Temperature is in degC, snow in m. The snow_thresh parameters is also used when dry_start is set to “GFWED”, see Notes.

  • dc_start (float) – DC start.

  • dmc_start (float) – DMC start.

  • ffmc_start (float) – Default starting values for the three base codes.

  • prec_thresh (float) – If the “dry start” is activated, this is the “wet” day precipitation threshold, see Notes. In mm/d.

  • dc_dry_factor (float) – DC’s start-up values for the “dry start” mechanism, see Notes.

  • dmc_dry_factor (float) – DMC’s start-up values for the “dry start” mechanism, see Notes.

  • snow_cover_days (int) – Snow cover days.

  • snow_min_cover_frac (float) – Snow minimum cover fraction.

  • snow_min_mean_depth (float) – Additional parameters for GFWED’s version of the “dry start” mechanism. See Notes. Snow depth is in m.

Return type:

dict[str, DataArray]

Returns:

dict[str, xarray.DataArray] – Dictionary containing the computed indexes as prescribed in indexes, including the intermediate ones needed, even if they were not explicitly listed in indexes. When overwintering is activated, winter_pr is added. If season_method is not None and season_mask was not given, season_mask is computed on-the-fly and added to the output.

Notes

When overwintering is activated, the argument dc0 is understood as last season’s last DC map and will be used to compute the overwintered DC at the beginning of the next season.

If overwintering is not activated and neither is fire season computation (season_method and season_mask are None), dc0, dmc0 and ffmc0 are understood as the codes on the day before the first day of FWI computation. They will default to their respective start values. This “always on” mode replicates the R “fire” code.

If the “dry start” mechanism is set to “CFS” (but there is no overwintering), the arguments dc0 and dmc0 are understood as the potential start-up values from last season. With \(DC_{start}\) the conventional start-up value, \(F_{dry-dc}\) the dc_dry_factor and \(N_{dry}\) the number of days since the last significant precipitation event, the start-up value \(DC_0\) is computed as:

\[DC_0 = DC_{start} + F_{dry-dc} * N_{dry}\]

The last significant precipitation event is the last day when precipitation was greater or equal to “prec_thresh”. The same happens for the DMC, with corresponding parameters. If overwintering is activated, this mechanism is only used for the DMC.

Alternatively, dry_start can be set to “GFWED”. In this mode, the start-up values are computed as:

\[DC_0 = F_{dry-dc} * N_{dry}\]

Where the current day is also included in the determination of \(N_{dry}\) (\(DC_0\) can thus be 0). Finally, for this “GFWED” mode, if snow cover is provided, a second check is performed: the dry start procedure is skipped and conventional start-up values are used for cells where the snow cover of the last snow_cover_days was above snow_thresh for at least snow_cover_days * snow_min_cover_frac days and where the mean snow cover over the same period was greater of equal to snow_min_mean_depth.

xclim.indices.fire._cffwis.initial_spread_index(ws, ffmc)[source]

Initialize spread index.

Parameters:

  • ws (array_like) – Noon wind speed [km/h].

  • ffmc (array_like) – Fine fuel moisture code.

Return type:

ndarray

Returns:

array_like – Initial spread index.

xclim.indices.fire._cffwis.overwintering_drought_code(last_dc, winter_pr, carry_over_fraction=0.75, wetting_efficiency_fraction=0.75, min_dc=15)[source]

Compute season-starting drought code based on previous season’s last drought code and total winter precipitation.

This method replicates the “wDC” method of the “cffdrs R package [Cantin et al., 2014], with an added control on the “minimum” DC.

Parameters:

  • last_dc (xr.DataArray) – The previous season’s last drought code.

  • winter_pr (xr.DataArray) – The accumulated precipitation since the end of the fire season.

  • carry_over_fraction (xr.DataArray or float) – Carry-over fraction of last fall’s moisture

  • wetting_efficiency_fraction (xr.DataArray or float) – Effectiveness of winter precipitation in recharging moisture reserves in spring

  • min_dc (xr.DataArray or float) – Minimum drought code starting value.

Return type:

DataArray

Returns:

wDC (xr.DataArray) – Overwintered drought code.

Notes

Details taken from the “cffdrs” R package documentation [Cantin et al., 2014]: Of the three fuel moisture codes (i.e. FFMC, DMC and DC) making up the FWI System, only the DC needs to be considered in terms of its values carrying over from one fire season to the next. In Canada both the FFMC and the DMC are assumed to reach moisture saturation from overwinter precipitation at or before spring melt; this is a reasonable assumption and any error in these assumed starting conditions quickly disappears. If snowfall (or other overwinter precipitation) is not large enough however, the fuel layer tracked by the Drought Code may not fully reach saturation after spring snow melt; because of the long response time in this fuel layer (53 days in standard conditions) a large error in this spring starting condition can affect the DC for a significant portion of the fire season. In areas where overwinter precipitation is 200 mm or more, full moisture recharge occurs and DC overwintering is usually unnecessary. More discussion of overwintering and fuel drying time lag can be found in Lawson and Armitage [2008] and Van Wagner [1985].

Carry-over fraction of last fall’s moisture:

  • 1.0, Daily DC calculated up to 1 November; continuous snow cover, or freeze-up, whichever comes first

  • 0.75, Daily DC calculations stopped before any of the above conditions met or the area is subject to occasional winter chinook conditions, leaving the ground bare and subject to moisture depletion

  • 0.5, Forested areas subject to long periods in fall or winter that favor depletion of soil moisture

Effectiveness of winter precipitation in recharging moisture reserves in spring:

  • 0.9, Poorly drained, boggy sites with deep organic layers

  • 0.75, Deep ground frost does not occur until late fall, if at all; moderately drained sites that allow infiltration of most of the melting snowpack

  • 0.5, Chinook-prone areas and areas subject to early and deep ground frost; well-drained soils favoring rapid percolation or topography favoring rapid runoff before melting of ground frost

Source: Lawson and Armitage [2008] - Table 9.

References

Cantin et al. [2014], Field et al. [2015], Lawson and Armitage [2008], Van Wagner [1985]

xclim.indices.fire._ffdi module

McArthur Forest Fire Danger (Mark 5) System

This submodule defines indices related to the McArthur Forest Fire Danger Index Mark 5. Currently implemented are the xclim.indices.fire.keetch_byram_drought_index(), xclim.indices.fire.griffiths_drought_factor() and xclim.indices.fire.mcarthur_forest_fire_danger_index() indices, which are used by the eponym indicators. The implementation of these indices follows Finkele et al. [2006] and Noble et al. [1980], with any differences described in the documentation for each index. Users are encouraged to read this module’s documentation and consult Finkele et al. [2006] for a full description of the methods used to calculate each index.

xclim.indices.fire._ffdi.griffiths_drought_factor(pr, smd, limiting_func='xlim')[source]

Griffiths drought factor based on the soil moisture deficit.

The drought factor is a numeric indicator of the forest fire fuel availability in the deep litter bed. It is often used in the calculation of the McArthur Forest Fire Danger Index. The method implemented here follows Finkele et al. [2006].

Parameters:

  • pr (xr.DataArray) – Total rainfall over previous 24 hours [mm/day].

  • smd (xarray DataArray) – Daily soil moisture deficit (often KBDI) [mm/day].

  • limiting_func ({“xlim”, “discrete”}) – How to limit the values of the drought factor. If “xlim” (default), use equation (14) in Finkele et al. [2006]. If “discrete”, use equation Eq (13) in Finkele et al. [2006], but with the lower limit of each category bound adjusted to match the upper limit of the previous bound.

Return type:

DataArray

Returns:

df (xr.DataArray) – The limited Griffiths drought factor.

Notes

Calculation of the Griffiths drought factor depends on the rainfall over the previous 20 days. Thus, the first non-NaN time point in the drought factor returned by this function corresponds to the 20th day of the input data.

References

Finkele, Mills, Beard, and Jones [2006], Griffiths [1999], Holgate, Van DIjk, Cary, and Yebra [2017]

xclim.indices.fire._ffdi.keetch_byram_drought_index(pr, tasmax, pr_annual, kbdi0=None)[source]

Keetch-Byram drought index (KBDI) for soil moisture deficit.

The KBDI indicates the amount of water necessary to bring the soil moisture content back to field capacity. It is often used in the calculation of the McArthur Forest Fire Danger Index. The method implemented here follows Finkele et al. [2006] but limits the maximum KBDI to 203.2 mm, rather than 200 mm, in order to align best with the majority of the literature.

Parameters:

  • pr (xr.DataArray) – Total rainfall over previous 24 hours [mm/day].

  • tasmax (xr.DataArray) – Maximum temperature near the surface over previous 24 hours [degC].

  • pr_annual (xr.DataArray) – Mean (over years) annual accumulated rainfall [mm/year].

  • kbdi0 (xr.DataArray, optional) – Previous KBDI values used to initialise the KBDI calculation [mm/day]. Defaults to 0.

Return type:

DataArray

Returns:

xr.DataArray – Keetch-Byram drought index.

Notes

This method implements the method described in Finkele et al. [2006] (section 2.1.1) for calculating the KBDI with one small difference: in Finkele et al. [2006] the maximum KBDI is limited to 200 mm to represent the maximum field capacity of the soil (8 inches according to Keetch and Byram [1968]). However, it is more common in the literature to limit the KBDI to 203.2 mm which is a more accurate conversion from inches to mm. In this function, the KBDI is limited to 203.2 mm.

References

Dolling, Chu, and Fujioka [2005], Finkele, Mills, Beard, and Jones [2006], Holgate, Van DIjk, Cary, and Yebra [2017], Keetch and Byram [1968]

xclim.indices.fire._ffdi.mcarthur_forest_fire_danger_index(drought_factor, tasmax, hurs, sfcWind)[source]

McArthur forest fire danger index (FFDI) Mark 5.

The FFDI is a numeric indicator of the potential danger of a forest fire.

Parameters:

  • drought_factor (xr.DataArray) – The drought factor, often the daily Griffiths drought factor (see griffiths_drought_factor()).

  • tasmax (xr.DataArray) – The daily maximum temperature near the surface, or similar. Different applications have used different inputs here, including the previous/current day’s maximum daily temperature at a height of 2m, and the daily mean temperature at a height of 2m.

  • hurs (xr.DataArray) – The relative humidity near the surface and near the time of the maximum daily temperature, or similar. Different applications have used different inputs here, including the mid-afternoon relative humidity at a height of 2m, and the daily mean relative humidity at a height of 2m.

  • sfcWind (xr.DataArray) – The wind speed near the surface and near the time of the maximum daily temperature, or similar. Different applications have used different inputs here, including the mid-afternoon wind speed at a height of 10m, and the daily mean wind speed at a height of 10m.

Returns:

xr.DataArray – The McArthur forest fire danger index.

References

Dowdy [2018], Holgate, Van DIjk, Cary, and Yebra [2017], Noble, Gill, and Bary [1980]