natcap.invest.pygeoprocessing_0_3_3.routing package

Submodules

natcap.invest.pygeoprocessing_0_3_3.routing.routing module

Routing functions to simulate overland flow on GIS rasters defined by DEM raster datasets.

Here are some conventions of this model:

A single pixel defines its neighbors as follows:

3 2 1 4 p 0 5 6 7

The ‘p’ refers to ‘pixel’ since the flow model is pixel centric.

One of the outputs from this model will be a flow graph represented as a sparse matrix. The rows in the matrix are the originating nodes and the columns represent the outflow, thus G[i,j]’s value is the fraction of flow from node ‘i’ to node ‘j’. The following expresses how to calculate the matrix indexes from the pixels original row,column position in the raster. Given that the raster’s dimension is ‘n_rows’ by ‘n_columns’, pixel located at row ‘r’ and colunn ‘c’ has index

(r,c) -> r * n_columns + c = index

Likewise given ‘index’ r and c can be derived as:

(index) -> (index div n_columns, index mod n_columns) where ‘div’ is
the integer division operator and ‘mod’ is the integer remainder operation.
natcap.invest.pygeoprocessing_0_3_3.routing.routing.delineate_watershed(dem_uri, outlet_shapefile_uri, snap_distance, flow_threshold, watershed_out_uri, snapped_outlet_points_uri, stream_out_uri)

Delinate watershed based on the DEM and the outlet points specified.

The algorithm will attempt to snap the outlet point to the nearest stream defined by a d-infinity flow accumulation raster thresholded by the ‘flow_threshold’ parameter.

Parameters:
  • dem_uri (string) – uri to DEM layer
  • outlet_shapefile_uri (string) – a shapefile of points indicating the outflow points of the desired watershed.
  • snap_distance (int) – distance in pixels to search for a stream pixel to snap the outlet to
  • flow_threshold (int) – threshold value to classify a stream pixel from the flow accumulation raster
  • watershed_out_uri (string) – the uri to output the shapefile
  • snapped_outlet_points_uri (string) – the uri to output snapped points
  • stream_out_uri (string) – the uri to a raster masking the stream layer
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.distance_to_stream(flow_direction_uri, stream_uri, distance_uri, factor_uri=None)

Calculate the flow downhill distance to the stream layers.

Parameters:
  • flow_direction_uri (string) – a raster with d-infinity flow directions
  • stream_uri (string) – a raster where 1 indicates a stream all other values ignored must be same dimensions and projection as flow_direction_uri.
  • distance_uri (string) – an output raster that will be the same dimensions as the input rasters where each pixel is in linear units the drainage from that point to a stream.
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.fill_pits(dem_uri, dem_out_uri)

Fill regions in DEM that don’t drain to the edge of dataset.

The resulting DEM will likely have plateaus where the pits are filled.

Parameters:
  • dem_uri (string) – the original dem URI
  • dem_out_uri (string) – the original dem with pits raised to the highest drain value
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.flow_accumulation(flow_direction_uri, dem_uri, flux_output_uri, aoi_uri=None)

Calculate flow accumulation.

A helper function to calculate flow accumulation, also returns intermediate
rasters for future calculation.
Parameters:
  • flow_direction_uri (string) – a uri to a raster that has d-infinity flow directions in it
  • dem_uri (string) – a uri to a gdal dataset representing a DEM, must be aligned with flow_direction_uri
  • flux_output_uri (string) – location to dump the raster representing flow accumulation
  • aoi_uri (string) – (optional) uri to a datasource to mask out the dem
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.flow_direction_d_inf(dem_uri, flow_direction_uri)

Calculate the D-infinity flow algorithm.

The output is a float raster whose values range from 0 to 2pi.
Algorithm from: Tarboton, “A new method for the determination of flow directions and upslope areas in grid digital elevation models,” Water Resources Research, vol. 33, no. 2, pages 309 - 319, February 1997.
Parameters:
  • dem_uri (string) – (input) a uri to a single band GDAL Dataset with elevation values
  • flow_direction_uri (string) – (output) a uri to a single band GDAL dataset with d infinity flow directions in it.
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.pixel_amount_exported(in_flow_direction_uri, in_dem_uri, in_stream_uri, in_retention_rate_uri, in_source_uri, pixel_export_uri, aoi_uri=None, percent_to_stream_uri=None)
Calculate flow and absorption rates to determine the amount of source
exported to the stream.
All datasets must be in the same projection. Nothing will be retained on
stream pixels.
Parameters:
  • in_dem_uri (string) – a dem dataset used to determine flow directions
  • in_stream_uri (string) – an integer dataset representing stream locations. 0 is no stream 1 is a stream
  • in_retention_rate_uri (string) – a dataset representing per pixel retention rates
  • in_source_uri (string) – a dataset representing per pixel export
  • pixel_export_uri (string) – the output dataset uri to represent the amount of source exported to the stream
  • percent_to_stream_uri (string) – (optional) if defined is the raster that’s the percent of export to the stream layer
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing.route_flux(in_flow_direction, in_dem, in_source_uri, in_absorption_rate_uri, loss_uri, flux_uri, absorption_mode, aoi_uri=None, stream_uri=None, include_source=True)

