SOD Strategy File via the Editor
Before going through this walkthrough, you should've installed SOD as described in the installation document. There are two steps to using SOD: creating the strategy file and running SOD on the strategy file. This document covers creating a SOD strategy file from the GUI editor. If you would like a lower level, XML-based view of how SOD works, please see the Strategy File via XML document.
First start the GUI editor by running
sodeditor.sh
under Unix or Mac OS X
or
sodeditor.bat
under Windows.
The SOD editor should start with the tutorial strategy file preloaded. This is contained within the editor so there is no need to worry about messing anything up since it can be reset by choosing Open Tutorial from the File menu. You will see several tabs which cover the various sections, or arms, of a SOD run. We will cover each in turn.
Properties
The Properties tab configures various run-encompassing settings. The various items in this tab configure big pieces of SOD functionality, such as where to write status files and how often to check for events. Basically, anything that doesn't fit in a specific arm gets stuck here. These items make more sense in the context of specific run strategy, so we'll refer back to the Properties tab as we come to items that relate to these settings.
Event
The Event tab contains the settings for the Event Arm. These settings indicate which server SOD should ask for events, which events are of interest to this run, and what, if anything, to do with them. The first part of the Event Arm's configuration defines the query to send to an event server. The tutorial configuration file uses the IRIS Event server to get events. It restricts the events returned by the query to be of magnitude greater than 6 during January of 2003, but allows them to come from anywhere in the world.
One subtle point is that a single real earthquake will be in multiple catalogs within the DMC's database. The DMC doesn't have enough information to group these origins into a single event. As such, they appear in seperate events. So, it is usually wise to pick a particular catalog to avoid duplicate processing of events. The default here is the PREF catalog from the DMC. PREF is not a true catalog, but something that the DMC Event server understands as the "best" catalog depending on the time of the request. The weeklies, or WHDF, catalog from the NEIC is another common one for historical data. If you are doing a SOD run and want near real time data, then you probably want to use FINGER catalog. This is because that has a short delay from the earthquake's occurrance to the location that is being included in the catalog. However, since this tutorial run is historical, PREF is a good choice.
These values can be changed and SOD has many more settings, but this is a nice minimal set of parameters. This covers what SOD will ask for in its event queries and who it will ask, but there's a property setting in this run that affects the event query. In the Properties tab the setting Event Query Increment is set to 1 week. This tells SOD how much of your event query to ask for in a single query to the event server. A good general rule here is to make this value just large enough to ensure that at least one event will be found for every query, but not so large that hundreds will be found. For this run, we're getting earthquakes of magnitude 6 or higher throughout the world. About 200 of those happen every year, so 1 week is a suitable value for the event query increment for this run.
After the query to the remote event server, we have our events stored locally. Now we could add some additional subsetting, based on the origin, that can't be done with simple query-based subsetting. However, for the tutorial we will assume all of these events are fine. Just to make running sod a little more interesting, the tutorial includes an event processor, printLineEventProcessor. This one just prints out every event's information on arrival.
The tutorial's Event Arm also contains an Event Status generator. This generates HTML pages in the Status Directory, set in the properties tab, with all of the events SOD has gotten and their status in the run. After you've started a run, you can go to the directory set in the properties tab (status by default) and look at event.html in your web browser to see what the event arm is doing.
Feel free to modify any of these values to customize your search. Be aware that some servers may not have data for all types of earthquakes. Also, it is possible to make choices that result in no data matching. Mistakes are the best way to learn, so click away!
Network
The Network tab is the other side of the coin. Once you have earthquakes, you must pick stations in order to ask for data. This query is sent to the IRIS Network server. We will get all stations in the II network, sites (which loosely correspond to seed loc ids) that are either space-space or 00 and channels that are long period. The construction is that the band code must be L and the gain code cannot be O. This accepts both LH? and LL? channels, but rejects LOG channels. Of course there are other, probably better, ways of accomplishing this same thing, but this is a good way of introducing the logical subsetters. Notice that there are three channel subsetters joined with a logical AND and one of these is a logical NOT that contains another subsetter. SOD makes heavy use of the ability to build up complex queries from simple building blocks glued together with logical operators. SOD tries to provide lots of small operations, instead of big monoliths, in order to give the user the flexibility to use it in new and interesting ways.
You will also notice that there are quite a few effective time subsetters. These are not strictly required. The SOD run would likely generate the same result if they were not there, but adding them allows SOD to be more efficient. By rejecting stations and channels that were not in existence at the time covered by your earthquake request, SOD is able to avoid a significant number of calls on the remote server. For example, if you eliminate a station, SOD need not retrieve the channels for that station. In general, SOD will run faster if you try to eliminate as much as possible as soon as you are able.
Waveform
The Waveform tab contains the settings for the waveform arm. This arm finishes up the work started by the event and network arms. It pairs up all the channels from the network arm with all of the events from the event arm and runs various subsetters over them to eliminate unwanted items. The first subsetter is a distance range subsetter. Only events that are at least 30 degrees, but less than 90 degrees away from the station are processed. This is an example of a type of subsetting that cannot be performed within the event or network tabs as it involves a combination of both the event and station information.
The Phase Request selects the time range, relative to particular phases, for which the server will be asked. The travel time calculations are based on theTauP Toolkit, so any choice of phase and model that is compatible with TauP is allowed. It is important to be careful of phases that might not exist at all distances likeP and S. An alternative is to use ttp and tts, which are TauP aliases for p, P, Pn, Pdiff, PKiKP, PKIKP and s, S, Sn, Sdiff, SKIKS respectively. In any case, the first arriving phase of that name is used. The offsets are added to the phase times to get the request time window. Note that this means that the begin offset should usually be negative in order to include the phase. The server will actually return a slightly wider time window than the actual request in order to avoid splitting data chunks.
Once the request is ready, SOD needs to choose the server. In this case, we will send it to the IRIS POND. Users need to know the characteristics of the servers that they use. For example, the POND only has data for events of magnitude 5.5 or larger and the BUD only has data for the last three months.
Next is the Some Coverage subsetter. It acts on the server's response to a query for available data, simply requiring that there be some. This is a pretty common subsetter to use as it keeps SOD from asking for data that doesn't exist, as well as logging the fact that the data wasn't available. This aids in SOD's ability to go back later and retry requests if the data was not yet available, perhaps due to a delay in transmitting the data from the station.
At this point, SOD will request and retrieve the actual data. The last items will print a line saying how many seismograms were received for each request and then save the data in SAC format in a directory. Because of gaps in the original recording, it is possible to get more than one seismogram from a single request, but usually for small time windows this does not happen.
The SacFileProcessor allows you to customize the directory naming structure. First, the dataDirectory element gives the parent directory into which SOD will build the actual event directories. Sod will create this directory if it does not exist. Next, the eventDirLabel creates the name of each event's subdirectory. We will name the directories with Event_ followed by the time of the event as year_Jday_hour_minute_second. Documentation on the time format can be found here.
The last items in the waveform tab are the status processors. They generate html pages that show how SOD is progressing, what events and stations were used, and images of the retrieved seismograms.
Run SOD
Although there is a GUI for editing the strategy files, SOD itself is not a GUI application. This is intentional since SOD will likely be a long running background processes, so command line execution is preferred. To start a SOD run, you need to save the XML strategy file to disk. Then start it up with
bin/sod.sh -f mysod.xml
bin\sod.bat -f mysod.xml
Once SOD is started, open theindex.html
file within the status
directory.
You will see a map of the events that have been found as well as some statistics about the run. The
Networks link shows which networks, stations, and channels were accepted by SOD. The Events link in
the menu on the left takes you to a page with the same map, but with a list of the accepted events
below. Each event link goes to a summary for that event showing which stations were accepted. The
stations in the list are links that show more information about the station and event, which
channels retrieved data, and an image of the seismogram, if it was successful.
You should also look at the Errors page since any problems that occur will be reported there. Also, the Wily link takes you to the Wily DHI status monitor. Wily will indicate if a server is down. The Strategy link shows the original strategy file. These are mostly useful if the status pages from a SOD run are on a web server.
WEED
Now that you have seen the tutorial strategy, feel free to visit the WEED strategy, also located in the File menu. It attempts to make SOD behave similarly to the IRIS WEED program. There are some areas where making the functionality exactly like WEED would have been harder on the user, so it was designed merely to be similar, not identical. In addition to the functionality in the Tutorial strategy, the WEED strategy also supports distance, azimuth, and back azimuth from a fixed point for events, response output to file, more logical operations, and distance, azimuth, back azimuth, and mid point for event station pairs.