models.staley2017 module¶

Implements the logistic regression models presented in Staley et al., 2017.

Content	Description

Solver Functions
likelihood	Solves for debris-flow likelihoods given rainfall accumulations
accumulation	Solves for the rainfall accumulations needed to achieve given probability levels

Model Classes
M1	Implements the M1 model
M2	Implements the M2 model
M3	Implements the M3 model
M4	Implements the M4 model

Model Methods
parameters	Returns the B, Ct, Cf, and Cs parameters for a model
variables	Returns the T, F, and S variables for a model
terrain	Returns the terrain variable (T) for a model
fire	Returns the fire variable (F) for a model
soil	Returns the soil variable (S) for a model

This module solves the logistic regression models presented in Staley et al., 2017. These models describe debris-flow likelihood as a function of terrain (T), fire burn severity (F), soil (S), and rainfall accumulation (R), such that:

\[p = \mathrm{\frac{e^X}{1 + e^X}}\]

\[\mathrm{X = B + C_t\ T\ R + C_f\ F\ R + C_s\ S\ R}\]

where:

Variable	Description
p	Debris-flow likelihood (0 to 1)
T	A terrain variable
F	A fire severity variable
S	A soil variable
R	Rainfall accumulation in mm
B	Model intercept
Ct, Cf, Cs	Variable coefficients

This module provides two functions to solve models of this form. The likelihood function solves the model in the forward direction, and the accumulation function inverts the model to compute the rainfall accumulations needed to cause debris flows at the specified probability levels.

Note

The likelihood and accumulation functions are generalized, so are suitable for any model following the form of the above equation.

In addition to the generic solvers, this module provides the M1, M2, M3, and M4 model classes, which help implement the 4 specific models described in the paper. Each class provides a parameters method, which returns the corresponding B, Ct, Cf, and Cs values published in the paper. Each class also provides a variables method, which returns the appropriate T, F, and S variables for a given set of stream segments. These parameters and variables can then be used to run the likelihood and/or accumulation functions.

Solver Functions¶

pfdf.models.staley2017.likelihood(R, B, Ct, T, Cf, F, Cs, S, *, keepdims=False)¶

Computes debris-flow likelihood for the specified rainfall durations

likelihood(R, B, Ct, T, Cf, F, Cs, S)
likelihood(..., keepdims=True)

Solves the debris-flow likelihoods for the specified rainfall accumulations. This function is agnostic to the actual model being run, and thus can implement all 4 of the models presented in the paper (as well as any other model following the form of Equation 1).

All of the inputs to this function should be real-valued numpy arrays. The R values are the rainfall accumulations for which the model should be solved. For example, R = 6 solves for debris-flow likelihood when rainfall accumulation is 6 mm/duration. R should be a 1D array listing all the accumulations that should be solved for.

The three variables - T, F, and S - represent the terrain steepness, wildfire severity, and surface properties variables for the model. In most cases, these are 1D arrays with one element per stream segment being assessed. Variables can also be scalar (in which the same value is used for every segment), or 2D arrays (refer below for details of this less common use case).

The four parameters - B, Ct, Cf, and Cs - are the parameters of the logistic model link equation. B is the intercept, and each C parameter is the coefficient of the associated variable. Parameters can be used to implement multiple runs of the assessment model. Here, we define a “run” as an implementation of the hazard model using a unique set of logistic model parameters. Each parameter should be either a scalar, or vector of parameter values. If a vector, the input should have one element per run. If a scalar, then the same value is used for every run of the model. A common use case is solving the model for multiple rainfall durations (for example: 15, 30, and 60 minute intervals). In the example with 3 durations, each parameter should have 3 elements - each element corresponds to parameter value for the corresponding rainfall duration. Another use case for multiple runs is implementing a parameter sweep to validate model parameters.

This function solves the debris-flow likelihoods for all stream segments, rainfall accumulations, and parameter runs provided. Note that rainfall accumulations should be relative to the rainfall durations associated with each set of parameters. For example, if using parameters for 15-minute and 30-minute rainfall durations, then the input rainfall accumulations should be for 15-minute and 30-minute intervals, respectively. Accumulation units are the units of the rainfall values used to calibrate the model’s parameters. For the 4 models described in the paper, accumulations are millimeters of accumulations per rainfall duration.

