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', mthresh: float = 0.3, mass_threshold: float = 0.95, rho_s: float = 2700, rho_f: float = 1000, 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.

For this analysis, the domain is broken up into the region containing landslide material (solid volume fraction greater than mthresh) and the region containing not-landslide material.

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.

mthreshfloat

The threshold value of m that demarcates landslide material from not-landslide material.

methodstr

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

rho_sfloat

Density of the solid fraction in mks units.

rho_ffloat

Density of the fluid in mks units.

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

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

digger.analyze.ellipse.estimate_ellipse_COV(x, y, rhoh)

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

RHOHndarray

2-d array of density times depth. All elements with RHOH>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

digger.analyze.ellipse.estimate_ellipse_CSI(x, y, RHOH, 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

RHOHndarray

2-d array of density times depth. All elements with RHOH>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