digger.make.new_water

make.new_water is used to modify the topography surface, b to add new regions with water.

Module Contents

Functions

new_water

Modify topobathymetry to create new water.

API

digger.make.new_water.new_water(topo_path: str, new_water_path: str, water_depth: float = 100.0, side_slope_angle: float = 30.0, sea_level: float = 0.0, min_island_size: float = 75000, b_prefix: str = 'b_new_water', west: float | None = None, south: float | None = None, east: float | None = None, north: float | None = None, write_tif: bool = True, write_tt3: bool = False, fig_path: str = 'new_water.png') → None

Modify topobathymetry to create new water.

This function modifies provide topobathymetry to add new areas of water by lowering the topographic elevation to a user-specified depth below sea level in a specified region. This function may be useful in context such as (1) areas with recent deglaciation such that the most recent topographic survey reports ice at locations where open water is now present and (2) lakes with incomplete bathymetric observations.

This function requires a user to provide an initial topographic surface in topo_path and the extent of new water in new_water_path. Within the extent of new_water_path this function will modify the topographic surface to be up to as deep as the value -1*water_depth. In most cases, a user will not want the transition from the newly created shoreline to abruptly change to the value -1*water_depth. To address this issue, this function will use planar slopes that descend from the shoreline elevation (sea_level) to the new water depth at a constant slope of side_slope_angle.

The modified topography is written out to a file.

Warning

In order to use make.new_water, the user must have some information about the water_depth in the area for which new water is being created. Additionaly, some information must be available to constrain the side_slope_angle. Should a user not have access to information that constrains these values, the results of make.new_water may not be of great value.

Furthermore, make.new_water only generates flat-bottomed bathymetry with planar side slopes. It is not suitable for adjusting topobathymetry in areas with complex submarine landforms.

Inputs:

topo_pathstr

Path to rasterio-readable file containing the topography input file. Output is written at the resolution of this file. Expected in projected coordinates (e.g., meters or feet, not degrees).

new_water_pathstr

Path to fiona-readable file with one or more polygon of the extent of new water. Required.

water_depthfloat

Depth of water within the new water area.

side_slope_anglefloat

Angle in degrees that the nearshore zone should slope away from the shoreline and down to the maximum depth of -1*water_depth.

sea_levelfloat

Sea level.

min_island_sizefloat

In extracting the shoreline, there may be interior rings within the extent of the ocean. make.new_water() will only keep islands with an area that exceeds min_island_size.

b_prefixstr

Prefix of the path to write any output of b (failure surface elevation, or eta-h)).

westfloat

The extent within topo_path to consider for this analysis. Along with west, east, and north, this parameter may reduce the size of the terrain consider, speeding computation time and reducing file size.

southfloat

The extent within topo_path to consider for this analysis.

eastfloat

The extent within topo_path to consider for this analysis.

northfloat

The extent within topo_path to consider for this analysis.

write_tt3bool

Whether to write out topotype 3 files b. If written, the b_prefix has ‘.tt3’ added to the end.

write_tifbool

Whether to write out geotif files of b. If written, the b_prefix has ‘.tif’ added to the end.

fig_pathstr

The base filepath for figures generated. The file extension will be used by matplotlib to determine the type of file (png, pdf, etc).

Outputs:

None