Computing Values¶

You’ll often need to compute a physical or statistical value for each segment in the network. Uses for these values include:

Filtering the network to model-worthy segments, and
Inputs to hazard assessment models

This section examines commands that compute such values. We note that Segments objects only compute these values for stream segments in the network, so these commands are typically faster than computing variables over an entire watershed.

Physical Variables¶

The Segments class includes methods to calculate commonly used physical variables for each segment in the network. The following table summarizes these methods:

Method	Description
area	Total catchment area
burn_ratio	The proportion of catchment area that is burned.
burned_area	Burned catchment area
catchment_ratio	The proportion of catchment area within a mask
developed_area	Developed catchment area
confinement	Confinement angle in degrees
in_mask	Whether each segment has pixels within a mask
in_perimeter	Whether each segment has pixels in a fire perimeter
kf_factor	Mean catchment KF-factor
length	The length of each segment along its stream bed
scaled_dnbr	Mean catchment dNBR / 1000
scaled_thickness	Mean catchment soil thickness / 100
sine_theta	Mean catchment sin(θ)
slope	Mean segment slope
relief	Vertical relief to the highest ridge cell
ruggedness	Relief / sqrt(area)

All of these methods return a 1D numpy array with one element per segment. Most require a raster as input, and some require additional inputs:

area = segments.area()
burn_ratio = segments.burn_ratio(isburned)
scaled_dnbr = segments.scaled_dnbr(dnbr)
confinement = segments.confinement(dem, neighborhood)

Ignoring Pixels¶

Many methods have an optional omitnan option. Set this value to True to ignore raster pixels equal to NaN. For example:

# Will ignore NaN pixels when computing summaries
scaled_dnbr = segments.scaled_dnbr(dnbr, omitnan=True)
kf_factor = segments.kf_factor(kf, omitnan=True)

In some cases, the omitnan option may not be sufficient. In this case, all catchment summaries support a mask option, which accepts a boolean Raster mask. False elements of the mask are ignored when computing catchment summaries. For example:

# Will ignore False elements when computing summaries
scaled_dnbr = segments.scaled_dnbr(dnbr, mask)
kf_factor = segments.kf_factor(kf, mask)

Additional Options¶

The area, burned_area, and developed_area methods all return areas in square kilometers (km²) by default. Analogously, the length method uses meters by default. You can use the units option to return values in other units instead:

# Return values in other units
self.area(units="miles")  # Square miles
self.area(units="meters") # Square meters
self.length(units="kilometers")

Separately, you can also configure any catchment summary to only return values for terminal basins by setting the terminal option to True:

# Only returns values for terminal basins
area = segments.area(terminal=True)
burn_ratio = segments.burn_ratio(isburned, terminal=True)
scaled_dnbr = segments.scaled_dnbr(dnbr, terminal=True)

Generic Summaries¶

Some users may want to compute statistical or physical variables not built-in to the class. To support this, the Segments class provides two methods for calculating generic statistical summaries from a raster of data values. The summary method computes a statistical summary over the pixels in each segment (roughly, the pixels in the river bed). Analogously, the catchment_summary method computes statistical summaries over the pixels in each segment’s catchment basin. Both methods support the following statistics:

Key	Description
outlet	The value of the pixel at each segment’s outlet
min	Minimum value
max	Maximum value
mean	Mean
median	Median
std	Standard deviation
sum	Sum of summarized pixels
var	Variance
nanmin	Minimum, ignoring NaN pixels
nanmax	Maximum, ignoring NaN pixels
nanmean	Mean, ignoring NaN pixels
nanmedian	Median, ignoring NaN pixels
nanstd	Standard deviation, ignoring NaN pixels
nansum	Sum, ignoring NaN pixels
nanvar	Variance, ignoring NaN pixels

Some examples:

# Summarize the pixels in the segment
mins = segments.summary("min", raster)
means = segments.summary("mean", raster)
vars = segments.summary("var", raster)

# Summarize the pixels in the catchment
outlets = segments.catchment_summary("outlet", raster)
sums = segments.catchment_summary("sum", raster)
nanmeans = segments.catchment_summary("nanmean", raster)

The catchment_summary method also supports the mask and terminal options described above:

# Only computes values for outlet basins
sums = segments.catchment_summary("sum", raster, terminal=True)
nanmeans = segments.catchment_summary("nanmean", raster, terminal=True)

# Ignores False pixels
sums = segments.catchment_summary("sum", raster, mask)
nanmeans = segments.catchment_summary("nanmean", raster, mask)

Tip

When computing basin summaries, we recommend using the outlet, sum, mean, nansum, or nanmean options whenever possible. The other statistics require a less efficient algorithm, so may take a while to compute. When other statistics are required, then limiting the summary to terminal basins can help improve runtime.

Value Rasters¶

As demonstrated, many of the summary methods require a raster of data values as input. When providing one of these rasters, the raster must match the shape, crs, and affine transformation of the flow directions raster used to derive the stream segment network. As previously described, you can return these values using the raster_shape, crs, and transform properties. You can also return the full flow directions raster using the flow property. If an input raster does not have a crs or transform, then it is assumed to have the same crs or transform as the flow directions raster.

You can also use various methods to visualize the pixels being used in different summaries. There are four common cases for computing segment summaries:

Computing values over the pixels in each stream segment,
Computing values over all pixels in the catchment basin of each stream segement,
Computing values over the pixels in each terminal outlet basin, and
Returning the values at the outlet or terminal outlet pixels.

For case 1, recall that stream segment pixels can be returned using the indices property, and visualized using the raster method method. For case 2, a stream segment catchment basin consists of all pixels that flow into the segment’s outlet pixel, and this can be visualized using the catchment_mask method. For case 3, recall that you can return the IDs of the terminal segments using the terminal_ids property. You can also visualize terminal outlet basins calling the catchment_mask method on terminal IDs. Finally for case 4, note that the outlets method returns the indices of stream segment outlet pixels.