Function API Reference

Main user-facing FCPGtools functions.

This file contains the user-facing tools imported when one imports fcpgtools. All functions can accept inputs either as in memory objects (i.e. xarray.DataArray + geopandas.GeoDataFrame) or string/pathlib.Path inputs. Additionally, many functions have a out_path parameter that allows outputs to be saved to a path in addition to the function returning an in-memory object.

See function specific documentation here: https://fcpgtools.readthedocs.io/en/latest/functions.html

See examples of use here: https://fcpgtools.readthedocs.io/en/latest/cookbook.html

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

Parameters:

d8_fdr – A D8 Flow Direction Raster (dtype=Int).
engine – A terrain engine class that supports flow accumulation.
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.

Create a parameter accumulation raster from a D8 FDR 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.
engine – A terrain engine class that supports parameter accumulation.
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.

Adds values to a parameter raster’s at specific coordinates / pour points.

The main utility of this function is to enable cascading accumulation values from one basin or raster to another via accumulate_parameter().

Parameters:

parameter_raster – Input parameter raster to update.
d8_fdr – a D8 Flow Direction Raster.
upstream_pour_points – A dictionary with coordinates to update values at, and the values to add.
out_path – Defines a path to save the output raster.

Returns:

The updated parameter raster.

Aligns the projection/CRS, spatial extent, and resolution of one raster to another.

Parameters:

in_raster – Input raster that needs to be aligned.
match_raster – Raster to align to.
resample_method – A valid resampling method from rasterio.enums.Resample (default=’nearest’). NOTE: Do not use any averaging resample methods when working with a categorical raster!
out_path – Defines a path to save the output raster.

Returns:

The output aligned raster.

Converts a single band categorical raster into a binary multi-band binary raster.

Each output band represent a unique category, where 1 encodes cells belonging the the category, and 0 encodes cells belonging to any other category. This function is used to prep a categorical raster for parameter_accumulate().

Parameters:

cat_raster – A categorical (dtype=int) raster with N unique categories (i.e., land cover classes).
categories_dict – A dictionary assigning string names (values) to integer raster values (keys).
ignore_categories – Category cell values not include in the output raster.
out_path – Defines a path to save the output raster.

Returns:

A N-band multi-dimensional raster as a xarray DataArray object.

Creates an output binary raster based on an input where nodata values -> 1, and valued cells -> 0.

Note: while param:inverse=True this can be used with pyfunc:apply_mask() to match nodata cells between rasters.

Parameters:

in_raster – Input raster.
nodata_value – If the nodata value for param:in_raster is not in the metadata, set this parameter to equal the cell value storing nodata (i.e., np.nan or -999).
out_path – Defines a path to save the output raster.

Returns:

The output binary mask raster.

check_function_kwargs(function: callable, engine: str) → Dict[str, str | int | float][source]

Provides a dictionary of allowed kwargs keywords + input types for a function.

NOTE: This function will raise a ValueError if a non-terrain_engine: function is provided as the input.

Parameters:

function – A function belonging to a terrain_engine class.
engine – The name of the engine being used.

Returns:

A dictionary with allowed kwargs as keys, and allowed input types as values.

Clips a raster to the rectangular extent (aka bounding box) of another raster (or shapefile).

Parameters:

in_raster – Input raster.
match_raster – If defined, in_raster is clipped to match the extent of match_raster.
match_shapefile – A shapefile that is used to define the output extent if match_raster == None.
out_path – Defines a path to save the output raster.
custom_bbox – A list with bounding box coordinates that define the output extent if match_raster == None. Note: Coordinates must be of the form [minX, minY, maxX, maxY]. Note: Using this parameter assumes that coordinates match the CRS of param:in_raster.

Returns:

The input raster clipped by the desired geometry.

Converts the D8 encoding of Flow Direction Rasters (FDR).

Parameters:

d8_fdr – The input D8 Flow Direction Raster (FDR).
out_format – A valid D8 flow direction format name in custom_types.D8ConversionDicts.keys().
in_format – A valid D8 flow direction format name in custom_types.D8ConversionDicts.keys() that overrides the auto-recognized format from param:d8_fdr. Note: manually inputting param:in_format will improve performance.
out_path – Defines a path to save the output raster.