The returned output will be a numpy array with up to 3 dimensions. The first dimension is stream segments, second dimension is rainfall accumulations, and third dimension is parameter runs. By default, this command will remove singleton dimensions from the output array. The first dimension is always retained, but the second is removed if there is a single rainfall accumulation, and the third is removed if there is a single parameter run. Alternatively, set keepdims=True to always return a 3D array.

As mentioned, one or more variables can also be a 2D array. In this case each row is a stream segment, and each column is a parameter run. Each column will be used to solve the model for (only) the associated parameter run. This allows use of different values for a variable. An example use case could be testing the model using different datasets to derive one or more variables.

Inputs:

R (vector (R values)) – The rainfall accumulations for which to solve the model
B (scalar | vector (Runs)) – The intercepts of the link equation
Ct (scalar | vector (Runs)) – The coefficients for the terrain steepness variable
T (vector (Segments) | matrix (Segments x Runs)) – The terrain steepness variable
Cf (scalar | vector (Runs)) – The coefficients for the wildfire severity variable
F (vector (Segments) | matrix (Segments x Runs)) – The wildfire severity variable
Cs (scalar | vector (Runs)) – The coefficients for the surface properties variable
S (vector (Segments) | matrix (Segments x Runs)) – The surface properties variable
keepdims (bool) – True to always return a 3D numpy array. If False (default), returns a 2D array when there is 1 R value, and a 1D array if there is 1 R value and 1 parameter run.

Outputs:

ndarray (Segments x R values x Parameter Runs) – The computed likelihoods

pfdf.models.staley2017.accumulation(p, B, Ct, T, Cf, F, Cs, S, *, keepdims=False, screen=True)¶

Computes rainfall accumulations needed for specified debris-flow probability levels

Solve Rainfall Accumulation

accumulation(p, B, Ct, T, Cf, F, Cs, S)

Returns the rainfall accumulations required to achieve the specified p-values. This function is agnostic to the actual model being run, and thus can implement all 4 of the models presented in the paper (as well as any other model following the form of Equation 1).

All of the inputs to this function should be real-valued numpy arrays. The p-values - p - are the design probabilities for which the model should be solved. For example, p=0.5 estimates the rainfall accumulation that would result in a 50% probability of a debris flow event. Here, p should be a 1D array listing all the design probabilities that should be solved for.

This function solves the rainfall accumulations for all stream segments, p-values, and parameter runs provided. Each accumulation describes the total rainfall required within the rainfall duration associated with its parameters. For example, if using parameters for a 15-minute rainfall duration, the accumulation describes the total rainfall required within a 15-minute window. Accumulation units are the units of the rainfall values used to calibrate the model’s parameters. For the 4 models described in the paper, accumulations are in mm.

The returned output will be a numpy array with up to 3 dimensions. The first dimension is stream segments, second dimension is p-values, and third dimension is parameter runs. By default, this command will remove singleton dimensions from the output array. The first dimension is always retained, but the second is removed if there is a single design probability, and the third is removed if there is a single parameter run. Alternatively, set keepdims=True to always return a 3D array.

As mentioned, one or more variable can also be a 2D array. In this case each row is a stream segment, and each column is a parameter run. Each column will be used to solve the model for (only) the associated parameter run. This allows use of different values for a variable. An example use case could be testing the model using different datasets to derive one or more variables.

Inputs:

p (vector (p values)) – The probability levels for which to solve the model
B (scalar | vector (Runs)) – The intercepts of the link equation
Ct (scalar | vector (Runs)) – The coefficients for the terrain steepness variable
T (vector (Segments) | matrix (Segments x Runs)) – The terrain steepness variable
Cf (scalar | vector (Runs)) – The coefficients for the wildfire severity variable
F (vector (Segments) | matrix (Segments x Runs)) – The wildfire severity variable
Cs (scalar | vector (Runs)) – The coefficients for the surface properties variable
S (vector (Segments) | matrix (Segments x Runs)) – The surface properties variable
keepdims (bool) – True to always return a 3D numpy array. If false (default), returns a 2D array when there is 1 p-value, and a 1D array if there is 1 p-value and 1 parameter run.
screen (bool) – True (default) to replace negative accumulations with NaN. False to disable this screening.

