# Earthworm Modules:

# Shakemapfeed Overview

(last revised 15 April, 2002)

Shakemapfeed is an Earthworm module for retrieving ground-motion parameters from an Earthworm database and creating the data files needed as input by the shakemap program. Here is the quick overview of how shakemapfeed works, followed by a more detailed description:

- Trigger on an event message from Earthworm system.

- If M > threshold and Mweight > threshold, insert it in the processing list.

- Create shakemap input files according to this schedule:

- Build first file DelayFirstFeed seconds after receiving event message.
- Build next file UpdateInterval minutes after previous one.
- Don't create new files if there's no new data available.
- Stop generating automatic files UpdateDuration minutes after event origin time.

- Request these data from DBMS to include in shakemap files:

- SM parameters associated with this eventid.
- Unassociated SM parameters in:

- +/- Latitude/Longitude from epicenter
- Time range from before origin time to beyond maximum travel time.

- Check data before writing the shakemap files:

- Verify that timestamp is consistent with traveltime for the event.

- use simple layered velocity model & P/S ratio (ala binder)
- allow anywhere from P to S+ (with tolerance)
- allow different time tolerance for different network codes

- Eliminate duplicate data from same channel.

- always use last data loaded into DBMS

### Shakemapfeed Input and Earthquake Lists

Shakemapfeed watches its input shared memory region for three different types of messages: TYPE_HYP2000ARC (required), TYPE_EQDELETE (optional), and TYPE_MAGNITUDE (optional). Using information from those messages, shakemapfeed maintains two lists of earthquakes:

> 1. qualifying events to be fed to shakemap (up to 50 events).
> 2. other events that shakemapfeed has seen (most recent 100 events).

The key in both lists is the eventid generated by binder_ew and contained in earthworm messages. Both lists contain the event hypocentral and magnitude information. The "qualifying event" list also contains the DBMS load time of the newest piece of information already sent to shakemap, the system time at which the next shakemap file should be created, and the system time when automatic shakemap feeds should cease. The qualifying list is periodically written to a binary disk file which shakemapfeed reads on startup. This enables shakemapfeed to keep working on the same events after a restart.

Processing TYPE_HYP2000ARC messages:
Shakemapfeed reads the eventid, origin time, location, magnitude and magnitude weight (preferred magnitude fields if they exist; otherwise, duration magnitude fields) from the summary line. To see if the event qualifies for shakemap processing, shakemapfeed tests the magnitude values against configured minimum magnitude and minimum magnitude weight. If the event fails either test, shakemapfeed stores it in the "other events" list, in case it gets information later about the event which would make it qualify. If the event passes both tests, shakemapfeed stores (or updates) it in the "qualifying list." Then it schedules times to create shakemap files for the event:

> - The first files will be created at the current system clock time plus DelayFirstFeed seconds.
> - Subsequent files will be created every UpdateInterval minutes. These subsequent feeds will produce output only if new data is available since the previous feed.
> - No more shakemap files will be generated after the system clock is later than event origin time plus UpdateDuration minutes.

If shakemapfeed gets an event whose UpdateDuration is already expired, it will perform one feed for the event with no delay. It assumes that this is a manually re-run event for which you want data now!

Processing TYPE_EQDELETE messages:
The TYPE_EQDELETE message contains only the eventid. It gives the user a means of stopping shakemapfeed from automatically creating more shakemap files for a given event (useful if the event or its magnitude is bogus). Shakemapfeed reads the eventid from the message, finds the event in qualifying list, and deletes it. Delete is really the wrong word, as shakemapfeed does not remove the event from the list, but sets the "update until this time" field to zero. It logs the message:

> "ProcessDelete: TYPE_EQDELETE for eventid: #"

If it can't find the eventid in the qualifying list, it logs the message:

> "ProcessDelete: TYPE_EQDELETE for eventid: # - not in processing list!"

Processing TYPE_MAGNITUDE messages:
Shakemapfeed reads the magnitude message, paying attention to the eventid, magnitude, magnitude weight. If the magnitude weight is less than the configured minimum magnitude weight, shakemapfeed will not update the lists with the new information. It instead logs a message:

