landlab.components.fire_generator.generate_fire

Landlab component that generates a random fire event in time.

This component generates a random fire event or fire time series from the Weibull statistical distribution.

Code author: Jordan Adams

This component generates random numbers using the Weibull distribution (Weibull, 1951). No particular units must be used, but it was written with the fire recurrence units in time (yrs).

Using the Weibull Distribution assumes two things: All elements within the study area have the same fire regime. Each element must have (on average) a constant fire regime during the time span of the study.

As of Sept. 2013, fires are considered instantaneous events independent of other fire events in the time series.

Written by Jordan M. Adams, 2013. Updated April 2016.

Examples

>>> from landlab.components.fire_generator import FireGenerator
>>> from landlab import RasterModelGrid

Create an instance of the FireGenerator component

>>> mg = RasterModelGrid((10, 10))
>>> fg = FireGenerator(mg, mean_fire_recurrence=15.0, shape_parameter=4.5)

This creates an instance of the component that has a mean_fire_recurrence, or average interval between fires of 15 years. We gave it a shape parameter of 4.5, suggesting the cumulative distribution function that is skewed right.

Since we didn’t pass it a scale parameter, the component calculates it for you. Testing this…

>>> fg.scale_parameter
16.437036931437866

To get a time to next fire:

>>> fg.generate_fire_recurrence()  
10.68

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

Polakow, D., Dunne, T. (1999). Modelling fire-return interval T: stochasticity and censoring in the two-parameter Weibull model Ecological Modelling 121(1), 79-102. https://dx.doi.org/10.1016/s0304-3800(99)00074-5

class FireGenerator

Bases: Component

Generate a random fire event or time series.

Parameters:

• mean_fire_recurrence (float) – Average time between fires for a given location

• shape_parameter (float) – Describes the skew of the Weibull distribution. If shape < 3.5, data skews left. If shape == 3.5, data is normal. If shape > 3.5, data skews right. To approximate a normal bell curve, use a value of 3.5

• scale_parameter (float, optional) – Describes the peak of the Weibull distribution, located at the 63.5% value of the cumulative distribution function. If unknown, it can be found using mean fire recurrence value and the get_scale_parameter() method described later.

Generate a random fire event in time.

Parameters:

• grid (landlab model grid)

• mean_fire_recurrence (float) – Average time between fires for a given location

• shape_parameter (float) – Describes the skew of the Weibull distribution. If shape < 3.5, data skews left. If shape == 3.5, data is normal. If shape > 3.5, data skews right.

• scale_parameter (float, optional) – Describes the peak of the Weibull distribution, located at the 63.5% value of the cumulative distribution function. If unknown, it can be found using mean fire recurrence value and the get_scale_parameter().

__init__(grid, mean_fire_recurrence=1.0, shape_parameter=3.5, scale_parameter=None)

Generate a random fire event in time.

Parameters:

• grid (landlab model grid)

• mean_fire_recurrence (float) – Average time between fires for a given location

• shape_parameter (float) – Describes the skew of the Weibull distribution. If shape < 3.5, data skews left. If shape == 3.5, data is normal. If shape > 3.5, data skews right.

• scale_parameter (float, optional) – Describes the peak of the Weibull distribution, located at the 63.5% value of the cumulative distribution function. If unknown, it can be found using mean fire recurrence value and the get_scale_parameter().

static __new__(cls, *args, **kwds)

cite_as = ''

property coords

Return the coordinates of nodes on grid attached to the component.

property current_time

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:

current_time

definitions = ()

classmethod from_path(grid, path)

Create a component from an input file.

Parameters:

• grid (ModelGrid) – A landlab grid.

• path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

generate_fire_recurrence()

Get time to next fire.

Finds the time to next fire (fire recurrence) based on the scale parameter (63.5% of fire Weibull distribution) and the shape parameter (describes the skew of the histogram, shape = 3.5 represents a normal distribution).

Rounds the time to next fire to 4 significant figures, for neatness.

Returns:

Updated value for the time to next fire.

Return type:

float

get_scale_parameter()

Get the scale parameter.

::

mean_fire_recurrence = (scale_parameter * (

special.gamma(1 + (1 / shape))))

sets the scale parameter.

property grid

Return the grid attached to the component.

initialize_optional_output_fields()

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:

values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ()

name = 'FireGenerator'

optional_var_names = ()

output_var_names = ()

property scale_parameter

Scale parameter for the random distribution.

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = True

units = ()

classmethod var_definition(name)

Get a description of a particular field.

Parameters:

name (str) – A field name.

Returns:

A description of each field.

Return type:

tuple of (name, *description*)

classmethod var_help(name)

Print a help message for a particular field.

Parameters:

name (str) – A field name.

classmethod var_loc(name)

Location where a particular variable is defined.

Parameters:

name (str) – A field name.

Returns:

The location (‘node’, ‘link’, etc.) where a variable is defined.

Return type:

str

var_mapping = ()

classmethod var_type(name)

Returns the dtype of a field (float, int, bool, str…).

Parameters:

name (str) – A field name.

Returns:

The dtype of the field.

Return type:

dtype

classmethod var_units(name)

Get the units of a particular field.

Parameters:

name (str) – A field name.

Returns:

Units for the given field.

Return type:

str