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:

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.

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:	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
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