Skip to content

Misc updates for 2.0.0

King, Jonathan M requested to merge ghsc/users/jking/pfdf:polish2 into main

Summary

This MR provides the final planned code updates for 2.0.0. (Note that there will still be a documentation MR following this).

Closes #94 (closed), #103 (closed), #106 (closed), #110 (closed), #126 (closed), #133 (closed), #134 (closed), #135 (closed), #136 (closed), #137 (closed), #138 (closed), #139 (closed)

Details

Non-metric datasets

Most functions in pfdf are unit agnostic. However, several routines expect metric units and now include options to convert non-metric data to meters.

  • watershed.slopes: via the new "dem_per_m" option
  • segments.confinement: the "dem_per_m" option replaces the old "factor" option, which was a less clear name
  • segments.ruggedness: via the "relief_per_m" option
  • staley2017.M3.terrain: via the "relief_per_m" option
  • staley2017.M3.variables: also via the "relief_per_m" option (it's just calling the terrain function under-the-hood)

Slopes for geographic CRS

Formerly, slopes were calculated as rise (meters) / run (CRS units). This required users to convert units when using a geographic CRS with units of degrees, as opposed to a projected CRS in meters. The code now performs this conversion automatically:

  • watershed.slopes: In the final code block

Raster.from_array

Formerly, the Raster class included .from_array and ._from_array methods. The internal method did not copy the input array, whereas the public method did. This was to prevent users from altering a Raster's base array. However, copying is not desirable when using a very large dataset, so I have replaced the internal method with a "copy" option in the public method. The docstring for this option also warns the user against altering the base array.

  • Raster._from_array: Removed
  • Raster.from_array: Added "copy" option

Informative Memory Errors

Several Raster preprocessors can trigger memory errors when trying to build a large array. This are issued by numpy, and are not very clear. I've supplemented these errors to help the user understand what's actually happening.

  • errors.handle_memory_error: Detects and supplements a memory error
  • Raster.from_points: line 1177
  • Raster.from_polygons: line 1326
  • Raster.buffer: line 1997
  • Raster.reproject: line 2168
  • Raster.clip via _utils.clip: line 78

Metric by default

The Raster and Segments class now use metric units default. Formerly, the code used affine Transform/CRS base units. Functions with unit options now include a "base_units" option to restore the old behavior.

  • watershed.network
  • Raster: dx, dy, resolution, pixel_area, pixel_diagonal, from_points, from_polygons
  • Segments: init, area, burned_area, developed_area, ruggedness
  • Raster.from_points/polygons: Uses 10m resolution by default

Removed missing NoData options

Formerly, preprocessing methods that required NoData values included "nodata" and "casting" options. These would assign a NoData value when the raster's NoData was missing. This functionality has been replaced by the "ensure_nodata" method, so these options have been removed:

  • Raster.buffer
  • Raster.clip
  • Raster.reproject

Stream segment connectivity

Added a number of methods to help determine segment connectivity in local drainage networks. Note that these methods/concepts will be described in detail in the forthcoming documentation MR. As such, I don't think the docstrings need to describe what a child segment is, what an ancestor segment is, etc.

  • Segments.child
  • Segments.parents
  • Segments.ancestors
  • Segments.descendents
  • Segments.family
  • Segments.isnested

Simplified segment outlets

Formerly users could query segment outlets using a plural command (all outlets in network), or a singular command (queried a specific segment). Example: segments.outlet/segments.outlets. This is redundant, so I've removed the singular commands and added an "ids" option to the plural command allowing the user to query specific segments.

  • Segments.outlet/outlets
  • Segments.terminus/termini

Flow continuity

Formerly, filtering a network implemented a flow continuity algorithm before filtering. But there was no way to see what would be filtered in advance. I've moved the flow continuity algorithm into the Segments.continuous function, and removed relevant options from Segments.keep and Segments.remove

  • Segments.continuous: Provides the flow continuity algorithm
  • Segments.remove: Removed flow continuity options
  • Segments.keep: Removed flow continuity options

Misc

  • Raster.repr: Provides a printable string summary of a raster
  • Raster.set_range: Now includes an "exclusive" option to include/exclude bounds in the valid range
  • Raster.utm_zone: Returns the CRS for the UTM zone holding the raster's center point
  • Segments.terminal_ids: Reports the IDs of terminal outlet segments
Edited by King, Jonathan M

Merge request reports