# natcap.invest.pygeoprocessing_0_3_3.routing package¶

## 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. 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 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 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. 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 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 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: flow_direction_uri (string) - (input) – d-infinity flow directions. stream_uri (string) - (input) – all other values ignored must be same dimensions and projection as flow_direction_uri. distance_uri (string) - (output) – 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. factor_uri (string) - (optional input) – is used to multiply the stepsize by for each current pixel, useful for some models to calculate a user defined downstream factor. 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: dem_uri (string) - (input) – elevation values flow_direction_uri (string) - (input/output) – GDAL Dataset with partially defined d_infinity flow directions drain_off_edge (boolean) – the edge of the raster 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