Route flux across DEM to guide flow from a d-infinty flow algorithm.

This function will route flux across a landscape given a dem to guide flow from a d-infinty flow algorithm, and a custom function that will operate on input flux and other user defined arguments to determine nodal output flux.

Parameters:
  • in_flow_direction (string) – a URI to a d-infinity flow direction raster
  • in_dem (string) – a uri to the dem that generated in_flow_direction, they should be aligned rasters
  • in_source_uri (string) – a GDAL dataset that has source flux per pixel
  • in_absorption_rate_uri (string) – a GDAL floating point dataset that has a percent of flux absorbed per pixel
  • loss_uri (string) – an output URI to to the dataset that will output the amount of flux absorbed by each pixel
  • flux_uri (string) – a URI to an output dataset that records the amount of flux travelling through each pixel
  • absorption_mode (string) – either ‘flux_only’ or ‘source_and_flux’. For ‘flux_only’ the outgoing flux is (in_flux * absorption + source). If ‘source_and_flux’ then the output flux is (in_flux + source) * absorption.
  • aoi_uri (string) – an OGR datasource for an area of interest polygon. the routing flux calculation will only occur on those pixels and neighboring pixels will either be raw outlets or non-contibuting inputs depending on the orientation of the DEM.
  • stream_uri (string) – (optional) a GDAL dataset that classifies pixels as stream (1) or not (0). If during routing we hit a stream pixel, all upstream flux is considered to wash to zero because it will reach the outlet. The advantage here is that it can’t then route out of the stream
  • include_source (boolean) – if True, source is added to current pixel, otherwise pixel starts at 0.
  • Returns – None
natcap.invest.pygeoprocessing_0_3_3.routing.routing.stream_threshold(flow_accumulation_uri, flow_threshold, stream_uri)

Create a raster of accumulated flow to each cell.

Parameters:
  • flow_accumulation_uri (string) – A flow accumulation dataset of type floating point
  • flow_threshold (float) – a number indicating the threshold to declare a pixel a stream or no
  • stream_uri (string) – the uri of the output stream dataset
Returns:

None

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core module

class natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.BlockCache

Bases: object

band_list = []
block_list = []
update_list = []
natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.calculate_flow_weights()

This function calculates the flow weights from a d-infinity based flow algorithm to assist in walking up the flow graph.

flow_direction_uri - uri to a flow direction GDAL dataset that’s
used to calculate the flow graph
outflow_weights_uri - a uri to a float32 dataset that will be created
whose elements correspond to the percent outflow from the current cell to its first counter-clockwise neighbor
outflow_direction_uri - a uri to a byte dataset that will indicate the

first counter clockwise outflow neighbor as an index from the following diagram

3 2 1 4 x 0 5 6 7

returns nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.delineate_watershed()
natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.distance_to_stream()

This function calculates the flow downhill distance to the stream layers

Parameters:
  • (string) - (input) a path to a raster with (flow_direction_uri) – d-infinity flow directions.
  • (string) - (input) a raster where 1 indicates a stream (stream_uri) – all other values ignored must be same dimensions and projection as flow_direction_uri.
  • (string) - (output) a path to the output raster that (distance_uri) – will be created as same dimensions as the input rasters where each pixel is in linear units the drainage from that point to a stream.
  • (string) - (optional input) a floating point raster that (factor_uri) – is used to multiply the stepsize by for each current pixel, useful for some models to calculate a user defined downstream factor.
Returns:

nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.fill_pits()

This function fills regions in a DEM that don’t drain to the edge of the dataset. The resulting DEM will likely have plateaus where the pits are filled.

dem_uri - the original dem URI dem_out_uri - the original dem with pits raised to the highest drain

value

returns nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.flow_direction_inf()
Calculates the D-infinity flow algorithm. The output is a float

raster whose values range from 0 to 2pi.

Algorithm from: Tarboton, “A new method for the determination of flow directions and upslope areas in grid digital elevation models,” Water Resources Research, vol. 33, no. 2, pages 309 - 319, February 1997.