Returns:

The re-encoded D8 Flow Direction Raster (FDR).

d8_to_dinfinity(d8_fdr: xarray.DataArray | str | Path, out_path: str | Path | None = None) → xarray.DataArray[source]

Converts a D8 Flow Direction Raster to D-Infinity.

Parameters:

d8_fdr – A D8 Flow Direction Raster (dtype=int).
out_path – Defines a path to save the output raster.

Returns:

The output D-Inf Flow Direction Raster.

Creates a “decayed” D-Infinity based accumulation raster via a decay raster.

NOTE: Replaces tools.decayAccum() from V1 FCPGtools. This can be used to accumulate a parameter or just cells counts.

Parameters:

dinf_fdr – A flow direction raster in D-Infinity format. This input can be made with d8_to_dinfinity().
decay_raster – A decay ‘multiplier’ raster calculated from distance to stream via make_decay_raster().
engine – A terrain engine class that supports decayed accumulation.
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 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.

Calculates cell distances from accumulation threshold defined streams.

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.
engine – A terrain engine class that supports calculating distance to 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.

Finds the max(default)/min value of a parameter grid upstream from each cell.

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.
engine – A terrain engine class that supports finding extreme upslope values.
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.

find_basin_pour_points(fac_raster: xarray.DataArray | str | Path, basins_shp: str, basin_id_field: str = 'HUC12', use_huc4: bool = True) → PourPointLocationsDict[source]

Find pour points (aka outflow cells) in a FAC raster by basin using a shapefile.

Parameters:

fac_raster – A Flow Accumulation Cell raster (FAC).
basins_shp – A .shp shapefile containing basin geometries.
basin_id_field – Default behavior is for each GeoDataFrame row to be a unique basin. However, if one wants to use a higher level basin id that is shared across rows, this should be set to the column header storing the higher level basin id.
use_huc4 – Either ‘HUC4’ or ‘HUC12’.

Returns:

A dictionary with keys (i.e., basin IDs) storing coordinates as a tuple(x, y).

find_fac_pour_point(fac_raster: xarray.DataArray | str | Path, basin_name: str | int | None = None) → PourPointLocationsDict[source]

Find pour points (aka outflow cells) in a FAC raster by basin using a shapefile.

Parameters:

fac_raster – A Flow Accumulation Cell raster (FAC).
basin_name – Allows a name to be given to the FAC.

Returns:

A dictionary with keys (i.e., basin IDs) storing coordinates as a tuple(x, y).

get_pour_point_values(pour_points_dict: PourPointLocationsDict, accumulation_raster: xarray.DataArray | str | Path) → PourPointValuesDict[source]

Get the accumulation raster values from downstream pour points.

NOTE: This function is intended to feed into accumulate_flow() or parameter_accumulate() param:upstream_pour_points.

Parameters:

pour_points_dict – A dictionary of form custom_types.PourPointValuesDict.
accumulation_raster – A Flow Accumulation Cell raster (FAC) or a parameter accumulation raster.

Returns:

A list of tuples (one for each pour point) storing their coordinates [0]: and accumulation value [1].

load_raster(in_raster: xarray.DataArray | str | Path) → xarray.DataArray[source]: Loads a raster into a xarray.DataArray object.

load_shapefile(in_shapefile: geopandas.GeoDataFrame | str | Path) → geopandas.GeoDataFrame[source]: Loads a shapefile into a geopandas.GeoDataFrame

Creates a decay raster based on distance to stream.

This function is used to prep for decay_accumulate(). Grid cell values are computed as the inverse number of grid cells, np.exp((-1 * distance_to_stream * cell_size) / (cell_size ** k)), where k is a constant applied to the cell size values.

Parameters:

distance_to_stream_raster – A distance to stream raster output from distance_to_stream().
decay_factor – Dimensionless constant applied to decay factor denominator. NOTE: Set k to 2 for ‘moderate’ decay; greater than 2 for slower decay; or less than 2 for faster decay.
out_path – Defines a path to save the output raster.

Returns:

The output decay raster for use in decay_accumulate().

Preps param:parameter_raster for parameter accumulation by matching the nodata boundary to param:fdr_raster.

