digger.analyze.ellipse

Module Contents

Functions

ellipse	Analyze a series of fixed grid output to generate landslide ellipse information.
get_center_of_mass
estimate_ellipse_COV	Estimate ellipse from extent of landslide material
estimate_ellipse_CSI	Estimate ellipse from extent of landslide material

API

digger.analyze.ellipse.ellipse(wdir: str = '.', output_type: str = 'fgout', gdir: str = '_output', csvout: str = 'ellipse.csv', shpout: str = 'ellipse.shp', method: str = 'COV', mass_threshold: float = 0.95, m0: float = 0.6, sea_level: float = 0, plot: float = True, epsg: int = None, njobs: int = 4, stride: int = 5) → dict

Analyze a series of fixed grid output to generate landslide ellipse information.

Two methods are provided. CSI guarantees that mass_threshold percent of the mass will be covered, but is much slower. COV does not guarantee mass coverage, but is much faster.

If method=='CSI', the following approach is used:

The location of a best-fit ellipse is determined by finding the ellipse that covers mass_threshold percent of the landslide material mass and maximizes the critical success index (\(CSI\)), defined as:

\[CSI = \frac{TP}{TP + FP + FN}\]

where \(TP\) is the area covered by the ellipse that is also landslide material, \(FN\) is the area covered by landslide material that is not in the ellipse, and \(FP\) is the area covered by the ellipse that is not landslide material.

Alternatively, if method=='COV', the best-fit ellipse will be based on the covariance of the landslide x and y coordinates, weighted by mass.

This function will generate two files:

• The file specified by csvout contains time-series information about total the best-fit ellipse, center of mass locations, each considered output timestep*.

• The file specified by shpout is a shapefile of the ellipses at each considered output timestep.

Diagnostic plots are optionally created.

Inputs:

wdirstr

Working directory within which D-Claw was run. This directory is expected to contain the standard .data files associated with a clawpack run.

output_typestr

Type of gridded output. Options are "fgout", indicating clawpack fgout-style output that will be read using the xarray FGOutBackend. Alternatively, "netcdf4" indicates netcdf files.

If output_type=="fgout", then an installation of the clawpack python modules is necessary as they provide the xarray FGOutBackend. To meet this requirement, install D-Claw as described in the documentation.

netcdfs are expected to have the variables for depth (h) and depth times solid fraction (hm).

gdirstr

The name of the directory within wdir that contains the gridded output files.

csvoutstr

The path, relative to the current directory to place time-variable results. See below for a description of all columns within csvout.

methodstr

‘COV’ or ‘CSI’ see above for explanation.

m0float

Reference solid fraction to convert hm to depth.

plotbool

Whether to generate diagnostic plots (not publication quality).

epsgint

The EPSG code of the simulation.

shpoutstr

The path to place a shapefile of ellipses.

epsgint

The EPSG code of to use for the shapefile.

njobsint

The number of simulatneous ellipses to process at once.

strideint

The ellipse calculations are not especially efficient and it may not be necessary to calculate them at every output timestep. They may be calculated less frequently by specifying a stride to sample the full output time series with.

Outputs:

None

This function will generate a file called ‘ellipse.csv’. It will have one row per fixed grid output timestep and the following columns:

Table 2 Columns in energetics.csv.

Column name	Column description	Units
time	Simulation time	seconds
x	Center of mass x-coordinate	meters
y	Center of mass y-coordinate	meters
a	Major axis length	meters
b	Minor axis length	meters
e	Eccentricity	unitless
theta	Angle from the major horizontal axis and the major axis of the ellipse	degrees
CSI	The critical success index assessing the fit between the ellipse and the area affected by landslide material	unitless
mass_fraction	The mass fraction covered by the ellipse	unitless
area	The area of the ellipse	square meters
h_max	meters	Maximum landslide thickness
h_mean	meters	Mean landslide thickness
landslide_volume	cubic meters	Landslide volume
displaced_volume	cubic meters	Displaced water volume

digger.analyze.ellipse.get_center_of_mass(mass_grid, x, y)

digger.analyze.ellipse.estimate_ellipse_COV(x, y, h, B, sea_level)

Estimate ellipse from extent of landslide material

The ellipse is estimated using the covariance of x and y, weighted by the mass.

Inputs:

xndarray

1-d array of x coordinates

yndarray

1-d array of y-coordinates

hndarray

2-d array of depths. Assumption is that all depths have the same density. All elements with h>0 are considered as landslide material

Outputs:

xfloat

Center of mass x-coordinate

yfloat

Center of mass y-coordinate

afloat

Major axis length

bfloat

Minor axis length

efloat

Eccentricity

thetafloat

Angle from the major horizontal axis and the major axis of the ellipse.

CSIfloat

The critical success index assessing the fit between the ellipse and the area affected by landslide material.

mass_fractionfloat

The mass fraction covered by the ellipse

h_maxfloat

Maximum thickness

h_meanfloat

Mean thickness

ls_volume: float

Landslide volume

disp_volume: float

Displaced water volume

digger.analyze.ellipse.estimate_ellipse_CSI(x, y, h, B, sea_level, mass_threshold=0.95)

Estimate ellipse from extent of landslide material

The goodness of fit between the ellipse and the landslide material is assessed useing the critical success index (\(CSI\)), defined as:

\[CSI = \frac{TP}{TP + FP + FN}\]

where \(TP\) is the area covered by the ellipse that is also landslide material, \(FN\) is the area covered by landslide material that is not in the ellipse, and \(FP\) is the area covered by the ellipse that is not landslide material.

Inputs:

xndarray

1-d array of x coordinates

yndarray

1-d array of y-coordinates

hndarray

2-d array of depths. Assumption is that all depths have the same density. All elements with h>0 are considered as landslide material

mass_thresholdfloat

The fraction of landslide mass that must be within the ellipse.

Outputs:

xfloat

Center of mass x-coordinate

yfloat

Center of mass y-coordinate

afloat

Major axis length

bfloat

Minor axis length

efloat

Eccentricity

thetafloat

Angle from the major horizontal axis and the major axis of the ellipse.

CSIfloat

The critical success index assessing the fit between the ellipse and the area affected by landslide material.

mass_fractionfloat

The mass fraction covered by the ellipse

h_maxfloat

Maximum thickness

h_meanfloat

Mean thickness

ls_volume: float

Landslide volume

disp_volume: float

Displaced water volume