PyroPy Modules

Spread Models

spreadmodels.py

Australian rate of spread models for wildfire and prescribed burns.

Unless otherwise indicated all models have been taken from:

Cruz, Miguel, James Gould, Martin Alexander, Lachie Mccaw, and Stuart Matthews. (2015) A Guide to Rate of Fire Spread Models for Australian Vegetation, CSIRO Land & Water and AFAC, Melbourne, Vic 125 pp.

Unless otherwise indicated all equations numbers also refer to Cruz et al. 2015.

All spread models take a pandas weather dataframe and model specific parmeters as arguments.

Functions can be called directly or as a method of PyroPy Incident.

The weather dataframe must include the following exact fields (column headings):

    date_time: a pandas datetime field
    temp: Air temerature (°C)
    humidity: Relative humidity (%)
    wind_speed: 10 m wind speed (km/h)
    wind_dir: Wind direction (°)

Ideally the weather dataframe should include a drought factor though this can be added as a parameter. TODO add error checking for this!

The weather module provides function for reading *.csv files into dataframes from standard sources

`get_FFDI(df, wrf=3, flank=False, DF=9)`

McArthur Forest Fire Danger Index (FFDI).

Uses Eqn 5.19.

If a drought factor (column heading = drought) is present in the weather dataframe then this is used, otherwise a drought factor must be supplied or the drought factor defaults to 9.

if flank=True the ffdi is calculated for a wind speed = 0

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a pandas dataframe which must contain the specified the weather data. This can be an Incident dataframe (`Incident.df`)	required
`wrf`	`int`	a wind reduction factor	`3`
`flank`	`bool`	if `flank=True` the ffdi is calculated for a wind speed = 0	`False`
`DF`	`int`	drought factor, this is only used if there is no `drought` in the DataFrame	`9`

Returns:

Type	Description
`Series`	a pandas Series of FFDI.

`get_mc_g(df)`

Calculates the grass moisture content using equation 3.8

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a pandas dataframe which must contain the specified the weather data. This can be an Incident dataframe (`Incident.df`)	required

Returns:

Type	Description
`Series`	the fine dead fuel moisture content (%)

`get_mc_m(df)`

Calculates the mallee moisture content using equation 4.15

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a pandas dataframe which must contain the specified the weather data. This can be an Incident dataframe (`Incident.df`)	required

Returns:

Type	Description
`Series`	the fine dead fuel moisture content (%)

`get_mc_v(df)`

Calculates VESTA the moisture content using equation 5.30

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a pandas dataframe which must contain the specified the weather data. This can be an Incident dataframe (`Incident.df`)	required

Returns:

Type	Description
`Series`	the fine dead fuel moisture content (%)

`ros_forest_mk5(df, wrf, fuel_load)`

Forward Rate of Spread (FROS) from McArthur Mk5 Forest Fire Danger Meter.

Eqn: 5.27

Application: Wildfire in Sclerophyll (Eucalypt) forests

Notes: This model is still widely used by FBAns in Australia though Cruz et al. 2015 recommend using Vesta in preference. However many FBAns feel that Vesta over predicts ROS unless conditions are severe.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the weather data. This can be an Incident dataframe (`Incident.df`)	required
`wrf`	`float`	wind reduction factor	required
`fuel_load`	`float`	fine fule load t/ha	required

Returns:

Type Description

DataFrame

a pandas dataframe including the fields

`fros_mk5` the forward rate of spread (m/h)

`ros_forest_vesta(df, fhs_surf, fhs_n_surf, fuel_height_ns, version_12=True)`

Forward Rate of Spread (FROS) from Project Vesta using fuel hazard scores

Eqn: 5.28

Application:

Notes: Many FBAns feel that Vesta over predicts ROS unless conditions are severe and use McArthur 1973a Mk5 Forest Fire Danger Meter.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the weather data. This can be an Incident dataframe (`Incident.df`)	required
`fhs_surf`	`float`	surface fuel hazard score (0-4)	required
`fhs_n_surf`	`float`	near surface fuel hazard score (0-4)	required
`fuel_height_ns`	`float`	near surface fuel height (cm)	required
`version_12`	`bool`	if `True` uses the Cheney et al. 2012 equation, if `False` uses the gould et al. 2008 version. Defaults to `True`	`True`

