CyberShake Hazard Calculation

CyberShake Hazard Curve/Disaggregation Calculation

Note: this wiki entry assumes basic familiarity with the CyberShake database including finding CyberShake Run IDs of interest for a given CyberShake Study. For information on various studies see Comparison of CyberShake Studies.

Common Setup

The tools mentioned below are part of the OpenSHA platform (http://www.opensha.org). The easiest way to obtain the code needed for these tools is to download the complete OpenSHA jar file nightly build from here:

opensha-complete.jar nightly build

You can also obtain the source code directly and compile it yourself, either via an ant build script or via eclipse. For details on this approach, see http://opensha.usc.edu/trac/wiki/SettingUpEclipse

Examples here will assume that you are using the jar file approach.

Running OpenSHA on the command line

Assuming that opensha-complete.jar is in the current directory, the following command can be used to run the fictional java class org.opensha.Test:

java -cp OpenSHA_complete.jar org.opensha.Test

If you would like to specify an alternative CyberShake database host and/or table name, specify the cybershake.db.host and or cybershake.db.name property. For example:

java -Dcybershake.db.host="my.server.com" -Dcybershake.db.name="CyberShake" -cp OpenSHA_complete.jar org.opensha.Test

Hazard Curve Calculation

Hazard curve calculation/plotting is done via the org.opensha.sha.cybershake.plot.HazardCurvePlotter OpenSHA class. Here is the usage:

java -cp opensha-complete.jar org.opensha.sha.cybershake.plot.HazardCurvePlotter --help
usage: HazardCurvePlotter [-?] [-af <arg>] [-benchmark] [-c] [-cmp <arg>]
       [-comp <arg>] [-cvmvs] [-e <arg>] [-ef <arg>] [-f] [-fvs <arg>] [-h
       <arg>] [-imid <arg>] [-imt <arg>] [-n] [-novm] [-o <arg>] [-p
       <arg>] [-pf <arg>] [-pl <arg>] [-R <arg>] [-r <arg>] [-s <arg>]
       [-sgt <arg>] [-sgtsym] [-t <arg>] [-v <arg>] [-vel <arg>] [-w
       <arg>]
 -?,--help                            Display this message
 -af,--atten-rel-file <arg>           XML Attenuation Relationship description file(s) for comparison. Multiple files should be comma separated
 -benchmark,--benchmark-test-recalc   Forces recalculation of hazard curves to test calculation speed. Newly recalculated curves are not kept and the original curves are plotted.
 -c,--calc-only                       Only calculate and insert the CyberShake curves, don't make plots. If a curve already exists, it will be skipped.
 -cmp,--component <arg>               Intensity measure component. Options: GEOM,X,Y,RotD100,RotD50, Default: GEOM
 -comp,--compare-to <arg>             Compare to  aspecific Run ID (or multiple IDs, comma separated)
 -cvmvs,--cvm-vs30                    Option to use Vs30 value from the velocity model itself in GMPE calculations rather than, for example, the Wills 2006 value.
 -e,--erf-id <arg>                    ERF ID
 -ef,--erf-file <arg>                 XML ERF description file for comparison
 -f,--force-add                       Flag to add curves to db without prompt
 -fvs,--force-vs30 <arg>              Option to force the given Vs30 value to be used in GMPE calculations.
 -h,--height <arg>                    Plot height (default = 500)
 -imid,--im-type-id <arg>             Intensity measure type ID. If not supplied, will be detected from im type/component/period parameters
 -imt,--im-type <arg>                 Intensity measure type. Options: SA, Default: SA
 -n,--no-add                          Flag to not automatically calculate curves not in the database
 -novm,--no-vm-colors                 Disables Velocity Model coloring
 -o,--output-dir <arg>                Output directory
 -p,--period <arg>                    Period(s) to calculate. Multiple periods should be comma separated (default: 3)
 -pf,--password-file <arg>            Path to a file that contains the username and password for inserting curves into the database. Format should be "user:pass"
 -pl,--plot-chars-file <arg>          Specify the path to a plot characteristics XML file
 -R,--run-id <arg>                    Run ID
 -r,--rv-id <arg>                     Rupture Variation ID
 -s,--site <arg>                      Site short name
 -sgt,--sgt-var-id <arg>              STG Variation ID
 -sgtsym,--sgt-colors                 Enables SGT specific symbols
 -t,--type <arg>                      Plot save type. Options are png, pdf, jpg, and txt. Multiple types can be comma separated (default is pdf)
 -v,--vs30 <arg>                      Specify default Vs30 for sites with no Vs30 data, or leave blank for default value. Otherwise, you will be prompted to enter vs30 interactively if needed.
 -vel,--vel-model-id <arg>            Velocity Model ID
 -w,--width <arg>                     Plot width (default = 600)

The GMPE comparisons mentioned in the above options use XML configuration files that can be downloaded from here.

It is perhaps easiest to understand the important options via an example:

java -cp opensha-complete.jar org.opensha.sha.cybershake.plot.HazardCurvePlotter --run-id 4498 --period 3,5,10 --output-dir /tmp/test_curves --type pdf,png,txt --no-add --cmp RotD50

This calculates CyberShake hazard curves for run ID 4498, periods 3,5,10, and stores them in /tmp/test_curves. NOTE: This tool was originally created for use by CyberShake developers to calculate and insert curves into the CyberShake database. As an external user you must supply the --no-add option in order to calculate curves without attempting to insert them into the database, otherwise it will prompt you for a password and fail when you don't supply one.

If you want to include GMPE comparison hazard curves, first download XML descriptions of the models you wish to use from here. Then add the following options:

--erf-file /path/to/MeanUCERF.xml --atten-rel-file /path/to/cb2008.xml,/path/to/ba2008.xml,/path/to/cy2008.xml,/path/to/as2008.xml

Disaggregation Calculation

Syntax for the disaggregation calculator is similar to the Hazard Curve Calculator above and is located at org.opensha.sha.cybershake.plot.DisaggregationPlotter:

java -cp opensha-complete.jar org.opensha.sha.cybershake.plot.DisaggregationPlotter --help
usage: DisaggregationPlotter [-?] [-cmp <arg>] [-e <arg>] [-i <arg>]
       [-imid <arg>] [-imt <arg>] [-o <arg>] [-p <arg>] [-pr <arg>] [-r
       <arg>] [-R <arg>] [-s <arg>] [-sgt <arg>] [-t <arg>] [-vel <arg>]
 -?,--help                   Display this message
 -af,--atten-rel-file <arg>           XML Attenuation Relationship description file(s) for comparison. Multiple files should be comma separated
 -cmp,--component <arg>      Intensity measure component. Options: GEOM,X,Y,RotD100,RotD50, Default: GEOM
 -e,--erf-id <arg>           ERF ID
 -i,--imls <arg>             Intensity Measure Levels (IMLs) to disaggregate at. Multiple IMLs should be comma separated.
 -imid,--im-type-id <arg>    Intensity measure type ID. If not supplied, will be detected from im type/component/period parameters
 -imt,--im-type <arg>        Intensity measure type. Options: SA, Default: SA
 -o,--output-dir <arg>       Output directory
 -p,--period <arg>           Period(s) to calculate. Multiple periods should be comma separated (default: 3)
 -pr,--probs <arg>           Probabilities (1 year) to disaggregate at. Multiple probabilities should be comma separated.
 -r,--rv-id <arg>            Rupture Variation ID
 -R,--run-id <arg>           Run ID
 -s,--site <arg>             Site short name
 -sgt,--sgt-var-id <arg>     STG Variation ID
 -t,--type <arg>             Plot save type. Options are png, pdf, and txt. Multiple types can be comma separated (default is pdf)
 -vel,--vel-model-id <arg>   Velocity Model ID

Here is an example for the same run as before:

java -cp opensha-complete.jar org.opensha.sha.cybershake.plot.DisaggregationPlotter --run-id 4498 --period 3,5,10 --output-dir /tmp/test_disagg --probs 4e-4 --type pdf,png,txt --cmp RotD50

You can also include GMPE comparisons which will plot to separate files using the same --atten-rel-file argument as before. The --erf-file argument is not needed (or supported) as the correct ERF was already instantiated in the code to perform CyberShake disaggregation.