digger.make.scoops

make.scoops will generate D-Claw input files for b, h, eta, and m0 over the extent of a provided geotif. This routine is much more complex than digger.make.slabs() because it generates initial, potentially mobile, material thickness with variable depths based on a series of either (a) logarithmic spirals or (b) biplanar lines.

This portion of the user guide will describe the background for using a logarithmic spiral and the expected inputs to this function. Biplanar lines are provided as a second option.

Logarithmic spirals are a common choice for a curved failure surface in geotechnical engineering (e.g., Chen, 1975; Das, 2020). In polar coordinates (\(r\), \(\theta\)), a logarithmic spiral is defined as

\[r =r_0 \exp ( \theta \tan \psi)\]

where \(r_0\) and \(\psi\) are positive constants.

make.scoops expects that the extent of potentially mobile material will be defined in a provided shapefile. This shapefile will have one or more rows representing each potentially mobile landslide with a polygon of the landslide extent. For each row, the downslope direction is determined either by user input or by fitting a plane to the landslide extent and the topography. A series of transects is the drawn through the polygon, parallel to the downslope direction. Along each transect, a logarithmic spiral or biplanar line is fit. Finally, linear interpolation between the transects provides a spatially continuous value for landslide depth.

Detailed options for how the logarithmic spirals are fit can be found in the docstring of digger.utils.logspiral()

The approach taken here was described by George and others (2017) and also - implemented by Barnhart and others (2021). Figure 4 in Barnhart and others (2021) may be useful for visualizing the method provided by make.scoops.

Fig. 20 Reproduction of Figure 4. from Barnhart et al. (2021). Their figure caption is as follows: Landslide depth to failure surface for A, the smaller landslide volume and B, the larger landslide volume. The failure surface was constructed by fitting logarithmic spirals to a series of transects parallel to the downslope direction in the landslide. Black outlines in A and B demarcate the extent of Landslide A, Landslide B, and the Kite, each an independent landslide. Example transect locations are shown in C as dashed lines, here spaced 400 meters apart. The yellow polygon in C represents the main body of Landslide A, and the solid black line goes through the centroid (white dot) at an orientation perpendicular to the downslope direction. The transect shown in D is from the thick dashed line in A–C. It extends from the headscarp location (red dot) to the toescarp location (green dot). The logarithmic-spiral fitting can support relatively larger or smaller landslide depths by modifying the headscarp (\(\alpha\)) and toescarp (\(\beta\)) angles to create either a shallower failure depth (smaller landslide) or deeper failure depth (larger landslide) as shown by the purple and brown lines in D. \(\Phi\) is the average slope angle. The base map in A and B reflects a hillshade (no vertical exaggeration) based on the bathymetric and topographic data in 2020 (respectively, National Oceanic and Atmospheric Administration [NOAA], 2020; Daanen and others, 2021). Where recent data are not available (upper left-hand corner of A and B) the 50-meter dataset is used (NOAA, 2009). Easting and northing coordinates are in North American Datum of 1983 (NAD 83) Universal Transverse Mercator (UTM) Zone 6 N (European Petroleum Survey Group [EPSG] code 26906). Hillshade vertical exaggeration (VE) equal to 1.

References

Barnhart, K.R., Jones, R.P., George, D.L., Coe, J.A., and Staley, D.M., 2021, Preliminary assessment of the wave generating potential from landslides at Barry Arm, Prince William Sound, Alaska: U.S. Geological Survey Open-File Report 2021–1071, 28 p., https://doi.org/10.3133/ofr20211071.

Chen, W.F., 1975, Limit analysis and soil plasticity, v. 7 of Developments in Geotechnical Engineering: Amsterdam, Elsevier, 638 p., https://doi.org/10.1016/b978-0-444-41249-2.x5001-x.

