gfail.utilities

gfail.utilities.is_grid_point_source(grid)[source]

Was the shakemap grid constructed with a point source?

This makes use of the ‘urat’ layer, which is the ratio of the predicted ground motion standard deviation to the GMPE standard deviation. The only reason this could ever be greater than 1.0 is if the uncertainty of the prediction is inflated due to the point source approxmiation; further, if a point source was used, there will always be some locations with ‘urat’ > 1.0.

Parameters

grid (ShakeGrid) – A ShakeGrid object from MapIO.

Returns

True if point rupture.

Return type

bool

gfail.utilities.get_event_comcat(shakefile, timewindow=60, degwindow=0.3, magwindow=0.2)[source]

Find an event in comcat, searching first by event id and if that fails searching by magnitude, time, and location.

Parameters

  • shakefile (str) – path to shakemap .xml file of event to find

  • timewindow (float) – width of time window to search around time defined in shakefile (in seconds)

  • degwindow (float) – width of area to search around location specified in shakefile (in degrees).

  • magwindow (float) – width of magnitude window to search around the magnitude specified in shakefile.

Returns

None if event not found, else tuple (info, detail, shakemap) where,

  • info: json formatted dictionary of info.json for the event

  • detail: event detail from comcat

  • shakemap: shakemap of event found (from comcat)

gfail.utilities.parseConfigLayers(maplayers, config, keys=None)[source]

Parse things that need to coodinate with each layer (like lims, logscale, colormaps etc.) from config file, in right order, where the order is from maplayers.

Parameters

  • maplayers (dict) – Dictionary containing model output.

  • config (ConfigObj) – Config object describing options for specific model.

  • keys (list) – List of keys of maplayers to process, e.g. ['model'].

Returns

(plotorder, logscale, lims, colormaps, maskthreshes) where:

  • plotorder: maplayers keys in order of plotting.

  • logscale: list of logscale options from config corresponding to keys in plotorder (same order).

  • lims: list of colorbar limits from config corresponding to keys in plotorder (same order).

  • colormaps: list of colormaps from config corresponding to keys in plotorder (same order),

  • maskthreshes: list of mask thresholds from config corresponding to keys in plotorder (same order).

Return type

tuple

gfail.utilities.text_to_json(input1)[source]

Simplification of text_to_json from shakelib.rupture.factory

Parameters

input1 (str) – url or filepath to text file

Returns

json formatted stream of input1

gfail.utilities.write_floats(filename, grid2d)[source]

Create a binary (with acc. header file) version of a Grid2D object.

Parameters

  • filename (str) – String filename to write (i.e., ‘probability.flt’)

  • grid2d (Grid2D) – MapIO Grid2D object.

Returns

Given a filename input of “probability.flt”, this function will create that file, plus a text file called “probability.hdr”.

gfail.utilities.savelayers(grids, filename)[source]

Save ground failure layers object as a MultiHazard HDF file, preserving metadata structures. All layers must have same geodictionary.

Parameters

  • grids – Ground failure layers object.

  • filename (str) – Path to where you want to save this file.

Returns

.hdf5 file containing ground failure layers

gfail.utilities.loadlayers(filename)[source]

Load a MultiHazard HDF file back in as a ground failure layers object in active memory (must have been saved for this purpose). :param filename: Path to layers file (hdf5 extension). :type filename: str

Returns

Ground failure layers object

gfail.utilities.get_alert(paramalertLS, paramalertLQ, parampopLS, parampopLQ, hazbinLS=[1.0, 10.0, 100.0], popbinLS=[100, 1000, 10000], hazbinLQ=[10.0, 100.0, 1000.0], popbinLQ=[1000, 10000, 100000])[source]

Get alert levels

Parameters

  • paramalertLS (float) – Hazard statistic of preferred landslide model

  • paramalertLQ (float) – Hazard statistic of preferred liquefaction model

  • parampopLS (float) – Exposure statistic of preferred landslide model

  • parampopLQ (float) – Exposure statistic of preferred liquefaction model

  • hazbinLS (list) – 3 element list of bin edges for landslide hazard alert between Green and Yellow, Yellow and Orange, and Orange and Red.

  • popbinLS (list) – same as above but for population exposure

  • hazbinLQ (list) – 3 element list of bin edges for liquefaction hazard alert between Green and Yellow, Yellow and Orange, and Orange and Red.

  • popbinLQ (list) – same as above but for population exposure

Returns

