SOSA User's Guide

SOSA (Synthetic and Observed Seismogram Analysis) is designed to ease the task of retrieving and performing basic analysis on both observed and synthetic seismograms. We designed the application to allow researchers to easily retrieve seismograms from disparate sources, such as model outputs and observed signals, and apply basic analysis methods. The SOSA application aims to reduce the amount of time spent on repetitive import and translation tasks, while not compromising the wide range of analytic processes researchers require.

The following attempts to explain how to best utilize the SOSA tool. If you can't find the answer to you question, or encounter a bug while using this tool, please contact the development group at IRIS immediately. Contact information is listed at the bottom of this page.

SOSA is released under the GPL. Please consult the associated README.txt file for this license, and the licenses of included libraries.

SOSA is a Java application and can run on any computer with a Java Virtual Machine (JVM). The SOSA distribution is available in archived form as a "tar.gz" or ".zip" file, or as an executable install that interactively guides the user through installation. We strongly recommend using InstallAnywhere to install this software.

A successful installation of SOSA will result in the following files and directories:

data/ - Contains sample data files.
docs/ - Contains the User's Guide and Tutorial.
icons/ and images/ - Graphics used in program.
lib/ - Associated java packages. Licenses for some libraries can be found at the end of the README.txt file located in the main application directory.
log4j.xml - Controls logging parameters for the application.
logs/ - Logs from runs. If you experience a problem with the application, you might be requested to email the contents of this folder to help with debugging.
README.txt - Contains release and licensing information.
sosa - Optional script for launching SOSA.
sosa.jar - Contains the main SOSA application.
sosa.properties - Contains user properties for SOSA. Maintains a record of user preferences.

SOSA requires that a Java Virtual Machine (JVM) version 1.4 or higher be installed on the host machine. Sun provides installable versions of the Java Runtime Environment (JRE) for download for most operating systems.

SOSA can work as a standalone application, but is most useful when connected to the Internet. Accessing seismograms through a Data Handling Interface (DHI) or Storage Resource Broker (SRB) requires SOSA to make outgoing calls on some non-standard ports. These ports are shown in the Edit/Configuration/DHI and SRB windows. Some firewalls may block external calls on non-standard ports; check with your systems administrator if you encounter problems. Also, please let the maintainer of this software know of this or any other problems you encounter running this software.

SOSA is a GUI interface enabling you to retrieve, display, process and save seismograms. The following sections detail the individual capabilities of the SOSA application. For a step-by-step walk-through of the software, see the SOSA Tutorial.

SOSA provides a simple graphical interface enabling you to retrieve observed seismograms from a Data Handling Interface (DHI). See Application Configuration for information on the DHI technology and configuration. SOSA is preconfigured to query servers at the IRIS DMC.

The application initially displays an event search panel shown below, allowing searches based on time and location criteria. The application is preconfigured to display parameters applicable to the Northridge Event (1/17/04).

Location: Locations can be selected with either a lat/lon box or a radius search (chosen by toggling the appropropriate radius button). All numbers are degrees; negative numbers indicate south or west and are not valid entries for radii searches.

Parameters: Magnitude parameters are the standard estimates of magnitude. Estimated event depth is in kilometers.

Parameters entered in the search panel are used to query the configured Event Data Center through a DHI (see Configuration for more information on selecting data centers). The application launches a status dialog providing information about the query progress. Some event data centers contain event information from multiple sources and therefore provide multiple instances of each event. Before displaying, events are filtered to remove duplicates. Queries over smaller regions and shorter time spans are generally faster.

The resulting queries are displayed in the table above. By selecting an event you'll open up the station search panel, enabling you to retrieve seismograms associated with the selected event.

Location: As in event searches, location searches for stations can be selected with either a lat/lon box or a radius search (chosen by toggling the appropropriate radius button). All numbers are degrees; negative numbers indicate south (latitude) or west (longitude) and are not valid entries for radii searches. The panel defaults to a local box with sides of 6 degrees centered on the event.

Parameters: Parameters are orientation, sampling and time interval. The N, E and Z orientations refer to (azimuth, dip) values of (0, 0), (90, 0) and (0, -90) respectively. All will bring back all orientations. Sampling is in Hz; common sampling intervals are:

The time interval constraints allow you to specify the number of minutes since the event to display. The time window of downloaded seismograms can be further adjusted in the display and processing panels.

Specification: Allows further filtering of stations by network, station, site and channel name. Filtering is case insensitive, wildcards are not yet supported.

As with event searches, narrower channel searches usually respond more quickly than longer queries. If you initially retrieve no channels, first try altering the orientation to "ALL". Many channels have non-standard orientations.

To display seismograms, select those you want to look at (drag with the mouse, use the CTRL key to select non-contiguous entries), and click on "Display Seismograms". The application will then retrieve the seismogram data along with instrument response information and display the seismogram in the "Display" panel.