Daanen, R.P., Wolken, G.J., Wikstrom Jones, K., and Herbst, A.M., 2021, High resolution lidar-derived elevation data for Barry Arm landslide, southcentral Alaska, June 26, 2020: Alaska Division of Geological & Geophysical Surveys Raw Data File 2021–3, 9 p., https://doi.org/10.14509/30593.

Das, B., 2020, Principles of Geotechnical Engineering 10th ed.: Stamford, Conn, Cengage Learning, 880 p., https://www.cengage.com/c/principles-of-geotechnical-engineering-10e-das/9780357420478/.

George, D.L., Iverson, R.M., and Cannon, C.M., 2017, New methodology for computing tsunami generation by subaerial landslides—Application to the 2015 Tyndall Glacier landslide, Alaska: Geophysical Research Letters, v. 44, no. 14, p. 7276–7284, https://doi.org/10.1002/2017GL074341.

National Oceanic and Atmospheric Administration [NOAA], 2020, Report for H13396: National Oceanic and Atmospheric Administration [NOAA] web page, https://www.ngdc.noaa.gov/nos/H12001-H14000/H13396.html.

National Oceanic and Atmospheric Administration [NOAA] National Geophysical Data Center, 2009, Prince William Sound, Alaska 8 arc-second MHHW coastal digital elevation model: National Oceanic and Atmospheric Administration [NOAA], National Centers for Environmental Information web page, https://data.noaa.gov/metaview/page?xml=NOAA/NESDIS/NGDC/MGG/DEM//iso/xml/638.xml&view=getDataView&header=none.

Module Contents

Functions

scoops

Calculate landslide failure slip surface using a series of logspiral transects.

API

digger.make.scoops.scoops(source_path: str, source_mask_path: str, topo_path: str, q1_prefix: str = 'q1', q4_prefix: str = 'q4', b_prefix: str = 'b', eta_prefix: str = 'eta', slip_angle: float | str | list | None = None, vertex_only: bool = False, step: float = 100.0, shift: float = 0.0, npoints: int = 100, sequential_scoop: bool = False, q1_buffer: float = 50.0, alpha1: float | None = None, alpha2: float | None = None, c: float | None = None, fit_method: str = 'logspiral', limit_alpha1: bool = True, limit_alpha2: bool = True, error_alpha: float = 5.0, error_xy: float = 2.0, m0: float = 0.62, water_level: float = 0.0, eta_dry: float = -99999.0, fill_flat: bool = False, check_crs: bool = True, check_heights: bool = True, check_nodata: bool = True, check_slip_and_mask: bool = True, clip_extent: bool = True, clip_m: bool = False, plot: bool = True, fig_path: str = 'scoops.png', write_tt3: bool = False, write_tif: bool = False, write_csv: bool = False, write_shp: bool = False, csv_path: str = 'spiral_lines_summary.csv', shp_path: str = 'spiral_lines_summary.shp', verbose: bool = True) → Dict

Calculate landslide failure slip surface using a series of logspiral transects.

This function generates input files for D-Claw. It does not do a slope stability analysis, but it estimates a slip surface based on logarithmic spirals. See the User Guide for background and references associated with logarithmic spirals.

The major implementation options are listed here in this enumerated list.

1. The extent of the scoops vs the extent of final material

   Two shapefiles specify the extent of the landslide failure surface. The first, source_path specifies the extent of the region where logarithmic spirals will be calculated. From these depths a field of landslide depths is constructed. The output landslide failure zone is then generated by clipping that field of landslide depths by source_path_mask.

2. Estimating the slip orientation

   Multiple options exist for specifying the orientation of the slip vector, the orientation parallel to which the logarithmic spirals will be drawn. The same value can be used for every extent polygon or a different value can be used for each. See the documentation for the parameters slip_angle and vertex_only.

3. Overlapping polygons in source_path.

   Should polygons overlap in source_path, you will probably want to specify the order in which logarithmic spirals are scooped out of the topography. To do this, indicate the scooping order in a shapefile attributed called ‘Sequence’. If you do not specify an order through ‘Sequence’ the scoops will be made in the shapefile row order.

   Additionally, set sequential_scoop to True to make the scoops sequential. In this case, the topography after the first scoop will be used to generate the z coordinate of the second scoop, and so on.