Also resolves flow directions in flat areas of DEM.

dem_uri (string) - (input) a uri to a single band GDAL Dataset with elevation values flow_direction_uri - (input/output) a uri to an existing GDAL dataset with

of same as dem_uri. Flow direction will be defined in regions that have nodata values in them. non-nodata values will be ignored. This is so this function can be used as a two pass filter for resolving flow directions on a raw dem, then filling plateaus and doing another pass.

returns nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.flow_direction_inf_masked_flow_dirs()
Calculates the D-infinity flow algorithm for regions defined from flat

drainage resolution.

Flow algorithm from: Tarboton, “A new method for the determination of flow directions and upslope areas in grid digital elevation models,” Water Resources Research, vol. 33, no. 2, pages 309 - 319, February 1997.

Also resolves flow directions in flat areas of DEM.

flat_mask_uri (string) - (input) a uri to a single band GDAL Dataset
that has offset values from the flat region resolution algorithm. The offsets in flat_mask are the relative heights only within the flat regions defined in labels_uri.
labels_uri (string) - (input) a uri to a single band integer gdal
dataset that contain labels for the cells that lie in flat regions of the DEM.
flow_direction_uri - (input/output) a uri to an existing GDAL dataset
of same size as dem_uri. Flow direction will be defined in regions that have nodata values in them that overlap regions of labels_uri. This is so this function can be used as a two pass filter for resolving flow directions on a raw dem, then filling plateaus and doing another pass.

returns nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.percent_to_sink()

This function calculates the amount of load from a single pixel to the source pixels given the percent export rate per pixel.

sink_pixels_uri - the pixels of interest that will receive flux.
This may be a set of stream pixels, or a single pixel at a watershed outlet.
export_rate_uri - a GDAL floating point dataset that has a percent
of flux exported per pixel
outflow_direction_uri - a uri to a byte dataset that indicates the

first counter clockwise outflow neighbor as an index from the following diagram

3 2 1 4 x 0 5 6 7

outflow_weights_uri - a uri to a float32 dataset whose elements
correspond to the percent outflow from the current cell to its first counter-clockwise neighbor
effect_uri - the output GDAL dataset that shows the percent of flux
emanating per pixel that will reach any sink pixel

returns nothing

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.resolve_flats()

Function to resolve the flat regions in the dem given a first attempt run at calculating flow direction. Will provide regions of flat areas and their labels.

Based on: Barnes, Richard, Clarence Lehman, and David Mulla. “An
efficient assignment of drainage direction over flat surfaces in raster digital elevation models.” Computers & Geosciences 62 (2014): 128-135.
Parameters:
  • (string) - (input) a uri to a single band GDAL Dataset with (dem_uri) – elevation values
  • (string) - (input/output) a uri to a single band (flow_direction_uri) – GDAL Dataset with partially defined d_infinity flow directions
  • (boolean) - input if true will drain flat areas off (drain_off_edge) – the edge of the raster
Returns:

True if there were flats to resolve, False otherwise

natcap.invest.pygeoprocessing_0_3_3.routing.routing_core.route_flux()

This function will route flux across a landscape given a dem to guide flow from a d-infinty flow algorithm, and a custom function that will operate on input flux and other user defined arguments to determine nodal output flux.

in_flow_direction - a URI to a d-infinity flow direction raster in_dem - a uri to the dem that generated in_flow_direction, they

should be aligned rasters

in_source_uri - a GDAL dataset that has source flux per pixel in_absorption_rate_uri - a GDAL floating point dataset that has a

percent of flux absorbed per pixel
loss_uri - an output URI to to the dataset that will output the
amount of flux absorbed by each pixel
flux_uri - a URI to an output dataset that records the amount of flux
travelling through each pixel
absorption_mode - either ‘flux_only’ or ‘source_and_flux’. For
‘flux_only’ the outgoing flux is (in_flux * absorption + source). If ‘source_and_flux’ then the output flux is (in_flux + source) * absorption.
aoi_uri - an OGR datasource for an area of interest polygon.
the routing flux calculation will only occur on those pixels and neighboring pixels will either be raw outlets or non-contibuting inputs depending on the orientation of the DEM.
stream_uri - (optional) a GDAL dataset that classifies pixels as stream
(1) or not (0). If during routing we hit a stream pixel, all upstream flux is considered to wash to zero because it will reach the outlet. The advantage here is that it can’t then route out of the stream
include_source - if True, source is added to current pixel, otherwise
pixel starts at 0.

returns nothing

Module contents

__init__ module for routing that cleans up the namespace of the functions inside the routing source