Returns:

Type Description

DataFrame

a pandas dataframe including the fields

`mc` the fuel moisture conent (%)
`fros_vesta` the forward rate of spread (m/h)

`ros_forest_vesta2(df, waf, fuel_load, height_u, drought=None)`

Forward Rate of Spread (FROS) from Project Vesta using fuel hazard scores

Cruz, et al. 2022 'An Empirical-Based Model for Predicting the Forward Spread Rate of Wildfires in Eucalypt Forests'. International Journal of Wildland Fire. https://doi.org/10.1071/WF21068

Application: Wildfire in Sclerophyll (Eucalypt) forests

Notes:

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the weather data. This can be an Incident dataframe (`Incident.df`)	required
`waf`	`float`	wind adjustment factor (1-6)	required
`fuel_load`	`float`	near surface fuel load (t/ha)	required
`fuel_height_u`		understorey fuel height (cm)	required

Returns:

Type Description

DataFrame

a pandas dataframe including the fields

`mc` the fuel moisture conent (%)
`fros_vesta` the forward rate of spread (m/h)

`ros_forest_vesta_fhr(df, fhr_surf, fhr_n_surf)`

Forward Rate of Spread (FROS) from Project Vesta using fuel hazard ratings

Eqn: 5.31

Application: Wildfire in Sclerophyll (Eucalypt) forests

Notes:

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the weather data. This can be an Incident dataframe (`Incident.df`)	required
`fhr_surf`	`str`	Surface Fuel Hazard Rating (L, M, H, V, E)	required
`fhr_n_surf`	`str`	Near Surface Fuel Hazard Rating (L, M, H, V, E)	required

Returns:

Type Description

DataFrame

a pandas dataframe including the fields

`fros_vesta_fhr` the forward rate of spread (m/h)

`ros_grass(df, state, curing)`

Forward Rate of Spread (FROS) from Cheney et al. 1998 grass model.

Eqns: 3.5, 3.6, 3.11

Application: Wildfire in grassland and shrubland

Notes:

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	the weather data. This can be an Incident dataframe (`Incident.df`)	required
`curing`	`int`	Curing level (%)	required
`state`	`str`	Grass state - natural (N), grazed (G), eaten out (E), (W) Woodlands, (F) Open forest	required

Returns:

Type Description

a pandas dataframe including the fields

`fros_grass` the forward rate of spread (m/h)

`ros_mallee(df, cover, height)`

Forward Rate of Spread (FROS) from Cruz et al 2013 Semi-arid mallee heath model.

Eqns: 4.17, 4.18

Model development:

n = 61
wind_speed range 5 - 28 km/h
temp range 16 - 39 C
humidity range 7 - 80 %
total_fuel range 3.8 - 14.8 t/ha
explains 0.74 of variability

Parameters:

Name	Type	Description	Default
`cover`	`int`	overstorey cover (%)	required
`height`	`float`	overstorey height (m)	required

Returns:

Type	Description
`DataFrame`	`DataFrame` including `fros_mallee`, `mc_m`

`spread_direction(df)`

Converts wind direction to spread direction.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a pandas dataframe which must contain the specified the weather data. This can be an Incident dataframe (`Incident.df`)	required

Returns:

Type	Description
`Series`	a pandas Series of spread direction in degrees.

Weather Data

weatherdata.py

Functions for reading, transforming and writing weather data.

The fire behaviour models require certain fields to be present in the weather data and these are mapped using dictionaries. There are several standard mappings included (see below), but for non-standard data users must create their own dictionary.

For use in spreadmodels functions, the weather dataframe must include the following fields (column headings) as a minimum:

    'date_time': a datetime field
    'temp': Air temerature (°C)
    'humidity': Relative humidity (%)
    'wind_speed': 10 m wind speed (km/h)
    'wind_dir': Wind direction (°)

The datetime field may be replaced by two separate fields:

    'date': the local date
    'time': the local time