Outputs:

ndarray (Segments x P-values x Parameter Runs) – The computed rainfall accumulations

Model Classes¶

class pfdf.models.staley2017.M1¶

Facilitates the M1 model.

Terrain (T): Proportion of catchment area with both (1) moderate or high burn severity, and (2) slope angle >= 23 degrees.
Fire (F): Mean catchment dNBR / 1000
Soil (S): Mean catchment KF-factor

classmethod parameters(cls, durations=[15, 30, 60])¶

Return model parameters for the queried durations.

Inputs:

durations (vector) – A list of rainfall durations for which to return model parameters

Outputs:

ndarray – Logistic model intercepts (B)
ndarray – Terrain coefficients (Ct)
ndarray – Fire coefficients (Cf)
ndarray – Soil coefficients (Cs)

static variables(segments, moderate_high, slopes, dnbr, kf_factor, omitnan=False)¶

Computes the T, F, and S variables for the M1 model

Inputs:

segments (Segments) – A Segments object defining a stream segment network
moderate_high (Raster) – A raster mask indicating watershed pixels with moderate or high burn severity. True pixels indicate moderate or high severity. False pixels are not burned at these levels.
slopes (Raster) – A raster with the slope gradients (not angles) for the watershed. NoData pixels are interpreted as locations with slope angles less than 23 degrees.
dnbr (Raster) – A dNBR raster for the watershed
kf_factor (Raster) – A KF-factor raster for the watershed
omitnan (bool) – A boolean or dict indicating whether to ignore NaN and NoData values in the dnbr and kf_factor rasters

Outputs:

ndarray – The terrain variable (T) for each stream segment
ndarray – The fire variable (F) for each stream segment
ndarray – The soil variable (S) for each stream segment

static terrain(segments, moderate_high, slopes)¶

Computes the M1 terrain variable

M1.terrain(segments, moderate_high, slopes)

Returns the M1 terrain variable for the network.

Inputs:

segments (Segments) – A stream segment network
moderate_high (Raster) – The moderate-high burn severity mask
slopes (Raster) – Slope raster

Outputs:

ndarray – The M1 terrain variable (T)

static fire(segments, dnbr, omitnan=False)¶

Computes the M2 fire variable

M1.fire(segments, dnbr)
M1.fire(segments, dnbr, omitnan=True)

Returns the M1 fire variable for the network. Use omitnan to ignore NaN and NoData values in the dNBR raster.

Inputs:

segments (Segments) – A stream segment network
dnbr (Raster) – A dNBR raster
omitnan (bool) – True to ignore NaN and NoData values in the dNBR raster. Default is False.

Outputs:

ndarray – The M1 fire variable (F)

static soil(segments, kf_factor, omitnan=False)¶

Computes the M1 soil variable

M1.soil(segments, kf_factor)
M1.soil(segments, kf_factor, omitnan=True)

Returns the M1 soil variable for the network. Use omitnan to ignore NaN and NoData values in the KF-factor raster.

Inputs:

segments (Segments) – A stream segment network
kf_factor (Raster) – A KF-factor raster
omitnan (bool) – True to ignore NaN and NoData values in the KF-factor raster. Default is False

Outputs:

ndarray – The M1 soil variable (S)

class pfdf.models.staley2017.M2¶

Facilitates the M2 model.

Terrain (T): Mean sin(θ) of catchment area burned at moderate or high severity
Fire (F): Mean catchment dNBR / 1000
Soil (S): Mean catchment KF-factor

classmethod parameters(cls, durations=[15, 30, 60])¶

Return model parameters for the queried durations.

Inputs:

durations (vector) – A list of rainfall durations for which to return model parameters

Outputs:

ndarray – Logistic model intercepts (B)
ndarray – Terrain coefficients (Ct)
ndarray – Fire coefficients (Cf)
ndarray – Soil coefficients (Cs)

static variables(segments, moderate_high, slopes, dnbr, kf_factor, omitnan=False)¶

Computes the T, F, and S variables for the M2 model