> "ProcessMag: eventid: # ignored new magnitude: ... weight too low to override existing."

Shakemapfeed looks for the eventid in both "qualifying" and "other events" lists. If the event isn't in either list, it logs a message:

> "ProcessMag: TYPE_MAGNITUDE for eventid: # - no record of this eventid!"

If the new magnitude weight is greater than or equal to the configured minimum magnitude weight, shakemapfeed updates the magnitude and weight in the event lists, and logs the message:

> "ProcessMag: eventid: # assigned new magnitude: ..."

Then shakemapfeed checks to see if the updated event qualifies or not. If not, shakemapfeed deletes it. If it's a new qualifier, shakemapfeed adds it to the qualifying list and sets its timers. If it still qualifies, shakemapfeed will create shakemap files at the next scheduled time. If the event's UpdateDuration has already expired, shakemapfeed will force the creation of shakemap files with no delay.

### Creating Shakemap Files

Each time thru its main processing loop, shakemapfeed reviews its list of qualifying events from most recent to oldest. If an event's "feed shakemap" timer has expired and it's still earlier than the "stop automatic update" time, shakemapfeed will query the DBMS for strongmotion data related to the event. If any new data has been loaded into the DBMS since the last time shakemapfeed checked, shakemapfeed will create output files. If no new data is seen, shakemapfeed does not create new files. In both cases, shakemapfeed then resets the "feed shakemap" timer to the current system time plus UpdateInterval minutes. After reviewing the entire list, shakemapfeed writes the list to a disk file (which shakemapfeed reads on startup).

### Retrieving Strongmotion Data from DBMS

Shakemapfeed defines a box and time range around the event to use in retrieving strongmotion data from the DBMS. The boundaries of the box are set to event latitude +/- LatitudeRange degrees and event longitude +/- LongitudeRange degrees. The time range is from:

(origin time - MaximumTimeTolerance) to
(origin time + maximum travel time + travel-time error + time-post-S-arrival + MaximumTimeTolerance)

where:

- MaximumTimeTolerance is the maximum value of DefautTimeTolerance and NetTimeTolerance commands.
- maximum travel time is calculated to farthest corner of the box using the given velocity model (lay and psratio commands)
- travel-time error is hardcoded at 5.0 seconds
- time-post-S-arrival is hardcoded at 60.0 seconds

Shakemapfeed first requests all data within the box that is associated with the event (using the eventid and QuakeAuthor to retrieve the DBMS id of the event). Then it requests all unassociated data that falls within the box and the time range. A maximum of MaxDataPerEvent channels of strongmotion data will be retreived from the DBMS (duplicates count as independent channels for this count).

Once all strongmotion data is retrieved, shakemapfeed goes into filtering mode. It weeds out duplicate readings from the same channel, always keeping the last one entered into the DBMS. It throws away data whose timestamp is outside the expected range for that station:

(origin time + minimum travel time - travel-time error - NetTimeTolerance) to
(origin time + maximum travel time + travel-time error + time-post-S-arrival + NetTimeTolerance)

It also throws away any data with component codes that were listed in BlockComponent commands. When filtering is complete, shakemapfeed writes its output file(s) in the format specified with ShakemapFormat command into the TempDir directory. When the files are complete, shakemapfeed moves them to the OutputDir directory.

Note on EventIDs:
Each earthquake has two eventids, one inside the Earthworm realtime system (assigned by binder_ew) and another inside the Earthworm DBMS (assigned by the DBMS). All Earthworm messages described above contain the binder_ew eventid. The strongmotion data in the DBMS is associated to an event through its DBMS id. Some networks create earthquake web pages and QDDS messages that list the binder_ew id, others list the DBMS id. Both eventids are known to shakemapfeed. A configuration file command, UseEventID, allows you to choose which of the two eventids shakemapfeed will write to its output so that your resulting shakemap will be labeled with the eventid that is consistent with your other web-based information and QDDS messages.

Module Index | shakemapfeed Commands