To retrieve a synthetic seismogram from an observed location, click on "Find Synthetics" and follow the instructions for Retrieving Seismograms from the DDDS.

SOSA provides an interface to retrieve synthetic seismograms from the Digital Data Distribution System (DDDS), a system that provides access to event simulations stored within the SRB and tagged with known metadata items. To get to the DDDS retrieval interface, choose "DDDS" in the drop down at the top of the Request panel (default is "DHI"). Alternatively, choosing one or more locations from the DHI Station Search view and clicking on "Find Synthetics" will also take you to the DDDS interface.

The Available Simulations table displays all the known DDDS simulations, with basic metadata. Additional metadata for each simulation is available in a panel to the right. Simulations can be filtered by location or parameters. Enter the desired restrictions and click "Filter Simulations". Only those simulations matching the selection criteria will be displayed. To see all the simulations, click "Show All".

The table can also be sorted by name, lat, lon, magnitude or depth, by clicking on the column name. To select seismogram locations from a given simulation, select the row of the simulation and click "Select Simulation". Use the "Refresh List" button to re-connect with the SRB and get a new list of available simulations. Any filter previously used to limit the simulation list will be erased.

Requests for synthetic seismograms from the DHI location interface will bring up just a list of simulations. If there are simulations whose epicenter locations match the event from the DHI search, the list of simulations will be filtered to match that event. Otherwise all simulations will be shown. Once you select a simulation, SOSA will check for the availability of data at each of the requested locations within the selected simulation, and populate the Select Location panel.

Select Location

Latitude/longitude location specifications, with orientation can be entered once a simulation is chosen. The application will check that data for that location is available within the selected simulation, and add that location to the location list if it is.

The above panel shows locations selected within a Terashake simulation. The first two locations were entered by hand, the remaining were selected from a DHI list of station locations. The exact location entered may not be available, but if a location exists within parameters set by the DDDS, it will be used. For instance, a synthetic seismogram is not available at exactly 33.609 N, 116.455 W (PFO seismic station), but the location 33.610 N, 116.456 W is within an acceptable subsitution range. The DDDS does not currently support interpolation between simulation grid points.

To view synthetic seismograms, select one or more (drag with the mouse, use the CTRL key to select non-contiguous entries) and click on "Retrieve Seismograms". The application will then retrieve the seismogram data along with associated metadata and display the seismogram in the "Display" panel.

Retrieving Seismograms from an SRB (top)

SOSA also provides an interface similar to MySRB to retrieve seismograms from a Storage Resource Broker. To get to the SRB retrieval interface, choose "SRB" in the drop down at the top of the Request panel (default is "DHI"). SOSA comes preconfigured to access the SCEC SRB at UCSD; this can be altered in the Configuration window. A view into the SCEC SRB is shown below.

Either enter the path to the data of interest within the SRB or navigate through the listed collections. SOSA provides access both to objects and metadata within the SRB, however the only objects that can be opened are the same as those accessed from a local disk, currently SAC and mSEED volumes.

Note: Inactive SRB connections will time out after 30 minutes. If your connection has timed out, go to the SRB Configuration Panel and click the "Reconnect" button.

Retrieving Seismograms from a local file (top)

SOSA can load seismograms stored locally in SAC and mSEED format. Use the File/Load Local menu option and choose the appropriate file format. Some header fields are read, including location, channel names, sample rates and date/time information, if available.

Viewing Seismograms (top)

Seismograms retrieved from a DHI, SRB or local file will automatically be displayed in the "Display" tab. If a seismogram from an event is chosen, information on that event will be displayed at the top of the panel. Each seismogram is displayed with some basic information and also has it's own set of buttons. Only the first two seismograms will be immediately visible, if more that two seismograms are displayed, use the scroll bar on the right hand side to view additional seismograms.

Dragging on the seismogram within the plot window will change the time range of the display. The "Apply" button applies the time window of the selected seismogram to all seismograms in the display panel. This process can be slow. Check button tool tips for more information on individual features.

To process an individual seismogram, use the "Process" button to the left of the display. The application will then copy that seismogram into the processing panel (see below). Seismograms are added in order, and their data points are windowed to the current displayed time range. The "Process All" button in the top right hand corner copies all the displayed seismograms into the process panel. "Clear All" removes all seismograms from the display panel.

Processing Seismograms (top)

In the process panel you can apply processes to individual or groups of seismograms. SOSA displays available processes in the left hand panel; parameters (if any) for that process are displayed below. In the example below, the resample process has four parameters.

Processes can be applied to one or more seismograms. You select a seismogram by toggling the radio button to the left of the seismogram trace. By default, results of a process are shown in a new Process tab. If you don't want a new tab, deselect the "Show results in new tab" option. Also, seismograms not selected to be processed will be displayed in the new tab. To remove a seismogram from the process tab, click the "Clear" button below the seismogram trace.