tuple: (hazLS, popLS, hazLQ, popLQ, LS, LQ) where:

  • hazLS: the landslide hazard alert level (str)

  • popLS: the landslide population alert level (str)

  • hazLQ: the liquefaction hazard alert level (str)

  • popLQ: the liquefaction population alert level (str)

  • LS: the overall landslide alert level (str)

  • LQ: the overall liquefaction alert level (str)

Return type

Returns

gfail.utilities.view_database(database, starttime=None, endtime=None, minmag=None, maxmag=None, eventids=None, realtime=False, currentonly=False, numevents=None, LShazmin=None, LShazmax=None, LSpopmin=None, LSpopmax=None, LQhazmin=None, LQhazmax=None, LQpopmin=None, LQpopmax=None, verbose=False, printcols=None, csvfile=None, printsummary=True, printsuccess=False, printfailed=False, printnotmet=False, maxcolwidth=100, alertreport='value', realtime_maxsec=259200.0)[source]

Prints out information from the ground failure database based on search criteria and other options. If nothing is defined except the database, it will print out a summary and details on the successful event runs only.

Parameters

  • database (str) – file path to event database (.db file)

  • starttime (str) – earliest earthquake time to include in the search, can be any string date recognizable by np.datetime

  • endtime (str) – latest earthquake time to include in the search, can be any string date recognizable by datetime

  • minmag (float) – minimum magnitude to include in search

  • maxmag (float) – maximum magnitude to include in search

  • eventids (list) – list of specific event ids to include (optional)

  • realtime (bool) – if True, will only include events that were run in near real time (defined by delay time less than realtime_maxsec)

  • currentonly (bool) – if True, will only include the most recent run of each event

  • numevents (int) – Include the numevents most recent events that meet search criteria

  • LShazmin – minimum landslide hazard alert color (‘green’, ‘yellow’, ‘orange’, ‘red’) or minimum hazard alert statistic value

  • LShazmax – same as above but for maximum landslide hazard alert value/color

  • LSpopmin – same as above but for minimum landslide population alert value/color

  • LSpopmax – same as above but for maximum landslide population alert value/color

  • LQhazmin – same as above but for minimum liquefaction hazard alert value/color

  • LQhazmax – same as above but for maximum liquefaction hazard alert value/color

  • LQpopmin – same as above but for minimum liquefaction population alert value/color

  • LQpopmax – same as above but for maximum liquefaction population alert value/color

  • verbose (bool) – if True, will print all columns (overridden if printcols is assigned)

  • printcols (list) – List of columns to print out (choose from id, eventcode, shakemap_version, note, version, lat, lon, depth, time, mag, location, starttime, endtime, eventdir, finitefault, HaggLS, ExpPopLS, HaggLQ, ExpPopLQ

  • csvfile – If defined, saves csvfile of table of all events found (includes all fields and failed/non-runs)

  • printsummary (bool) – if True (default), will print summary of events found to screen

  • printsuccess (bool) – if True (default), will print out database entries for successful event runs found

  • printfailed (bool) – if True (default False), will print out information about failed event runs

  • printnotmet (bool) – if True (default False), will print out information about event runs that didn’t meet criteria to run ground failure

  • maxcolwidth (int) – maximum column width for printouts of database entries.

  • alertreport (str) – ‘value’ if values of alert statistics should be printed, or ‘color’ if alert level colors should be printed

  • realtime_maxsec (float) – if realtime is True, this is the maximum delay between event time and processing end time in seconds to consider an event to be run in realtime

Returns

Prints summaries and database info to screen as requested, saves a csv file if requested. Also returns a tuple where (success, fail, notmet, stats, criteria) where

  • success: pandas dataframe of selected events that ran

    successfully

  • fail: pandas dataframe of selected events that failed to run

    due to an error

  • notmet: pandas dataframe of selected events that failed to run

    because they did not meet the criteria to run ground failure

  • stats: dictionary containing statistics summarizing selected

    events where * aLSg/y/o/r is the number of overall alerts of green/yellow

    orange or red for landslides. If LS is replaced with LQ, it is the same but for liquefaction.

    • hazLSg/y/o/r same as above but for hazard alert level totals

    • popLSg/y/o/r same as above but for population alert level

      totals

    • nsuccess is the number of events that ran successfully

    • nfail is the number of events that failed to run

    • nnotmet is the number of events that didn’t run because they

      did not meet criteria to run ground failure

    • nunique is the number of unique earthquake events run

    • nunique_success is the number of unique earthquake events

      that ran successfully

    • nrealtime is the number of events that ran in near-real-time

    • delay_median_s is the median delay time for near-real-time

      events (earthquake time until first GF run), also the same for mean, min, max, and standard deviation

  • criteria: dictionary containing info on what criteria were used

    for the search

gfail.utilities.alert_summary(database, starttime=None, endtime=None, minmag=None, maxmag=None, realtime=True, currentonly=True, filebasename=None, summarytypes='all')[source]

Print summary plot of alerts that have been issued for set of events met by defined criteria

Parameters

  • database (str) – file path to event database (.db file)

  • starttime (str) – earliest earthquake time to include in the search, can be any string date recognizable by np.datetime

  • endtime (str) – latest earthquake time to include in the search, can be any string date recognizable by datetime

  • minmag (float) – minimum magnitude to include in search

  • maxmag (float) – maximum magnitude to include in search

  • realtime (bool) – if True, will only include events that were run in near real time (defined by delay time less than realtime_maxsec)

  • currentonly (bool) – if True, will only include the most recent run of each event

  • filebasename (str) – If defined, will save a file with a modified version of this name depending on which alert is displayed, if no path is given it will save in current directory.

  • summarytypes (str) – if ‘all’, will create three figures, one for overall alerts, one for hazard alerts, and one for population alerts. If ‘overall’, ‘hazard’, or ‘population’ it will create just the one selected.

Returns

List of figure handles in order [‘overall’, ‘hazard’, ‘population’] Figure files of alert level summaries

gfail.utilities.plot_evolution(database, starttime=None, endtime=None, minmag=None, maxmag=None, eventids=None, filebasename=None, changeonly=True, percrange=None)[source]
Make a plot and print stats showing delay times and changes in alert

statistics over time

Parameters

  • database (str) – file path to event database (.db file)

  • starttime (str) – earliest earthquake time to include in the search, can be any string date recognizable by np.datetime

  • endtime (str) – latest earthquake time to include in the search, can be any string date recognizable by datetime

  • minmag (float) – minimum magnitude to include in search

  • maxmag (float) – maximum magnitude to include in search

  • eventids (list) – list of specific event ids to include (optional)

  • filebasename (str) – If defined, will save a file with a modified version of this name depending on which alert is displayed, if no path is given it will save in current directory.

  • changeonly (bool) – if True will only show events that changed alert level at least once in the time evolution plots (unless eventids are defined, then all will show)

  • percrange – percentile to use for error bars to show uncertainty as value <1 (e.g., 0.95). If None, errors will not be shown

Returns

Figures showing alert changes over time and delay and alert change

statistics

gfail.utilities.time_delays(database, starttime=None, endtime=None, minmag=None, maxmag=None, eventids=None, filebasename=None)[source]
Make a plot and print stats showing delay times and changes in alert

statistics over time

Parameters

  • database (str) – file path to event database (.db file)

  • starttime (str) – earliest earthquake time to include in the search, can be any string date recognizable by np.datetime

  • endtime (str) – latest earthquake time to include in the search, can be any string date recognizable by datetime

  • minmag (float) – minimum magnitude to include in search

  • maxmag (float) – maximum magnitude to include in search

  • eventids (list) – list of specific event ids to include (optional)

  • filebasename (str) – If defined, will save a file with a modified version of this name depending on which alert is displayed, if no path is given it will save in current directory.

Returns

Figure showing delay and alert change statistics

gfail.utilities.plot_uncertainty(database, eventid, currentonly=True, filebasename=None, bars=False, percrange=0.95)[source]
Make a plot and print stats showing delay times and changes in alert

statistics over time

Parameters

  • database (str) – file path to event database (.db file)

  • eventid (str) – event ids to plot

  • currentonly (bool) – if True, will only plot newest version, if False will plot all versions with different colors

  • filebasename (str) – If defined, will save a file with a modified version of this name depending on which alert is displayed, if no path is given it will save in current directory.

  • bars (bool) – if True, will use bars spanning percrange

  • percrange (float) – percentile to use for error bars to show uncertainty as value <1 (e.g., 0.95).

Returns

Figure showing uncertainty

gfail.utilities.alert_rectangles(ax, bins)[source]

Function used to color bin levels in background of axis

gfail.utilities.correct_config_filepaths(input_path, config)[source]

Takes an input filepath name and pre-pends it to all file locations within the config file. Individual locations are put into the config. Don’t have to put entire filepath location for each layer. Works by looping over config dictionary and subdictionary to fine locations named ‘file’.

Parameters

  • input_path (str) – Path that needs to be appended to the front of all the file names/paths in config.

  • config (ConfigObj) – Object defining the model and its inputs.

Returns

config dictionary with complete file paths.