4. The final surface altitude, eta.

   In most cases, you will want to use the observed topography to generate the landslide thickness field. However, if you want to fill the extent of the landslide area with a flat plane, set the fill_flat to True.

Inputs:

source_pathstr

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

source_mask_pathstr

Path to fiona-readable file with one or more polygon of the landslide mask extent. If not provided, source_path is used.

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).

q1_prefixstr

Prefix of the path to write any output of q1 (thickness, h). The extent of q1 output is the extent of the polygon(s) provided in source_path, buffered with the value 1.5*q1_buffer.

eta_prefixstr

Prefix of the path to write any output of eta (surface altitude). The extent of eta output is the extent of the polygon(s) provided in source_path, buffered with the value 1.5*q1_buffer. Outside of the slide area, eta is set to the value eta_dry to ensure that D-Claw uses the value of b.

b_prefixstr

Prefix of the path to write any output of b (failure surface elevation, or eta-h)). The extent of b output is the extent of the polygon(s) provided in source_path, buffered with the value 1.5*q1_buffer.

q4_prefixstr

Prefix of the path to write any output of q4 (solid volume fraction, m) . The extent of q4 output is the extent of the file provided in topo_path.

slip_angleNone, float, list, or str

Orientation of the logarithmic spirals draw for each landslide polygon. Provided as a compass orientation (degrees clockwise from North). Multiple options for specification: (1) if None each polygon in source_path will have a best fit plane fit to its verticies (if vertex_only==True or all elements of topo_path which intersect the polygon exterior; (2) if a float, all polygons will use the same value, (3) if a list, the list must be the same size as the number of polygons in source_path; (4) if a string, that string must specify an attribute name in source_path, which will be used.

vertex_onlybool

If slip_angle is None, then a best-fit plane will be calculated to estimate the orientation of the log spirals. If vertex_only==True, only the verticies of the polygon will be used. If vertex_only==False, then the x,y,z coordinates of all grid cells in topo_path which intersect the polygon will be used.

stepfloat

Distance between logarithmic spiral transects, provided in the map units of topo_path.

shiftfloat

Shift moves the start of logspiral lines to a different horizontal location along the strike line.

npointsint

Number of points used to discretize each logarithmic spiral transect.

fit_methodstr

Either ‘logspiral’ or ‘biplanar’. If set to ‘logspiral’ then a logspiral is fit. If set to ‘biplanar’, then both alpha values must be provided and a biplanar line is calculated.

sequential_scoopbool

If the polygons provided in source_path do not overlap, this will not have an effect. If they do overlap the overlapping polygons can be simultaneously scooped out of the topography (if this variable is False) or sequentially scooped out of the topograph(if this variable is True).

q1_bufferfloat

Buffer distance around the polygons provided in source_path use for setting the extent of output (if clip_extent==True)

clip_extentbool

Whether to clip the extent of some output. If the input topography is large, this should be true otherwise the interpolation will take a very long time.

clip_mbool

Whether to clip the extent of the q4 output.

alpha1float

Headscarp angle relative to the horizon (degrees measured relative to east, in which positive is counterclockwise). alpha1 must be negative and between the average slope angle along the logarithmic spiral transect and -90. Exactly two of alpha1, alpha2, and c must be provided.

alpha2float

Landslide toe angle relative to the horizon (degrees measured relative to east, in which positive is counterclockwise). alpha2 must be negative for the slip surface to monotonically decrease. It must be between zero and the average slope angle. Exactly two of alpha1, alpha2, and c must be provided.

limit_alpha1: bool

True if alpha1 should be limited to between -90 (vertical headscarp angle) and 2 degrees steeper than the topography?

limit_alpha2: bool

True if alpha2 should be limited so that the toe angle is never less than zero. This enforces monotonic decrease from headscarp to toe.

cfloat

Parameter used to calculate a value for alpha1 or alpha2 if the other is not provided based on the equation: c = [(S-alpha1)/(-S+alpha2)], where S is the average slope along a given transect. Given the position and elevation of the headscarp and the toeslope (both defined by the extent of the landslide polygon and the topography), a perfectly fitting logarithmic spiral requires that c==1. A well fitting logarithmic spiral can be forced through through the headscarp and toeslope points with values of c as low as 0.5. In general, the higher the value of c, the deeper the logarithmic spiral and the larger the landslide volume. Exactly two of alpha1, alpha2, and c must be provided.

error_alphafloat

Error parameter passed on to the function digger.utils.logspiral.spiral. See documentation of that function for explaination.

error_xyfloat

Error parameter passed on to the function digger.utils.logspiral.spiral. See documentation of that function for explaination.

m0float

Solid volume fraction for landslide material. Must be between 0 and 1.

water_levelfloat

Elevation of water level in the same units and vertical reference frame as topo_path.

fill_flatbool

Fill the scooped area surface (eta) based on best fit plane.

check_crsbool

Check compatibility between the coordinate reference system (CRS) of topo_path, source_path, and source_path_mask.

check_nodatabool

Whether to check for no data in the topo raster. If True and nodata are present, a value error is raised.

eta_dryNone or float

Value to use for the eta output file where no material is present. Default is -9999 because this ensures that there is no thin material on the edge when D-Claw initializes.

check_heightsbool

Whether to ensure that every single logspiral line descends. Default is True. Unless you are confident you understand what this does, it should be True. The primary use case for it being False is having a slip surface in irregular topography and having a few of the edge slip surfaces not descend.

check_slip_and_maskbool

Whether to ensure that 100% of the masked area is covered by the source area. Unless you are confident you understand what this does, it should be True. The primary use case for it being False is having a source and mask area that are almost identical, but that do not quite conform to the test implemented here using the painters algorithm.

plotbool

Whether to make plots depicting some aspects of the output. Often useful for honing in on the specific values of alpha1, alpha2, and c used for an application.

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).

