landlab.utils.source_tracking_algorithm module#

Source Tracking Algorithm#

convert_arc_flow_directions_to_landlab_node_ids(...)

Convert Arc flow_directions to RasterModelGrid node ids.

track_source(grid, hsd_ids[, flow_directions])

Track all contributing upstream core nodes for each core node.

find_unique_upstream_hsd_ids_and_fractions(...)

Finds unique entries in hsd_upstr.values()

Authors: Sai Nudurupati & Erkan Istanbulluoglu

Ref 1: ‘The Landlab LandslideProbability Component User Manual’ @ https://github.com/RondaStrauch/pub_strauch_etal_esurf/blob/master/LandslideComponentUsersManual.pdf

Notation

Definition

MD

Modeling Domain - Raster grid that is being analyzed/worked upon.

HSD

Hydrologic Source Domain - Grid that is at least as coarse as MD. For more info, refer Ref 1
convert_arc_flow_directions_to_landlab_node_ids(grid, flow_dir_arc)[source]#

Convert Arc flow_directions to RasterModelGrid node ids.

This function receives flow directions (D8) from ESRI ArcGIS and converts them to Landlab’s RasterModelGrid node id. ESRI ArcGIS D8 flow directions are either of the eight valid output directions relating to the eight adjacent cells into which flow could travel. The valid output directions are powers of 2 starting from 2^0 (1) in the Eastern neighbor going clockwise to 2^7 (128) at Northeastern neighbor. For more information refer ‘https://pro.arcgis.com/en/pro-app/tool-reference/spatial-analyst/ how-flow-direction-works.htm’

Parameters:

  • grid (RasterModelGrid) – A grid.

  • flow_dir_arc (ndarray of int, shape (n_nodes, )) – flow directions derived from ESRII ArcGIS.

Returns:

receiver_nodes – downstream node at each node. Note that this array gives the receiver nodes only for the core nodes. For non-core nodes, a zero is used.

Return type:

ndarray of int, shape (n_nodes, )

find_unique_upstream_hsd_ids_and_fractions(hsd_upstr)[source]#

Finds unique entries in hsd_upstr.values()

This function operates on hsd_upstr.values(), that are lists of hsd_ids. Two new Python dictionaries, ‘unique_ids’ and ‘fractions’ are created.

unique_ids.keys() = hsd_upstr.keys() unique_ids.values()[i] = list of unique entries in hsd_upstr.values()[i]

fractions.keys() = hsd_upstr.keys() fractions.values()[i] = (number of entries of each unique_id.values()[i]/ length of hsd_upstr.values()[i]) for each unique_id.values()[i] in the same order.

Note that ‘hsd_upstr’ is the output of track_source(). You can use an alternative input. In that case, please refer to the documentation of track_source() or refer source_tracking_algorithm_user_manual for more information.

Parameters:

hsd_upstr (dictionary) – ‘hsd_upstr’ maps each MD grid node to corresponding contributing upstream HSD ids.

Returns:

(unique_ids, fractions) – Tuple of data. ‘unique_ids’ maps each MD node with all upstream HSD ids without repitition. ‘fractions’ maps each MD node with the fractions of contributions of the corresponding upstream HSD ids in the same order as uniques_ids[node_id].

Return type:

(dictionary, dictionary)

track_source(grid, hsd_ids, flow_directions=None)[source]#

Track all contributing upstream core nodes for each core node.

This algorithm traverses the grid based on information of flow directions at nodes and at every node identifies all the nodes upstream of a given node. The algorithm creates a dictionary with an entry for each node; a node’s entry in the dictionary will contain a list with the node_ids of all upstream nodes. Thus this method permits identification of the source area contributing to each and every node in the model grid. This function is different from a standard flow accumulation routine in that it not only calculates the amount of flow at each node, but records the IDs of all upstream nodes. However, similar to a standard flow accumulation routine, it produces an at_node array of the amount of flow passing through the node. It also differs from a standard flow accumulation routing in that it permits the mapping of flow inputs from a coarser grid to to a finer model grid.

In its present implementation, the algorithm has not been optimized for efficient time use. Its methods are brute force and it should be expected to be time intensive. It is not recommended to be run frequently in a modeling exercise. Due to its intensive nature, this algorithm may fail with large watersheds (a present, the development team has not derived a maximum stable watershed size).

This function was initially developed to find contributing area of a 30 m grid (MD), where the quantitative data that we were interested in was available in significantly coarser resolution (called Hydrologic Source Domain (HSD)). Therefore, we started working with re-sampled HSD, that is at the same resolution as MD, and represents exactly the same landscape. Alternatively, one can use the node ids of MD (grid.nodes.flatten()) as input for hsd_ids.

For more information, refer Ref 1.

Parameters:

  • grid (RasterModelGrid) – A grid.

  • hsd_ids (ndarray of int, shape (n_nodes, )) – array that maps the nodes of the grid to, possibly coarser, Hydrologic Source Domain (HSD) grid ids.

  • flow_directions (ndarray of int, shape (n_nodes, ), optional.) – downstream node at each node. Alternatively, this data can be provided as a nodal field ‘flow__receiver_node’ on the grid.

Returns:

(hsd_upstr, flow_accum) – ‘hsd_upstr’ maps each grid node to corresponding contributing upstream hsd_ids. hsd_upstr.keys() will return node_ids of the grid. hsd_upstr.values() will return lists of all upstream contributing hsd_ids, including repitions of hsd_ids, at corresponding node_ids. ‘flow_accum’ is an array of the number of upstream contributing nodes at each node.

Return type:

(dictionary, ndarray of shape (n_nodes))