Terrain Engine Reference

Note: This is for reference only, all terrain engine functionality should be accessed via the user facing tools.

fcpgtools.terrainengine.protocols module

Python protocols defining the input/output signature of terrain engine functions.

This module stores abstract methods for all tools.py functions that require a terrain engine. Nesting these methods in @runtime_checkable classes that inherit from typing.Protocol allows function signatures to be verified via our engine_validator.validate_engine decorator.

For more information on Python Protocols see: https://peps.python.org/pep-0544/

class SupportsAccumulateFlow(*args, **kwargs)[source]

Bases: Protocol

abstract accumulate_flow(upstream_pour_points: Optional[PourPointValuesDict] = None, weights: Optional[xarray.DataArray] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a Flow Accumulation Cell (FAC) raster from a D8 Flow Direction Raster.

Parameters

  • d8_fdr – A D8 Flow Direction Raster (dtype=Int).

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • weights – A grid defining the value to accumulate from each cell. Default is a grid of 1s.

  • out_path – Defines a path to save the output raster.

  • **kwargs – keyword arguments, specific options depend on the engine being used.

Returns

The output Flow Accumulation Cells (FAC) raster.

class SupportsAccumulateParameter(*args, **kwargs)[source]

Bases: Protocol

abstract accumulate_parameter(parameter_raster: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a parameter accumulation raster from a D8 Flow Direction Raster and a parameter raster.

A key aspect of this function is that the output DataArray will have dimensions matching param:parameter_raster.

Parameters

  • d8_fdr – A D8 Flow Direction Raster (dtype=Int).

  • parameter_raster – A parameter raster aligned via tools.align_raster() with the us_fdr. This can be multi-dimensional (i.e. f(x, y, t)), and if so, a multi-dimensional output is returned.

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • out_path – Defines a path to save the output raster.

  • **kwargs – keyword arguments, specific options depend on the engine being used.

Returns

The output parameter accumulation raster.

class SupportsDecayAccumulation(*args, **kwargs)[source]

Bases: Protocol

abstract decay_accumulation(decay_raster: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, parameter_raster: Optional[Union[xarray.DataArray, str, Path]] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Creates a D-Infinity based accumulation raster (parameter or cell accumulation) while applying decay via a multiplier_raster.

NOTE: Replaces tools.decayAccum() from V1 FCPGtools.

Parameters

  • dinf_fdr – A flow direction raster in D-Infinity format. This input can be made with tools.d8_to_dinfinity().

  • decay_raster – A decay ‘multiplier’ raster calculated from distance to stream via tools.make_decay_raster().

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • parameter_raster – A parameter raster aligned via tools.align_raster() with the us_fdr. This can be multi-dimensional (i.e. f(x, y, t)), and if so, a multi-dimensional output is returned.

  • out_path – Defines a path to save the output raster.

  • **kwargs – keyword arguments, specific options depend on the engine being used.

Returns

The output decayed accumulation raster.

class SupportsDistanceToStream(*args, **kwargs)[source]

Bases: Protocol

abstract distance_to_stream(fac_raster: Union[xarray.DataArray, str, Path], accum_threshold: int, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Calculates distance each cell is from a stream (as defined by a cell accumulation threshold).

NOTE: Replaces tools.dist2stream() from V1 FCPGtools.

Parameters

  • d8_fdr – A D8 Flow Direction Raster (dtype=Int).

  • fac_raster – A Flow Accumulation Cell (FAC) raster output from accumulate_flow().

  • accum_threshold – The # of upstream/accumulated cells to consider a cell a stream.

  • out_path – Defines a path to save the output raster.

  • **kwargs – keyword arguments, specific options depend on the engine being used.

Returns

A raster with values of D8 flow distance from each cell to the nearest stream.

class SupportsExtremeUpslopeValues(*args, **kwargs)[source]

Bases: Protocol

abstract extreme_upslope_values(parameter_raster: Union[xarray.DataArray, str, Path], mask_streams: Optional[Union[xarray.DataArray, str, Path]] = None, out_path: Optional[Union[str, Path]] = None, get_min_upslope: bool = False, **kwargs) → xarray.DataArray[source]

Finds the max (or min if get_min_upslope=True) value of a parameter grid upstream from each cell in a D8 FDR raster.

NOTE: Replaces tools.ExtremeUpslopeValue() from V1 FCPGtools.

Parameters

  • d8_fdr – A flow direction raster .

  • parameter_raster – A parameter raster to find the max values from.

  • mask_streams – A stream mask raster from tools.mask_streams(). If provided, the output will be masked to only stream cells.

  • out_path – Defines a path to save the output raster.

  • get_min_upslope – If True, the minimum upslope value is assigned to each cell.

  • **kwargs – keyword arguments, specific options depend on the engine being used.

Returns

A raster with max (or min) upstream value of the parameter grid as each cell’s value.

fcpgtools.terrainengine.engine_validator module

validate_engine(protocol)[source]

decorator verify engine argument of function matches required protocol

Validation is performed at runtime. In the engine argument does not match the protocol specified, the decorator will raise a TypeError indicting the required engine type for the original function.

Example usage:

@validate_engine(SupportsFACtoFDR) def my_func(engine:SupportsFACtoFDR):

…

fcpgtools.terrainengine.pysheds_engine module

PySheds terrain engine implementation.

class:PyShedsEngine stores concrete implementation of some terrain engine protocols, PySheds specific helper functions, the engines required D8 format, and a dictionary with valid function kwargs.

For more information on PySheds see the projects documentation: http://mattbartos.com/pysheds/

class PyShedsEngine[source]

Bases: object

static accumulate_flow(d8_fdr: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, weights: Optional[xarray.DataArray] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a Flow Accumulation Cell (FAC) raster from a ESRI format D8 Flow Direction Raster.

NOTE: Replaces tools.tauFlowAccum() from V1 FCPGtools.

Parameters

  • d8_fdr – A ESRI format D8 Flow Direction Raster (dtype=Int).

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • weights – A grid defining the value to accumulate from each cell. Default is a grid of 1s.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional pysheds.Grid.accumulation kwargs.

Returns

The output Flow Accumulation Cells (FAC) raster.

static accumulate_parameter(d8_fdr: Union[xarray.DataArray, str, Path], parameter_raster: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a parameter accumulation raster from a ESRI format D8 Flow Direction Raster and a parameter raster.

A key aspect of this function is that the output DataArray will have dimensions matching param:parameter_raster. NOTE: Replaces tools.accumulateParam() from V1 FCPGtools.

Parameters

  • d8_fdr – A ESRI format D8 Flow Direction Raster (dtype=Int).

  • parameter_raster – A parameter raster aligned via tools.align_raster() with the us_fdr. This can be multi-dimensional (i.e. f(x, y, t)), and if so, a multi-dimensional output is returned.

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional pysheds.Grid.accumulation kwargs.

Returns

The output parameter accumulation raster.

d8_format = 'esri'
function_kwargs = {'accumulate_flow': {'algorithm': <class 'str'>, 'cycle_size': <class 'int'>, 'dirmap': typing.Tuple[int, int, int, int, int, int, int, int], 'efficiency': pysheds.view.Raster, 'fdir': pysheds.view.Raster, 'nodata_out': typing.Union[int, float], 'routing': <class 'str'>, 'weights': pysheds.view.Raster}, 'accumulate_parameter': {'algorithm': <class 'str'>, 'cycle_size': <class 'int'>, 'dirmap': typing.Tuple[int, int, int, int, int, int, int, int], 'efficiency': pysheds.view.Raster, 'fdir': pysheds.view.Raster, 'nodata_out': typing.Union[int, float], 'routing': <class 'str'>, 'weights': pysheds.view.Raster}}

fcpgtools.terrainengine.taudem_engine module

TauDEM terrain engine implementation.

class:TauDEMEngine stores concrete implementation of some terrain engine protocols, TauDEM specific helper functions, the engines required D8 format, and a dictionary with valid function kwargs.

Note that when using the TauDEM terrain engine temporary files will be saved to the current working directory. Additionally, in HPC environments one may need to pass in kwargs={‘mpiCall’: ‘alternative command line call’} if ‘mpiexec’ (default) is not a valid command line term.

For more information on TauDEM see the projects documentation: https://hydrology.usu.edu/taudem/taudem5/

class TauDEMEngine[source]

Bases: object

static accumulate_flow(d8_fdr: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, weights: Optional[xarray.DataArray] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a Flow Accumulation Cell (FAC) raster from a TauDEM format D8 Flow Direction Raster.

NOTE: this is a command line wrapper of TauDEM:aread8 and replaces tools.tauFlowAccum() from V1 FCPGtools.

Parameters

  • d8_fdr – A TauDEM format D8 Flow Direction Raster (dtype=Int).

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • weights – A grid defining the value to accumulate from each cell. Default is a grid of 1s.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional TauDEM:aread8 parameter values using “cores”, “mpiCall”, or “mpiArg” as keys.

Returns

The output Flow Accumulation Cells (FAC) raster.

static accumulate_parameter(d8_fdr: Union[xarray.DataArray, str, Path], parameter_raster: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Create a parameter accumulation raster from a TauDEM format D8 Flow Direction Raster and a parameter raster.

A key aspect of this function is that the output DataArray will have dimensions matching param:parameter_raster. NOTE: This is a command line wrapper of TauDEM:aread8 and replaces tools.accumulateParam() from V1 FCPGtools.

Parameters

  • d8_fdr – A TauDEM format D8 Flow Direction Raster (dtype=Int).

  • parameter_raster – A parameter raster aligned via tools.align_raster() with the us_fdr. This can be multi-dimensional (i.e. f(x, y, t)), and if so, a multi-dimensional output is returned.

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional TauDEM:aread8 parameter values using “cores”, “mpiCall”, or “mpiArg” as keys.

Returns

The output parameter accumulation raster.

d8_format = 'taudem'
static decay_accumulation(d8_fdr: Union[xarray.DataArray, str, Path], decay_raster: Union[xarray.DataArray, str, Path], upstream_pour_points: Optional[PourPointValuesDict] = None, parameter_raster: Optional[Union[xarray.DataArray, str, Path]] = None, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Creates a D-Infinity based accumulation raster (parameter or cell accumulation) while applying decay via a multiplier_raster.

NOTE: This is a command line wrapper of TauDEM:DinfDecayAccum and replaces tools.decayAccum() from V1 FCPGtools.

Parameters

  • dinf_fdr – A flow direction raster in D-Infinity format. This input can be made with tools.tools.d8_to_dinfinity().

  • decay_raster – A decay ‘multiplier’ raster calculated from distance to stream via tools.make_decay_raster().

  • upstream_pour_points – A list of lists each with with coordinate tuples as the first item [0], and updated cell values as the second [1]. This allows the FAC to be made with boundary conditions such as upstream basin pour points.

  • parameter_raster – A parameter raster aligned via tools.align_raster() with the us_fdr. This can be multi-dimensional (i.e. f(x, y, t)), and if so, a multi-dimensional output is returned.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional TauDEM:DinfDecayAccum parameter values using “cores”, “mpiCall”, or “mpiArg” as keys.

Returns

The output decayed accumulation raster.

static distance_to_stream(d8_fdr: Union[xarray.DataArray, str, Path], fac_raster: Union[xarray.DataArray, str, Path], accum_threshold: int, out_path: Optional[Union[str, Path]] = None, **kwargs) → xarray.DataArray[source]

Calculates distance each cell is from a stream (as defined by a cell accumulation threshold).

NOTE: this is a command line wrapper of TauDEM:D8HDistTostrm and replaces tools.dist2stream() from V1 FCPGtools.

Parameters

  • d8_fdr – A TauDEM format D8 Flow Direction Raster (dtype=Int).

  • fac_raster – A Flow Accumulation Cell (FAC) raster output from accumulate_flow().

  • accum_threshold – The # of upstream/accumulated cells to consider a cell a stream.

  • out_path – Defines a path to save the output raster.

  • **kwargs – Can pass in optional TauDEM:D8HDistTostrm parameter values using “cores”, “mpiCall”, or “mpiArg” as keys.

Returns

A raster with values of D8 flow distance from each cell to the nearest stream.

static extreme_upslope_values(d8_fdr: Union[xarray.DataArray, str, Path], parameter_raster: Union[xarray.DataArray, str, Path], mask_streams: Optional[Union[xarray.DataArray, str, Path]] = None, out_path: Optional[Union[str, Path]] = None, get_min_upslope: bool = False, **kwargs) → xarray.DataArray[source]

Finds the max (or min if get_min_upslope=True) value of a parameter grid upstream from each cell in a D8 FDR raster.

NOTE: This is a wrapper for the TauDEM:d8flowpathextremeup and replaces tools.ExtremeUpslopeValue() from V1 FCPGtools.

Parameters

  • d8_fdr – A flow direction raster in TauDEM format.

  • parameter_raster – A parameter raster to find the max values from.

  • mask_streams – A stream mask raster from tools.mask_streams(). If provided, the output will be masked to only stream cells.

  • out_path – Defines a path to save the output raster.

  • get_min_upslope – If True, the minimum upslope value is assigned to each cell.

  • **kwargs – Can pass in optional TauDEM:d8flowpathextremeup parameter values using “cores”, “mpiCall”, or “mpiArg” as keys.

Returns

A raster with max (or min) upstream value of the parameter grid as each cell’s value.

function_kwargs = {'accumulate_flow': {'cores': <class 'int'>, 'fdr': <class 'str'>, 'mpiArg': <class 'str'>, 'mpiCall': <class 'str'>, 'outFl': <class 'str'>}, 'accumulate_parameter': {'cores': <class 'int'>, 'fdr': <class 'str'>, 'mpiArg': <class 'str'>, 'mpiCall': <class 'str'>, 'outFl': <class 'str'>}, 'decay_accumulation': {'cores': <class 'int'>, 'fdr': <class 'str'>, 'mpiArg': <class 'str'>, 'mpiCall': <class 'str'>, 'outFl': <class 'str'>}, 'distance_to_stream': {'cores': <class 'int'>, 'fac': <class 'str'>, 'fdr': <class 'str'>, 'mpiArg': <class 'str'>, 'mpiCall': <class 'str'>, 'outRast': <class 'str'>, 'thresh': <class 'int'>}, 'extreme_upslope_values': {'accum_type': <class 'str'>, 'cores': <class 'int'>, 'fdr': <class 'str'>, 'mpiArg': <class 'str'>, 'mpiCall': <class 'str'>, 'outRast': <class 'str'>, 'param': <class 'str'>}}