Some of the processes available are:

Demean: Remove mean amplitude value from all seismogram values.
Cosine Taper Window: Apply a cosine taper window to the seismogram.
Resample: Resample seismogram new sample interval, start and end times.
Butterworth filter: Apply a Butterworth filter to each seismogram.
Gaussian filter: Apply a Gaussian filter to each seismogram.
Convolve: Convolves second selected seismogram with first seismogram, with option to convolve with instrument response.
Overlay: Overlays multiple seismograms in a single panel.
Rotate: Rotates two perpendicular seismograms by the given angle.

Other processes may be available through associated seismogram processing web services. See the section on configuring web services for details.

Saving Seismograms (top)

Seismograms may be saved locally in SAC or mSeed format. Both the display and process seismogram display panels have Save buttons that will bring up the following window:

SOSA provides an appropriate file name based on the metadata associated with the seismogram, and allows the user to save the associated metadata as well.

Application Configuration (top)

SOSA relies on connections with other computing resources. These connections can be configured within the SOSA Configuration window (menu options Edit/Configuration). The following services have configuration options:

DHI (Data Handling Interface)

Connections to different DHI's enable SOSA to retrieve observed seismograms from a variety of global and local data centers. These data centers register with a central nameserver, configured as the default in SOSA. Accessing the name server requires SOSA to make outgoing calls on a non-standard ports, shown below as DHI Nameserver Port. Some firewalls may block external calls on non-standard ports; check with your systems administrator if you encounter problems. Also, please let the maintainer of this software know of this or any other problems you encounter running this software.

The window comes pre-loaded with standard IRIS DHI servers, shown in the panel on the right. Choosing to "Add" a type of server will bring up a list of all known servers of that type that do not appear in that panel. Select one or more and click "Add" to populate the server list. Note that not all servers listed are active; for best results try the main DHI's - IRIS, NCEDC and SCEDC. To remove an individual server, select it from the list and click the associated "Remove" button. "Remove All" will clear all servers from the list. By default, if no servers are selected, all known servers will be searched.

Network servers and waveform servers are closely interrelated. Therefore the selection of network servers will limit the waveform servers available for selection to those associated with selected network servers.

Once you have chosen the servers of interest, click "Save" to save and close the window. "Reset" returns all the fields to the settings in place when you opened the configuration window. "Cancel" closes the window, leaving your configuration unchanged.

See here for a description of the DHI and other DHI client applications.

SRB (Storage Resource Broker)

An SRB can provide extensive storage for community research. SOSA provides an interface to access information stored within an SRB similar to that of the MySRB web interface. By default, SOSA is configured to access the San Diego Supercomputer (SDSC) SRB via the public account.

Accessing an SRB may require SOSA to make outgoing calls on a non-standard port, shown below as 'Port Number'. Some firewalls may block external calls on non-standard ports; check with your systems administrator if you encounter problems. Also, please let the maintainer of this software know of this or any other problems you encounter running this software.

Web Services

SOSA ships with a basic set of processes. To better serve our user base, we will augment these processes via a web service. Users are encouraged to contribute processing capabilities through this means as well.

The IRIS seismoproc web service will be contacted when the SOSA application is started for the names of available processes. Should another service with an identical signature exist, altering the url host and service name will enable SOSA to contact that web service instead of the default IRIS service. SOSA will need to be closed and restarted for the change to take effect.

Event Duplication

The IRIS event server provides information on events from multiple catalogs. By default, SOSA will remove duplicate events, based on the event origin latitude, longitude and depth and the event time. The criteria for those duplication can be configured in the Event Duplication tab of the configuration panel. By de-selecting "Remove duplicate events", all events matching the search criteria will be displayed.

Some event servers contain events from a single catalog. Selecting the removal of duplicate events will slow down the performance of results from these services, without providing any benefits.

Source Code Notes (top)

If you have downloaded SOSA with source code, you'll find the SOSA source code files in the src directory. If you have Apache Ant installed on your system you'll be able to make changes to the source code and rebuild. The SOSA code also comes with tests that run in JUnit. If you make changes to the code, please run the ant task test_all before releasing your changes to an unsuspecting audience.

SOSA is licensed under the Gnu Public License

Providing Feedback (top)

We hope that SOSA will be a useful tool for your research. If you encounter any problems for have any questions about SOSA, please send email to sosa@iris.washington.edu. We'll try to get back to you as quickly as possible. Suggestions for additional features are also welcome.

Java and the Java Coffee Cup Logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Last modified: Tue Jul 19 16:00:58 PDT 2005

		SOSA User's Guide
		Synthetic and Observed Seismogram Analysis
		Version 1.1
		Joanna Muench