Migrating to FCPGtools Version 2.0

New in Version 2.0

Version 2.0 of FCPGtools is a complete rebuild of Version 1.0. Backwards compatibility is not preserved, and many workflows have been significantly streamlined. We strongly recommend that users who are familiar with Version 1.0 refer to our updated function documentation.

Key Updates

• All functions output an in-memory xarray.DataArray object, allowing for functions to be strung together into performance-oriented pipelines.

  • xarray.DataArray objects have a variety of powerful features and optimizations. For more information, please reference the library’s documentation.

  • Rasters can still be saved to a local GeoTIFF file by providing a valid .tif path to param:out_path.

• All functions can now accept either local string paths, local pathlib.Path objects, or in-memory xarray.DataArray objects.

• Multi-band parameter grids are now supported!

  • For example, passing a 12-month precipitation raster (where each month is a raster band) into fcpgtools.accumulate_parameter() will output a 12-band xarray.DataArray object.

• Conversion of flow direction raster (FDR) formats (i.e. ESRI -> TauDEM) is now automated behind-the-scenes.

• Support for multiple “terrain engines” gives users additional optionality and increases the resilience to dependency deprecation (see below).

  • Where necessary users can set param:engine to taudem (default) or pysheds.

  • Note that the pysheds terrain engine is significantly more performant, but currently only supports accumulate_flow() and accumulate_parameter().

Using the engine parameter

As mentioned above, some functions now require a “terrain engine” to be specified through the param:engine parameter (i.e., accumulate_flow()). Under the hood, we use a Python Protocols-based implementation that will raise an error if the specified terrain engine does not support the function being called. All of these functions have a valid default terrain engine, so an error will only be raised if the user chooses to override the default in a unsupported way. While this may seem redundant, it enables more “terrain engines” to be incorporated in the future (i.e. WhiteBox) without altering the user experience in any way, other than the number of valid engine string arguments.

Mapping of Version 1.1 to Version 2.0 FCPGtools Functions

I/O Functions

• loadRaster() -> load_raster()

• getFeatures() -> load_shapefile()

Key Use-Case Functions

• resampleParam() -> align_raster()

• tauFlowAccum() -> accumulate_flow()

• accumulateParam() -> accumulate_parameter()

• make_fcpg() -> make_fcpg()

• maskStreams() -> mask_streams()

• dist2stream() -> distance_to_stream()

• makeDecayGrid() -> make_decay_raster()

• decayAccum() -> decay_accumulation()

• ExtremeUpslopeValue() -> extreme_upslope_values()

Pour Points / Cascade Functions

• findLastFACFD() -> find_fac_pour_point() Output is of type

• makePourBasins() and findPourPoints() -> find_basin_pour_points()
  which uses a basin shapefile to find outflow points.

  • Output is of type custom_types.PourPointLocationsDict.

  • Note: In V2 find_fac_pour_point() gets the location of the outflow point for a full FAC, which is then fed into _find_downstream_cell() within _update_raster_values().

• createUpdateDict() -> get_pour_point_values()

  • The output is of type custom_types.PourPointValuesDict.

  • Note: The pour points workflow is somewhat different in V2, where the output of either find_basin_pour_points() or find_fac_pour_point() is appended with the pour point values within get_pour_point_values().

---

Functions made redundant but still accessible

• makeFACweight() -> make_fac_weights()

• adjustParam -> adjust_parameter_raster()

• d8todinfinity() -> d8_to_dinfinity()

• tauDrainDir() and ESRIDrainDir() -> convert_fdr_formats()

  • Note: FDR format conversion is now done automatically behind-the-scenes.

  • See custom_types.D8ConversionDicts for FDR format mappings.

Functions moved to fcpgtools.utilities (wrapped into higher level functions)

• FindDownstreamCellTauDir() -> _find_downstream_cell()

• changeNoData() -> _change_nodata_value()

• queryPoint() -> _query_point()

• updateRaster() -> _update_raster_values()

---

Completely removed functions (no longer necessary for use-cases)

• resampleParam_batch(), accumulateParam_batch(), and make_fcpg_batch() are made redundant in V2 by utilizing f(x, y, t) rasters via xarray.DataArray objects.

• makeStreams() -> made redundant by mask_streams().

• cat2bin() and binarizeCat() are combined into binarize_categorical_raster() by utilizing f(x, y, t) rasters via xarray.DataArray objects.

• parsebool() -> not necessary in V2.

• applyMult() -> not necessary in V2.