Inputs:

segments (Segments) – A Segments object defining a stream segment network
moderate_high (Raster) – A raster mask indicating watershed pixels with moderate or high burn severity. True pixels indicate moderate or high severity. False pixels are not burned at these levels.
slopes (Raster) — A raster with the slope gradients (not angles) for the watershed
dnbr (Raster) – A dNBR raster for the watershed
kf_factor (Raster) – A KF-factor raster for the watershed
omitnan (bool) – A boolean or dict indicating whether to ignore NaN and NoData values in the slopes, dnbr, and kf_factor rasters

Outputs:

ndarray – The terrain variable (T) for each stream segment
ndarray – The fire variable (F) for each stream segment
ndarray – The soil variable (S) for each stream segment

static terrain(segments, slopes, moderate_high, omitnan=False)¶

Computes the M2 terrain variable

M2.terrain(segments, slopes, moderate_high)
M2.terrain(..., omitnan=True)

Computes the M2 terrain variable. Set omitnan=True to ignore NaN and NoData values in the slopes raster.

Inputs:

segments (Segments) – A stream segment network
slope (Raster) – A slope raster
moderate_high (Raster) – Moderate-high burn severity raster mask
omitnan (bool) – True to ignore NaN and NoData values in the slopes raster. Default is False

Outputs:

ndarray – The M2 terrain variable (T)

static fire(segments, dnbr, omitnan=False)¶

Computes the M2 fire variable

M2.fire(segments, dnbr)
M2.fire(segments, dnbr, omitnan=True)

Computes the M2 fire variable. Set omitnan=True to ignore NaN and NoData values in the dNBR raster.

Inputs:

segments (Segments) – A stream segment network
dnbr (Raster) – A dNBR raster
omitnan (bool) – True to ignore NaN and NoData values in the dNBR raster. Default is False.

Outputs:

ndarray – The M2 fire variable (F)

static soil(segments, kf_factor, omitnan=False)¶

Computes the M2 soil variable

M2.soil(segments, kf_factor)
M2.soil(..., omitnan=True)

Computes the M2 soil variable. Set omitnan=True to ignore NaN and NoData values in the KF-factor raster.

Inputs:

segments (Segments) –: A stream segment network
kf_factor (Raster) – A KF-factor raster
omitnan (bool) – True to ignore NaN and NoData values in the KF-factor raster. Default is False.

Outputs:

ndarray – The M2 soil variable (S)

class pfdf.models.staley2017.M3¶

Facilitates the M3 model.

classmethod parameters(cls, durations=[15, 30, 60])¶

Return model parameters for the queried durations.

Terrain (T): Topographic ruggedness (vertical relief / sqrt(catchment area))
Fire (F): Proportion of catchment area burned at moderate or high severity
Soil (S): Mean catchment soil thickness / 100

Inputs:

durations (vector) – A list of rainfall durations for which to return model parameters

Outputs:

ndarray – Logistic model intercepts (B)
ndarray – Terrain coefficients (Ct)
ndarray – Fire coefficients (Cf)
ndarray – Soil coefficients (Cs)

static variables(segments, moderate_high, relief, soil_thickness, relief_per_m=1, omitnan=False)¶

Computes the T, F, and S variables for the M3 model

Inputs:

segments (Segments) – A Segments object defining a stream segment network
moderate_high (Raster) – A raster mask indicating watershed pixels with moderate or high burn severity. True pixels indicate moderate or high severity. False pixels are not burned at these levels.
relief (Raster) – A vertical relief raster for the watershed
soil_thickness (Raster) – A soil thickness raster for the watershed
relief_per_m (scalar) – A conversion factor between relief units and meters
omitnan (bool) – A boolean or dict indicating whether to ignore NaN and NoData values in the soil_thickness raster

Outputs:

ndarray – The terrain variable (T) for each stream segment
ndarray – The fire variable (F) for each stream segment
ndarray – The soil variable (S) for each stream segment

static terrain(segments, relief, relief_per_m=1)¶

Computes the M3 terrain variable

M3.terrain(segments, relief)
M3.terrain(..., relief_per_m)