Other optional fields used by the spreadmodels include:

    'drought': Drought Factor
    'ffdi': McArthur Mk5 Forest Fire Danger Index
    'gfdi': McArthur Mk5 Grass Fire Danger Index

There are functions to handle the standard data formats such as BOM gridded weather with mapping dictionaries already defined.

gridded_to_df(fn)
amicus_to_df(fn)
df_to_gridded(fn)
df_to_amicus(fn)

For example, if you are using BOM gridded weather data the you should run:

df = gridded_to_df('your_file_path.csv')

`df_to_amicus(df, fn)`

"Creates a weather DataFrame containing Amicus compatible fields.

Writes the weather data to a *.csv file

The output fields are:

'date_time': 'Date time',
'temp': 'Air temperature (°C)',
'humidity': 'Relative humidity (%)',
'wind_speed': '10 m wind speed (km/h)',
'wind_dir': 'Wind direction (°)'

Parameters:

Name	Type	Description	Default
`df`		a `DataFrame` containing the weather and other fields	required
`fn`	`str`	path to the output file	required

Returns:

Type	Description
`DataFrame`	a pandas `DataFrame` with Amicus compatible fields

`df_to_weather(df, fn, col_names={'date_time': 'Date time', 'temp': 'Air temperature (C)', 'humidity': 'Relative humidity (%)', 'wind_speed': '10 m wind speed (km/h)', 'wind_dir': 'Wind direction'}, datetime_format='%Y%m%d %H:%M', encoding=None)`

"Creates a weather DataFrame containing the fields in col_names.

Writes the weather data to a *.csv file

The default fields are:

    'date': 'Local Date',
    'time': 'Local Time',
    'temp': 'Temp (C)',
    'humidity': 'RH (%)',
    'wind_dir': 'Wind Dir',
    'wind_speed': 'Wind Speed (km/h)',
    'drought': 'Drought Factor',
    'ffdi': 'FFDI',
    'gfdi': 'GFDI',

If datetime_format == 'iso8601' the output format will be %Y-%m-%dT%H:%M:%s+11:00.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	a `DataFrame` containing the weather and other fields	required
`fn`	`str`	path to the output file	required
`col_names`		the fields to be returned	`{'date_time': 'Date time', 'temp': 'Air temperature (C)', 'humidity': 'Relative humidity (%)', 'wind_speed': '10 m wind speed (km/h)', 'wind_dir': 'Wind direction'}`
`datetime_format`		the output format for datetimes, dates and times.	`'%Y%m%d %H:%M'`
`encoding`		the coding for the output file if `*.csv`. Default is `UTF-8`	`None`

Returns:

Type	Description
`DataFrame`	a pandas `DataFrame` with the specified fields

`fbcalcs_to_df(fn)`

Reads weather data from FireBehaviourCalcs xlsm.

Parameters:

Name	Type	Description	Default
`fn`	`str`	the path to the FireBehaviourCalcs xlsm	required

Returns:

Type	Description
`DataFrame`	a pandas `DataFrame` suitable for use in `spreadmodels.py`

`gridded_to_df(fn, header=6)`

Reads BoM gridded weather forecast or observations into a pandas DataFrame.

Fields are mapped using

FIELDS_GRIDDED = { 'date': 'Local Date', 'time': 'Local Time', 'temp': 'Temp (C)', 'humidity': 'RH (%)', 'wind_dir': 'Wind Dir', 'wind_speed': 'Wind Speed (km/h)', 'drought': 'Drought Factor', 'ffdi': 'FFDI', 'gfdi': 'GFDI', }

Parameters:

Name	Type	Description	Default
`fn`	`str`	the path to the csv file	required

Returns:

Type	Description
`DataFrame`	a pandas DataFrame with the columns defined in `FIELDS_GRIDDED`

`weather_to_df(fn, header=0, col_names={'date_time': 'Date time', 'temp': 'Air temperature (C)', 'humidity': 'Relative humidity (%)', 'wind_speed': '10 m wind speed (km/h)', 'wind_dir': 'Wind direction'}, datetime_format='%d/%m/%Y %H:%M')`