NOTE: Only this function AFTER aligning the parameter raster to the FDR raster via tools.align_raster()!

Parameters:

parameter_raster – A parameter raster.
fdr_raster – A Flow Direction Raster (either D8 or D-inf).
out_of_bounds_value – The value to give param:parameter_raster cells outside the data boundary of param:fdr_raster. Note that this is automatically set within terrain_engine functions.
out_path – defines a path to save the output raster.

Returns:

The prepped parameter grid.

Creates a Flow Conditioned Parameter Grid raster by dividing a parameter accumulation raster by a Flow Accumulation Cell (FAC) raster.

Parameters:

param_accum_raster – (xr.DataArray or str raster path)
fac_raster – (xr.DataArray or str raster path) input FAC raster.
out_path – (str or pathlib.Path, default=None) defines a path to save the output raster.

Returns:

The output FCPG raster as a xarray DataArray object.

A simplified version of tools.value_mask() that outputs np.nan for non-‘stream’ cells below the accumulation threshold.

Parameters:

fac_raster – A single band flow accumulation (FAC) raster.
accumulation_threshold – The flow accumulation threshold.

Returns:

The output raster with cells below the threshold encoded as np.nan

Reprojects a raster to match another shapefile/raster’s Coordinate Reference System (CRS), or a custom CRS.

Parameters:

in_raster – Input raster.
out_crs – A raster or shapefile with the desired CRS to reproject to.
resolution – Allows the output resolution to be overridden.
wkt_string – Allows the user to define the output CRS using a custom valid WKT string.
out_path – Defines a path to save the output raster.

Returns:

The input raster reprojected to match the desired Coordinate Reference System (CRS).

Reprojects a shapefile to match another shapefile/raster’s Coordinate Reference System (CRS), or a custom CRS.

Parameters:

in_shapefile – Input shapefile/GeoDataFrame.
out_crs – A raster or shapefile with the desired CRS to reproject to.
wkt_string – Allows the user to define the output CRS using a custom valid WKT string.
out_path – Defines a path to save the output shapefile.

Returns:

The input shapefile reprojected to match the desired Coordinate Reference System (CRS).

Resamples a raster to match another raster’s cell size.

Parameters:

in_raster – Input raster.
match_raster – A raster to match the resolution / cell size of.
method – A valid resampling method from rasterio.enums.Resample. NOTE: Do not use any averaging resample methods when working with a categorical raster!
out_path – Defines a path to save the output raster.

Returns:

The input raster resampled to the desired resolution / cell size.

save_raster(out_raster: xarray.DataArray, out_path: str | Path) → None[source]: Saves an xarray.DataArray to a .tif raster file at location param:out_path

save_shapefile(out_shapefile: geopandas.GeoDataFrame, out_path: str | Path) → None[source]: Saves an geopandas.GeoDataFrame to a .shp file at location param:out_path

Applies a spatial mask via a shapefile to a raster.

Primarily for masking rasters (i.e., FAC) by basin shapefiles, converting out-of-mask raster values to NoData. A cell value can also be used to create a mask for integer rasters. NOTE: default behavior (inverse=False) will make it so cells NOT COVERED by mask_shp -> NoData.

Parameters:

in_raster – Input raster.
mask_shp – Shapefile used for masking.
inverse – If True, cells that ARE COVERED by mask_shp -> NoData.
out_path – Defines a path to save the output raster.

Returns:

The output spatially masked raster.

“Mask a raster via a value threshold.

Primary use case is to identify high accumulation zones / stream cells. Cells included in the mask are given a value of 1, all other cells are given a value of 0 (unless out_mask_value!=None). NOTE: this function generalizes V1:pyfunc:makeStreams() functionality.

Parameters:

in_raster – Input raster.
thresh – The threshold to apply the value mask with.
greater_than – If False, only values less than param:thresh are included in the mask.
equals – Only cells matching the value of param:equals are included in the mask.
inverse_equals – Is True and param:equals==True, values NOT equal to :param:thresh are masked out.
in_mask_value – Allows included cells to be given a non-zero integer value.
out_mask_value – Allows non-included cells to be given a non-zero integer value.
out_path – Defines a path to save the output raster.

Returns:

out_mask_value.

Return type:

The output raster with all masked out values == nodata or param