Computes the M3 terrain variable. By default, the relief values are interpreted as meters. If this is not the case, use the “relief_per_m” input to provide a conversion factor (number of relief units per meter).

Inputs:

segments (Segments) – A stream segment network
relief (Raster) – A vertical relief raster
relief_per_m (scalar) – Conversion factor between relief units and meters

Outputs:

ndarray – The M3 terrain variable (T)

static fire(segments, moderate_high)¶

Computes the M3 fire variable

M3.fire(segments, moderate_high)

Computes the M3 fire variable.

Inputs:

segments (Segments) – A stream segment network
moderate_high (Raster) – A moderate-high burn severity raster mask

Outputs:

ndarray – The M3 fire variable (F)

static soil(segments, soil_thickness, omitnan=False)¶

Computes the M3 soil variable

M3.soil(segments, soil_thickness)
M3.soil(..., omitnan=True)

Computes the M3 soil variable. Set omitnan=True to ignore NaN and NoData values in the soil_thickness raster.

Inputs:

segments (Segments) – A stream segment network
soil_thickness (Raster) – A soil thickness raster
omitnan (bool) – True to ignore NaN and NoData values in the soil thickness raster. Default is False.

Outputs:

ndarray – The M3 soil variable (S)

class pfdf.models.staley2017.M4¶

Facilitates the M4 model.

Terrain (T): Proportion of catchment area that both (1) was burned, and (2) has a slope angle >= 30 degrees
Fire (F): Mean catchment dNBR / 1000
Soil (S): Mean catchment soil thickness / 100

classmethod parameters(cls, durations=[15, 30, 60])¶

Return model parameters for the queried durations.

Inputs:

durations (vector) – A list of rainfall durations for which to return model parameters

Outputs:

ndarray – Logistic model intercepts (B)
ndarray – Terrain coefficients (Ct)
ndarray – Fire coefficients (Cf)
ndarray – Soil coefficients (Cs)

static variables(segments, isburned, slopes, dnbr, soil_thickness, omitnan=False)¶

Computes the T, F, and S variables for the M4 model

Inputs:

segments (Segments) – A Segments object defining a stream segment network
isburned (Raster) – A raster mask indicating watershed pixels that were burned (low, moderate or high severity). True elements indicate burned pixels, False elements are not burned.
slopes (Raster) – A raster of slope gradients (not angles) for the watershed
dnbr (Raster) – A dNBR raster for the watershed
soil_thickness (Raster) – A soil thickness raster for the watershed
omitnan (Raster) – A boolean or dict indicating whether to ignore NaN and NoData values in the dnbr and soil_thickness rasters

Outputs:

ndarray – The terrain variable (T) for each stream segment
ndarray – The fire variable (F) for each stream segment
ndarray – The soil variable (S) for each stream segment

static terrain(segments, isburned, slopes)¶

Computes the M4 terrain variable

M4.terrain(segments, isburned, slopes)

Computes the M4 terrain variable.

Inputs:

segments (Segments) – A stream segment network
isburned (Raster) – A burned pixel raster mask
slopes (Raster) – A slope raster

Outputs:

ndarray – The M4 terrain variable (T)

static fire(segments, dnbr, omitnan=False)¶

Computes the M4 fire variable

M4.fire(segments, dnbr)
M4.fire(segments, dnbr, omitnan=True)

Computes the M4 fire variable. Set omitnan=True to ignore NaN and NoData values in the dNBR raster.

Inputs:

segments (Segments) – A stream segment network
dnbr (Raster) – A dNBR raster
omitnan (bool) – True to ignore NaN and NoData values in the dNBR raster. Default is False.

Outputs:

ndarray – The M4 fire variable (F)

static soil(segments, soil_thickness, omitnan=False)¶

Computes the M4 soil variable

M4.soil(segments, soil_thickness)
M4.soil(..., omitnan=True)

Computes the M4 soil variable. Set omitnan=True to ignore NaN and NoData values in the soil_thickness raster.

Inputs:

segments (Segments) – A stream segment network
soil_thickness (Raster) – A soil thickness raster
omitnan (bool) – True to ignore NaN and NoData values in the soil thickness raster. Default is False.

Outputs:

ndarray – The M4 soil variable (S)