View source for Publishing UCERF3-ETAS Event Reports

'''This document is currently under construction.'''

After successfully running a UCERF3-ETAS simulation and generating our plots, the generated UCERF3-ETAS forecast results can be published as part of a larger SCEC Event page. This page outlines the process by which results are published.

Refer to [[UCERF3-ETAS Measurements]] for detailed instructions on how to run simulations and generate plots across HPC systems. The following examples allow us to take our generated results directly from the HPC system on which the computation occurs, although results can be published from any system with an internet connection.

== Creating and Updating SCEC Event Pages ==
SCEC Event Pages detail earthquake events. For a given mainshock, recorded magnitude, time and location, and aftershock sequences are recorded. Identify a given event from its USGS ID and use this to generate an event on the SCEC.org website at https://central.scec.org/earthquakes/eventpage/generate. (See Figure 1).

After generating an event page, it should be populated and available to view from the SCEC Event Pages list. This page is not yet published and isn't available to the public. Navigate to the "View" link to view the event page. (See Figure 2).
Under the Table of Contents, you shouldn't see a "UCERF3-ETAS Forecast" yet, but after generating your results and making them available, you will be able to update this event page by selecting the "Regenerate Page with Latest Data" button.

[[File:SCEC Event Page Generator.png|400px|thumb|Fig 1. SCEC Event Page Generator available at scec.org]]
[[File:Malibu EQ.png|400px|thumb|Fig 2. SCEC Event Page for M4 earthquake near Malibu, CA]]

'''TODO''': Show the final UCERF3-ETAS forecast successfully in the SCEC Event page

== Publishing the UCERF3-ETAS Forecast ==

Generate your UCERF3-ETAS forecast for a given earthquake event following instructions available at [[UCERF3-ETAS Measurements]].
Our generated results are pushed to a GitHub repository (kmilner/event-reports) that is directly read by the SCEC Event Page.
Clone this repository with the following command:

<code>git clone https://github.com/kevinmilner/event-reports.git</code>

We can't directly copy results into this repository. The data is prepared using the u3etas_jar_wrapper shell script. You should already have such scripts downloaded and made available to execute by adding to your PATH. If not, clone the repository.

<code> git clone https://github.com/opensha/ucerf3-etas-launcher.git</code>

The following example has the event-reports repository cloned in our home directory on Expanse. Execution updates the local repository, after which you can <code> git push</code> the changes upstream given sufficient permissions. Recall that such changes don't update an already generated SCEC Event page, in which case the page will have to be regenerated.

<code>
u3etas_jar_wrapper.sh org.opensha.commons.data.comcat.plot.ComcatReportPageGen --event-id ci40186202 --min-mag 0d --radius 50 --output-parent-dir /expanse/lustre/projects/usc143/flsilva/event-reports --etas-dir outputs --etas-output-dir /expanse/lustre/projects/usc143/flsilva/event-reports/ucerf3-etas
</code>

Ensure that you have selected the correct Event ID and directories. See the following section for an explanation of the parameters used.

Prior to execution on Expanse, go over the following checklist.
* Ensure you're on an interactive node:
<code>srun --partition=debug  --pty --account=usc143 --nodes=1 --ntasks-per-node=4 --mem=16G -t 00:30:00 --wait=0 --export=ALL /bin/bash</code>
* Update your bash config with:
<code>
module load cpu/0.15.4

module load openjdk/11.0.2

export ETAS_JAR_DISABLE_UPDATE=1

ETAS_LAUNCHER=/expanse/lustre/projects/usc143/qwxdev/apps/expanse/rocky8.8/ucerf3-etas/069e27e/ucerf3-etas-launcher

export PATH=$ETAS_LAUNCHER/sbin:$PATH
</code>

== ComcatReportPageGen Usage ==
The [https://github.com/opensha/ucerf3-etas-launcher/blob/master/sbin/u3etas_jar_wrapper.sh u3etas_jar_wrapper.sh] shell script is used to execute any Java application in the provided OpenSHA Jar. In this case, we're executing the [https://github.com/opensha/opensha/blob/master/src/main/java/org/opensha/commons/data/comcat/plot/ComcatReportPageGen.java ComcatReportPageGen] application.

<code>
usage: ComcatReportPageGen [-?] [-d <arg>] -e <arg> [-eod <arg>] [-etas <arg>] [-m <arg>] [-o <arg>] [-opd <arg>] [-r <arg>]
 -?,--help                        Display this message
 -d,--days-before <arg>           Number of days of events before the mainshock to fetch (default: 3)
 -e,--event-id <arg>              ComCat event id, e.g. 'ci39126079'
 -eod,--etas-output-dir <arg>     If supplied, ETAS only results will also be written to <path>/<event-id>
 -etas,--etas-dir <arg>           Path to a UCERF3-ETAS simulation directory
 -m,--min-mag <arg>               Minimum magnitude of events to fetch (default: 0.0)
 -o,--output-dir <arg>            Output dirctory. Must supply either this or --output-parent-dir
 -opd,--output-parent-dir <arg>   Output parent dirctory. The directory name will be generated automatically from the
                                  event name, date, and magnitude. Must supply either this or --output-dir
 -r,--radius <arg>                Search radius around mainshock for aftershocks. Default is the greater of 10.0 km and
                                  twice the Wells & Coppersmith (1994) median rupture length for the mainshock magnitude

</code>

In our example, we specify the absolute path to where we cloned the event-reports repository, as well as the absolute path to a UCERF3-ETAS results directory within the event-reports repository. Our results are written into two folders to allow us to filter by either date or Event ID.

If running on Expanse, copy any plots from scratch into your own account as we can't run in someone else's folder. You can create a tarball and copy the whole folder into your account. The same logic should apply to any other HPC system. Ensure you execute the script on an interactive node, not on the head node.

== Workflow Automation and Potential Challenges ==
'''TODO''': Discuss reasons why we aren't currently automating this workflow (permissions, simulations conflicts) and how we may go about automating such a workflow in the future.