gfail.stats

gfail.stats.computeStats(grid2D, stdgrid2D=None, shakefile=None, shakethreshtype='pga', shakethresh=0.0, probthresh=None, pop_file=None, stdtype='full', maxP=1.0, proj='moll')

Compute summary stats of a ground failure model output.

Parameters

• grid2D – grid2D object of model output.

• stdgrid2D – grid2D object of model standard deviations (optional)

• shakefile – Optional, path to shakemap file to use for ground motion threshold.

• shakethreshtype – Optional, Type of ground motion to use for shakethresh, ‘pga’, ‘pgv’, or ‘mmi’.

• shakethresh – Optional, Float in %g for pga, cm/s for pgv, float for mmi. Used for Hagg and Exposure computation

• probthresh – Optional, None or float, exclude any cells with probabilities less than or equal to this value

• pop_file (str) – File path to population file to use to compute exposure stats

• stdtype (str) – assumption of spatial correlation used to compute the stdev of the statistics, ‘max’, ‘min’ or ‘mean’ of max and min, or full (default) estimates std considering covariance

• maxP (float) – maximum possible value of P (1 default, but coverage models have smaller values, 0.487 and 0.256 for LQ and LS)

• proj (str) – projection string to use when computing stats

Returns

Dictionary with all or some of the following keys

(depending on input options): - Max - Median - Std - hagg_# where # is the shaking threshold input - hagg_std_# standard deviation of hagg_# - hlim_# maximum possible value of hagg (for given Pmax value) - p_hagg_# beta function shapefile p for hagg - q_hagg_# beta function shapefile q for hagg - exp_pop_# where # is the shaking threshold (if pop_file specified) - exp_std_# (optional) standard deviation of exp_pop_# - elim_# maximum possible value of E (for given Pmax value) - p_exp_# beta function shapefile p for exp_pop - q_exp_# beta function shapefile q for exp_pop

Return type

dict

gfail.stats.computeHagg(grid2D, proj='moll', probthresh=0.0, shakefile=None, shakethreshtype='pga', shakethresh=0.0, stdgrid2D=None, stdtype='full', maxP=1.0, sill1=None, range1=None)

Computes the Aggregate Hazard (Hagg) which is equal to the probability * area of grid cell For models that compute areal coverage, this is equivalant to the total predicted area affected in km2.

Parameters

• grid2D – grid2D object of model output.

• proj – projection to use to obtain equal area, ‘moll’ mollweide, or ‘laea’ lambert equal area.

• probthresh – Probability threshold, any values less than this will not be included in aggregate hazard estimation.

• shakefile – Optional, path to shakemap file to use for ground motion threshold.

• shakethreshtype – Optional, Type of ground motion to use for shakethresh, ‘pga’, ‘pgv’, or ‘mmi’.

• shakethresh – Optional, Float or list of shaking thresholds in %g for pga, cm/s for pgv, float for mmi.

• stdgrid2D – grid2D object of model standard deviations (optional)

• stdtype (str) – assumption of spatial correlation used to compute the stdev of the statistics, ‘max’, ‘min’, ‘mean’ of max and min, or ‘full’ (default) which estimates the range of correlation and accounts for covariance. Will return ‘mean’ if ridge and sill cannot be estimated.

• maxP (float) – the maximum possible probability of the model

• sill1 (float, None) – If known, the sill of the variogram of grid2D, will be estimated if None and stdtype=’full’

• range1 (float, None) – If known, the range of the variogram of grid2D, will be estimated if None and stdtype=’full’

Returns

Dictionary with keys:

hagg_#g where # is the shakethresh std_# if stdgrid2D is supplied (stdev of exp_pop) hlim_#, the maximum exposure value possible with the applied thresholds and given maxP value cell_area_km2 grid cell area p_hagg_# beta distribution shape factor p (sometimes called alpha) q_hagg_# beta distribution shape factor q (sometimes called beta)

Return type

dict

gfail.stats.computePexp(grid, pop_file, shakefile=None, shakethreshtype='pga', shakethresh=0.0, probthresh=0.0, stdgrid2D=None, stdtype='full', maxP=1.0, sill1=None, range1=None)

Get exposure-based statistics.

Parameters

• grid – Model grid.

• pop_file (str) – Path to the landscan population grid.

• shakefile (str) – Optional, path to shakemap file to use for ground motion threshold.

• shakethreshtype (str) – Optional, Type of ground motion to use for shakethresh, ‘pga’, ‘pgv’, or ‘mmi’.