Reads weather forecast or observations into a pandas DataFrame. Unless a col_names dictionary is supplied, the FIELDS_BASE dictionary is used.

FIELDS_BASE = {
    'date_time': 'Date time',
    'temp': 'Air temperature (C)',
    'humidity': 'Relative humidity (%)',
    'wind_speed': '10 m wind speed (km/h)',
    'wind_dir': 'Wind direction',
}

Parameters:

Name	Type	Description	Default
`fn`	`str`	the path to the csv or axf file	required
`header`	`int`	the line containing the column headers	`0`
`col_names`	`dict`	the dictionary containing the column names to read into the dataframe	`{'date_time': 'Date time', 'temp': 'Air temperature (C)', 'humidity': 'Relative humidity (%)', 'wind_speed': '10 m wind speed (km/h)', 'wind_dir': 'Wind direction'}`
`datetime_format`	`str`	string format for the date times. Use a single string of the form `'date_format time_format'` even if supplying date and time as two separete fields.	`'%d/%m/%Y %H:%M'`

Returns:

Type	Description
`DataFrame`	weather dataframe

Fire Behaviour

firebehaviour.py

Defines the classes used to analyse fire behaviour with PyroPy.

`Incident`

A wildfire incident.

Attributes:

Name	Type	Description
`df`	`Dataframe`	Weather and model output data
`waf`	`float`	wind reduction factor (0-6)
`fuel_load`	`float`	fine fuel load (t/ha)
`fhs_surf`	`float`	surface fuels hazard score (1-4)
`fhs_n_surf`	`float`	near surface fuels hazard score (1-4)
`fuel_height_ns`	`float`	near surface fuel height (cm)
`fuel_height_u`	`float`	understorey fuel height (m) TODO calc this
`fhr_surf`		Surface Fuel Hazard Rating (L, M, H, V, E)
`fhr_n_surf`		Near Surface Fuel Hazard Rating (L, M, H, V, E)

`adjust_precision(self, precision_dict)`

Adjusts the precision of the records in the incident dataframe.

Parameters:

Name	Type	Description	Default
`precision_dict`	`dict`	defines the precision of the fields to be changed. Example: `precision_dict = { 0: ['ffdi','fros', 'ros'], 1: ['mc', 'mf'], 2: [] }`	required

`check_params(self, params)`

Checks to see if parameters have been defined.

Parameters:

Name	Type	Description	Default
`params`	`dict`	a dictionary with the parmeters to check.	required

Returns:

Type	Description
`bool`	`True` is values for the parameters have been defined, else `False`

`compare_fbcalc(self, fn, models)`

Loads results from an FireBehaviourCalcs spreadsheet into the Incident.df.

Only loads the pages from FireBehaviourCalcs that have correspond to models then adds fros values to Incident.df in the form 'fros_{model}_fbcalc'

Parameters:

Name Type Description Default

fn

str

path to the FireBehaviourCalcs spreadsheet

required

model

list

a list of the models to compare. Valid items include: 'mk5' McArthur Mk5, 'vesta' Project VESTA, 'vesta2' Vesta MkII (dry), 'mallee' the mallee-heath.

Also there is a little easter egg here and if you put 'mc_v' as the model it will get the moisture content (%) from the VESTA model, while 'mc_v2' will get the moisture content from the Vesta II model and 'mc_m' will get the moisture content from the Mallee-Heath model.

required

Returns:

Type	Description
`None`

`copy(self)`

Deep copy.

Returns:

Type	Description
`Incident`	a deep copy of the `Incident`.

`get_df(self)`

Returns:

Type	Description
`DataFrame`	the Incident Data as a pandas `Dataframe`

`get_models(self)`

Returns:

Type	Description
`list`	a list of the models that have been run for the Incident

`get_params(self)`

Gets the model parameters that have been defined.

Returns:

Type	Description
`dict`	dictionary with model parameter names and values

`get_spread_direction(self)`

Add the fire spread direction measured in degrees to the incident df.

`print(self, head=False)`

Prints the field headings and rows of the Dataframe

Parameters:

Name	Type	Description	Default
`head`	`bool`	Print only the head (first 5 rows). Defaults to False.	`False`

`run_forest_mk5(self)`

Runs the McArthur Mk5 Forest Fire Danger Meter model.

Requires that the Wind Adjustment Factor 'waf' and Fine fuel load (t/ha) 'fuel_load' parameters are set. See Incident.set_params()

Adds the results to the Incident.df

`run_forest_vesta(self, version_12=True)`

Runs the Project Vesta (fuel hazard scores) model.

Uses the Fuel Hazard Scores (FHS) described in:

Hines, F. et al. 2010, Overall Fuel Hazard Assessment Guide. Dept of Natural Resources and Environment, East Melbourne, Vic.

Requires that the surface FHS 'fhs_surf', the near surface FHS 'fhs_n_surf' and the near surface fuel height (cm) 'fuel_height_ns' parameters are set. See Incident.set_params()

Adds the results to the Incident.df

Parameters:

Name	Type	Description	Default
`version_12`		if `True` uses the Cheney et al. 2012 equation, if `False` uses the Gould et al. 2008 version. Defaults to `True`.	`True`

`run_forest_vesta2(self)`

Runs the Project Vesta Mk2 model.

Cruz, et al. 2022 'An Empirical-Based Model for Predicting the Forward Spread Rate of Wildfires in Eucalypt Forests'. International Journal of Wildland Fire. https://doi.org/10.1071/WF21068

Requires that the Wind Adjustment Factor 'waf', surface fuel load (t/ha) 'fuel_load' and the understorey fuel height 'fuel_height_u' parameters are set. See Incident.set_params()

Adds the results to the Incident.df

`run_forest_vesta_fhr(self)`

Runs the Project Vesta (fuel hazard ratings) model.

Uses the Fuel Hazard Ratings (FHR) described in:

Hines, F. et al. 2010, Overall Fuel Hazard Assessment Guide. Dept of Natural Resources and Environment, East Melbourne, Vic.

Requires that the surface FHR 'fhr_surf' and the near surface FHR 'fhr_n_surf' parameters are set. See Incident.set_params()

Adds the results to the Incident.df

`run_grass(self)`

Runs the Cheney et al. 1998 grass and woodland model.

Requires that the grass fuel state (N, G, E, W or F) 'grass_state' and curing (%) 'curing' parameters are set. See Incident.set_params()

Adds the results to the Incident.df

`run_mallee(self)`

Runs the Cruz et al 2013 Semi-arid mallee heath model.

Requires that the overstorey cover(%) 'os_cover' and overstorey height (m) parameters are set. See Incident.set_params()

Adds the results to the Incident.df

`set_fbcalc(self, fn)`

Writes the weather data and model parameters to a FireBehaviourCalc macro enabled spreadsheet.

WARNING! THE VALUES IN THE SPREADSHEET WILL BE OVERWRITTEN

Spreadsheet macros will not run (ie changes will not take place in the spreadsheet) until you open it and click on the relevant sheets.

Parameters:

Name	Type	Description	Default
`fn`	`str`	path to the FireBehaviourCalc spreadsheet.	required

Returns:

Type	Description
`bool`	`True` f successful else `False`

`set_params(self, params)`

Update several model parameters using a dictionary.

The dictionary keys must match the name of the parameter.

Parameters:

Name	Type	Description	Default
`params`	`dict`	a dictionary of the model parameters to be updated.	required

`thin_by_timestep(self, time_step=1)`

Removes records from the incident dataframe.

The dataframe will have a a minimum time step given by time_step

Parameters:

Name	Type	Description	Default
`time_step`	`float`	Minimum time step in hours. Defaults to 1.	`1`

`trim_by_datetime(self, start, end, format='%Y%m%d %H:%M')`

Trims the records of the Incident Dataframe to a datetime range.

Parameters:

Name	Type	Description	Default
`start`	`str`	the start datetime	required
`end`	`str`	the end datetime	required
`format`	`str`	The datetime format. Defaults to '%Y%m%d %H:%M'.	`'%Y%m%d %H:%M'`