write_tt3bool

Whether to write out topotype 3 files of q1, eta, q4, and b. If written, the *_prefix for each output has ‘.tt3’ added to the end.

write_tifbool

Whether to write out geotif files of q1, eta, q4, and b. If written, the *_prefix for each output has ‘.tif’ added to the end.

write_csvbool

Whether a CSV file containing information about the logarithmic spirals be generated. If True the CSV will contain a row for every point generated along each logspiral. For each feature in source_path multiple logspiral lines are generated. The CSV will have the following columns:

Table 9 CSV column descriptions

Column name	Description
feat_id	The feature ID of the geometry source_path
line_id	The logspiral line number.
x_length	The x coordinate of the point, units of length of topo_path.
y_length	The y coordinates of the point.
dist_length	The distance from the headscarp along the line.
b_length	The elevation of the failure plane surface.
h_length	The thickness of material.
topo_in	The elevation of the surface.
mask	Whether this point was masked out by source_path_mask.

write_shpbool

Whether a shapefile containing the logarithmic spirals is generated. Each logarithmic spiral will be represented as a row in the shapefile. Each row is a LineString geometry with two attributes:

Table 10 Shapefile column descriptions

Column name	Description
feat_id	The feature id of the polygon containing this logarithmic spiral
line_id	The unique identifier of this logarithmic spiral within the set of logarithmic spirals generated for the associated polygon.

csv_pathstr

The filepath to write the csv file.

shp_pathstr

The filepath to write the shapefile.

verbosebool

Whether to print information about logspiral fits.

Outputs:

infodict

Dictionary of summary information. Includes the following key-value pairs:

Table 11 Output dictionary contents.

Key	Value
total_volume	The total failure volume in cubic units of topo_path.
maximum_thickness	The maximum thickness in units of topo_path.
mean_thickness	The mean thickness in units of topo_path.