• shakethresh – Float or list of shaking thresholds in %g for pga, cm/s for pgv, float for mmi.

• probthresh – Float, exclude any cells with probabilities less than or equal to this value

• stdgrid2D – grid2D object of model standard deviations (optional)

• stdtype (str) – assumption of spatial correlation used to compute the stdev of the statistics, ‘max’, ‘min’, ‘mean’ of max and min, or ‘full’ (default) which estimates the range of correlation and accounts for covariance. Will return ‘mean’ if ridge and sill cannot be estimated.

• maxP (float) – the maximum possible probability of the model

• sill1 (float, None) – If known, the sill of the variogram of grid2D, will be estimated if None and stdtype=’full’

• range1 (float, None) – If known, the range of the variogram of grid2D, will be estimated if None and stdtype=’full’

Returns

Dictionary with keys named exp_pop_# where # is the shakethresh

and exp_std_# if stdgrid2D is supplied (stdev of exp_pop) and elim_#, the maximum exposure value possible with the applied thresholds and given maxP value p_exp_# beta distribution shape factor p (sometimes called alpha) q_exp_# beta distribution shape factor q (sometimes called beta)

Return type

dict

gfail.stats.semivario(model, threshold=0.0, maxlag=100, npts=1000, ndists=200, nvbins=20, makeplots=False, shakegrid=None, shakethresh=0.0, minpts=50)

Quickly estimate semivariogram with by selecting seed points and then computing semivariogram between each of those points and ndists random locations around it that are within maxlag of the seed point. Will result in npts x ndists total distance pairs. Uses spherical model.

Parameters

• model (array) – array of raster to estimate semivariogram for

• threshold –

• maxlag (int) – in pixels

• npts (int) – number of seed points to sample from

• ndists (int) – number of points to sample at random distances from each seed point

• nvbins (int) – number of semivariogram bins

• minpts (float) – minimum number of samples above threshold required

• makeplots (bool) – create semivariogram plots

• shakegrid (array) – array of shaking that is the same size as model

• shakethresh (float) – Shaking threshold for seed point selection

Returns

range, sill

gfail.stats.spherical(lag, range1, sill)

Spherical variogram model assuming nugget = 0

Parameters

• lag – float or array of lags as # of pixels/cells

• range1 (float) – range of spherical model

• sill (float) – sill of spherical model

Returns

semivariance as float or array, depending on type(lag)

gfail.stats.svar(stds, range1, sill1, scale=1.0)

Estimate variance of aggregate statistic using correlation from semivariogram and std values for each pair of cells that are within range of each other, add up quickly by creating kernal of the correlations and convolving with the image, then multiply by std to equal sum of std1*std2*corr*scale1*scale2 over each valid cell

Parameters

• stds (array) – grid of standard deviation of model

• range1 (float) – range of empirical variogram used to estimate correlation model

• sill1 (float) – sill of empirical variogram used to estimate correlation model

• scale – float or array same size as std, factor to multiply by (area or population) and include in convolution

Returns

variance of aggregate statistic

gfail.stats.get_rangebeta(p, q, prob=0.95, minlim=0, maxlim=1)

Get endpoints of the range of the specified beta function that contain prob percent of the distribution

Parameters

• p (float) – p shape factor of beta distribution (a in scipy)

• q (float) – q shape factor of beta distribution (b in scipy)

• prob (float) – central probability of distribution to return the range of. Value from 0 to 1

• minlim (float) – minimum possible value of distribution

• maxlim (float) – maximum possible value of distribution

Returns: tuple (valmin, valmax) where:

• valmin (float): lower edge of range containing prob

• valmax (float): upper edge of range containing prob

gfail.stats.get_pdfbeta(p, q, binedges, minlim=0, maxlim=1, npts=1000, openends=True)

Return discretized pdf for plotting curve and report probabilities of each bin

Parameters

• p (float) – p shape factor of beta distribution (a in scipy)

• q (float) – q shape factor of beta distribution (b in scipy)

• binedges (list) – list of bin edges

• minlim (float) – minimum possible value of distribution

• maxlim (float) – maximum possible value of distribution

• npts (int) – number of points to return in xvals

• openends (bool) – assumes lower and upper bins don’t have hard edges

Returns: tuple of (xvals, yvals, probs) where:

• xvals: list of log-distributed values

• yvals: corresponding list of

• probs (list): list of len(binedges)-1 that gives probability of

  value falling in the corresponding bin