Jump to
- Introduction
- Work flow overview
- Quick jump to examples
- Service class overview
- Working Tutorial: The Bare Bones Outline for all examples
- Import the appropriate java classes
- Initialize the services
- Specify the criteria and Fetch the results
- Display the results
- Expected Output from the TRACE tutorial
- Initialize the services
- Specify the Criteria (narrow your search)
- Fetch the results
- Display the results
- Expected Output from the Station tutorial
- Initialize the services
- Specify the Criteria
- Fetch the results
- Display the results
- Output from the Event tutorial
- Initialize the services
- Specify the Criteria
- Fetch the results
- Display the results
- Output from the WAVEFORM tutorial
- Initialize the services
- Specify the Criteria (narrow your search)
- Fetch the results
- Print the results
- Output from the RESP tutorial
Introduction ¶
This tutorial illustrates how to access station, event, and time series (waveform) data from IRIS using the Java Web Service Library.
Example code is included with the .zip file download
Work flow overview ¶
Each example, and the recommended usage pattern, uses the Java Web Service Library in the following manner:
- Initialize the services, using the ServiceUtil class.
- Specify the data of interest, using one the service-specific criteria classes.
- Fetch the data from the service, using your initialized service.
- Process the returned java objects.
Quick jump to examples ¶
- Trace tutorial, a simple example of requesting Trace data (time series & related metadata)
- Station tutorial, a simple example of requesting and printing station metadata
- Event tutorial, a simple example of requesting and printing event (earthquake) parameters
- Waveform tutorial, a simple example of requesting time series (waveforms)
- Resp tutorial, a simple example of printing resp format (from stationxml).
Service class overview ¶
Each service will be initialized through a ServiceUtil class, which handles reading of service-related parameters and avoids creation of unnecessary copies of Service classes.
The Trace class combines the functionality multiple services in
order to return a seismic trace containing data along its associated metadata
Trace Classes ¶
TraceData uses the StationService, WaveformService, and SacpzService classes to retrieve information. It may use either StationCriteria or channel and time parameters to refine the search. Results are returned as a list of Trace objects, which are SAC-like representations of the waveform and channel metadata. Additionally, responses can be obtained, in SAC poles and zeros format.
There are four fundamental data types (classes), each corresponding to a specific IRIS web service. These are:
Station-related Classes ¶
StationService is used to connect to the fdsn-station
webservice, using StationCriteria to refine the search. Results are returned as either a list of Network objects (representing content from StationXML
) or a Java stream of returned Station XML
.
Event-related Classes ¶
EventService is used to connect to the fdsn-station webservice, using EventCriteria to refine the search. Results are returned as either an Event (representing content from QuakeML) or as a Java stream of returned QuakeML
.
Waveform-related Classes ¶
WaveformService is used to connect to the ws-bulkdataselect
webservice, using WaveformCriteria to refine the search. Results are returned in objects of the Timeseries class (one per continuous trace segment) or as a Java stream of returned miniSEED records.
SacpzService is used to connect to the ws-sacpz
webservice, using SacpzCriteria to refine the search.
Working Tutorial: The Bare Bones Outline for all examples ¶
Import the appropriate java classes ¶
These classes include all the station, waveform, and event-related classes, as well as error-handling classes, and date classes. Not all these classes would be needed for each application, but the tutorial will make use of all of them. For an accurate list of imports required with each example, check out the individual example .java files that are available in the .zip download
// Import the error handling classes import edu.iris.dmc.criteria.CriteriaException; // error handling //<i>... more here... // // ServiceUtil is where we obtain all the "hooks" to the web services. import edu.iris.dmc.service.ServiceUtil; // // Import the classes specific to the STATION example // Import the classes specific to the WAVEFORM example // Import the classes specific to the EVENT example // Import other Java classes> // public class MyWSTutorialClass { public static void main(String[] args) { // get access to the services // specify criteria // fetch data // process data } }
Working Tutorial: Importing and printing Trace metadata
Download the complete .java file for this example.
Initialize the services ¶
The following example grabs trace data for a few stations in a network. This code, and all of this example’s following code, would go within
the main function of the bare bones outline.
TraceData traceFetcher = TraceData(); traceFetcher.setAppName("Tutorials");</pre>
Specify the criteria and Fetch the results ¶
This example fetches traces for a few stations in the IU network.
// define the dates of interest DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS"); dfm.setTimeZone(TimeZone.getTimeZone("GMT")); // Date startDate = dfm.parse("2006-09-11T00:00:00.000"); Date endDate = dfm.parse("2006-09-11T00:01:45.000"); Boolean includePZ = true; Trace traces []=null; // Traces are unique in that you could provide a station criteria object (as in the station example) or // you can specify simple criteria directly in the call.</span> traces = traceFetcher.fetchTraces("IU", "AN*,B*","00","BHZ", startDate, endDate, 'B', includePZ);
For additional detail about specifying station search criteria, consult the StationCriteria class within the Java Doc.
Display the results ¶
The traces that are returned contain information akin to that found in SAC files. Let’s loop through it to see what was returned.
//loop through all the channels to display the details for (Trace trace : traces) { System.out.printf("Found %2s-%5s (%2s) from %15s to %15s\n", trace.getNetwork(),trace.getStation(),trace.getChannel(), trace.getStartTime().toString(), trace.getEndTime().toString()); System.out.printf(" This trace has %d samples, at %7.2f samples per second\n", trace.getSampleCount(), trace.getSampleRate()); System.out.printf(" This channel is located at: %8.4f lat, %8.4f lon, elev %.0f m\n\n", trace.getLatitude(), trace.getLongitude(), trace.getElevation()); }
Expected Output from the TRACE tutorial ¶
Found IU- ANMO (BHZ) from 2006-09-10 17:00:00.0358 to 2006-09-10 17:01:44.9858 This trace has 2100 samples, at 20.00 samples per second This channel is located at: 34.9460 lat, -106.4571 lon, elev 1671 m
Found IU- ANTO (BHZ) from 2006-09-10 17:00:00.0108 to 2006-09-10 17:01:44.96084 This trace has 2100 samples, at 20.00 samples per second This channel is located at: 39.8680 lat, 32.7934 lon, elev 895 m
Found IU- BBSR (BHZ) from 2006-09-10 17:00:00.0346 to 2006-09-10 17:01:44.984678 This trace has 2100 samples, at 20.00 samples per second This channel is located at: 32.3713 lat, -64.6963 lon, elev -1 m
Found IU- BILL (BHZ) from 2006-09-10 17:00:00.0485 to 2006-09-10 17:01:44.9985 This trace has 2100 samples, at 20.00 samples per second This channel is located at: 68.0653 lat, 166.4531 lon, elev 320 m
Download the complete .java file for this example.
Working Tutorial: Importing and printing Station metadata
Initialize the services ¶
The following example uses the ServiceUtil class to initialize (get an instance of) the StationService. This code, and all of this example’s following code, would go within the main function of the bare bones outline.
ServiceUtil serviceUtil = ServiceUtil.getInstance(); serviceUtil.setAppName("Tutorials"); StationService stationService = serviceUtil.getStationService();
Specify the Criteria (narrow your search) ¶
This example fetches the metadata from station ANMO in the IU network, valid from 1993 through 2001.
// define the dates of interest</span> DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd"); dfm.setTimeZone(TimeZone.getTimeZone("GMT")); // Date startDate = dfm.parse("1993-01-01"); Date endDate = dfm.parse("2002-01-01"); // // specify the search criteria</span> StationCriteria stationCriteria = new StationCriteria(); stationCriteria = stationCriteria.addNetwork("IU").addStation("ANMO"). setStartAfter(startdate).setEndBefore(enddate);
Criteria names are generally based upon the parameters that are used within each webservice. Since each webservice has a different set of search parameters, each webservice will have its own criteria class (e.g. StationService accepts StationCriteria as input, while EventService accepts EventCriteria).
Empty Criteria objects ¶
A criteria object with no specified parameters will result in a search with no constraints, and may result in vast amounts of information being transferred.
Wildcards ¶
Certain parameters support wildcards (* or ?) or lists (station1, station2, …). StationCriteria parameters that accept these include addNetwork, addStation, addLocation, and addChannel.
Parameter Naming Conventions ¶
- addParametername
can be used to grow a list of criteria, with each subsequent call adding another possibility. For example, to return station results for both the IU and AV networks, you might use the following stationCriteria:
sc = stationCriteria.addNetwork("IU").addNetwork("AV");
which is equivalent to…
sc = stationCriteria.addNetwork("IU"); sc = sc.addNetwork("AV");
- setSomething
will change the value of that particular criteria. Subsequent calls will replace the value. For example:
sc = stationCriteria.setSomething(whatever);
Additional calls to setSomething would merely replace this choice.
For additional detail about specifying station search criteria, consult the StationCriteria class within the Java Doc.
Fetch the results ¶
Now we use the stationcriteria to fetch a list of Network objects from the station webservice. Each network object may contain the detail for stations within it. We’ll also specify the level of detail to fetch by using the java enum OutputLevel.
// fetch the data from the service, using the stationCriteria // The fdsn-station service can be queried for different levels of detail. // We're asking for CHANNEL detail, but could have chosen STATION or NETWORK, too. // List<Network> ls = stationService.fetch(stationCriteria, OutputLevel.CHANNEL);
Display the results ¶
The StationXML is nested according to network, station and channel. Therefore, we will loop through this hierarchy to display the results.
// loop through all the channels to display the details for (Network n : ls) { System.out.printf("Network : %s with %d stations\n", n.getCode(), n.getSelectedNumberStations()); // each network may have multiple stations for (Station s : n.getStations()) { System.out.printf("\tStation : %s with %d channels\n", s.getCode(), s.getChannels().size()); for (Channel c : s.getChannels()) { // Finally! Print the detail System.out.printf("\t\tChannel: %s on: %s off:%s\n", c.getCode(), c.getStartDate(), c.getEndDate()); } } }
Expected Output from the Station tutorial ¶
Network : IU with 1 stations Station : ANMO with 172 channels Channel: LDO on: 2000-08-16T14:00:00 off:2000-10-19T16:00:00 Channel: BH1 on: 2000-07-19T14:00:00 off:2000-10-19T16:00:00 Channel: BH2 on: 2000-07-19T14:00:00 off:2000-10-19T16:00:00 Channel: BHZ on: 2000-07-19T14:00:00 off:2000-10-19T16:00:00 Channel: HH1 on: 2000-07-19T14:00:00 off:2000-10-19T16:00:00 Channel: HH2 on: 2000-07-19T14:00:00 off:2000-10-19T16:00:00 ...<i><b>continued</b></i>
Working Tutorial: Importing and displaying Event information
In this example, we’ll flesh out the The Bare Bones Outline’s main function in order to fetch and display some event information.
Initialize the services ¶
ServiceUtil serviceUtil = ServiceUtil.getInstance(); serviceUtil.setAppName("Tutorials"); EventService eventService = serviceUtil.getEventService();
Specify the Criteria ¶
In this example, we’ll fetch all events that are in the IRIS database that have occurred between 44.8 and 45.0 degrees Latitude and have a mangnitude of 5.0 or greater.
// we aren't concerned with a date range in this example, // but we COULD have specified a range as seen in the previous examples</span> EventCriteria criteria = new EventCriteria(); criteria.setMaximumLatitude(45.0); criteria.setMinimumLatitude(44.8); criteria.setMinimumMagnitude(5.0);
A great many selection criteria are available, and reflect the parameters seen in the fdsn-event service. For more thorough listing of available parameters, consult the EventCriteria class within the Java Doc.
Fetch the results ¶
Once again, the Service’s fetch routine is used.
// get a list of Event objects List<Event> events = eventService.fetch(criteria);
Display the results ¶
for (Event e : events) { System.out.println("Event: " + e.getType() + " " + e.getFlinnEngdahlRegionName()); System.out.println("\t"+e.getPreferredOrigin()); for(Magnitude magnitude:e.getMagnitudes()){ System.out.printf("\tMag: %3.1f %s\n", magnitude.getValue(), magnitude.getType()); } }
Output from the Event tutorial ¶
Because the criteria for this search did not specify a date range, the output may be preceded by additional events.
Event: earthquake EAST OF KURIL ISLANDS Origin [publicId=smi:www.iris.edu/ws/event/query?originId=7636191, latitude=44.817, longitude=150.086, depth=40.2, time=Fri Feb 18 20:20:30 PST 2011] Mag: 5.4 MB Event: earthquake KURIL ISLANDS Origin [publicId=smi:www.iris.edu/ws/event/query?originId=5194528, latitude=44.857, longitude=147.973, depth=97.9, time=Sat Jul 25 11:32:22 PDT 2009] Mag: 5.1 MB Mag: 5.0 MW Event: earthquake KURIL ISLANDS Origin [publicId=smi:www.iris.edu/ws/event/query?originId=5192839, latitude=44.978, longitude=148.151, depth=93.9, time=Wed Jun 10 15:54:55 PDT 2009] Mag: 5.0 MB Event: earthquake EAST OF KURIL ISLANDS ...<i><b>continued</b></i>
Working Tutorial: Importing and displaying Waveform information
In this example, we’ll flesh out the Bare Bones Outline’s main function in order to fetch and display some waveform information.
Initialize the services ¶
ServiceUtil serviceUtil = ServiceUtil.getInstance(); serviceUtil.setAppName("Tutorials"); WaveformService waveformService = serviceUtil.getWaveformService();
Specify the Criteria ¶
In this example, we take advantage of the WaveformCriteria’s helper function that allows us to specify (in one place) a network, station, channel, location, starttime, and endtime.
// We're specifying the BulkDataRequest equivalent of: // IU ANMO 00 BHZ 2006-09-11T00:00:00 2006-09-11T00:01:00 // define the dates of interest DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss"); dfm.setTimeZone(TimeZone.getTimeZone("GMT")); Date startDate = dfm.parse("2006-09-11T00:00:00"); Date endDate = dfm.parse("2006-09-11T00:01:00"); WaveformCriteria criteria = new WaveformCriteria(); criteria.add("IU", "ANMO", "00", "BHZ", startDate, endDate); // to request additional data, we coulld use more criteria.add(...) statements
Parameter limits and usage are dictated by the fdsn-dataselect service unless otherwise noted. Empty WaveformCriteria objects are not allowed. For additional detail about working with the waveform criteria webservice, consult the WaveformCriteria class within the Java Doc.
Fetch the results ¶
Once again, the retrieval is straight forward. Simply call the service’s FETCH routine, providing it with the search criteria. The results will be returned in a list of Timeseries objects
// get a list of Timeseries objects List<Timeseries> timeSeriesCollection = waveformService.fetch(criteria);
Converted SEED data is available in two classes ¶
Requests convert the returned SEED data, such that it will be available in two classes Timeseries and Segment.
- Timeseries
- The Timeseries class organizes data into unique channels according to the SEED format nomenclature.
- Segment
- The Segment class is used to contain a contiguous segment of time series data, collections of Segments are associated with each Timeseries
Display the results ¶
Display all the location information as well as the sample count and start-time of the retrieved segments
for(Timeseries timeseries:timeSeriesCollection){ System.out.println(timeseries.getNetworkCode() + "-" + timeseries.getStationCode() + " (" + timeseries.getChannelCode() + "), loc:" + timeseries.getLocation()); for(Segment segment:timeseries.getSegments()){ System.out.printf("Segment:\n"); System.out.printf(" Start: %s", segment.getStartTime()); System.out.printf(" %d samples exist in this segment\n", segment.getSampleCount()); } }
Output from the WAVEFORM tutorial ¶
IU-ANMO (BHZ), loc:00 Segment: Start: 2006-09-10 17:00:00.0358 1200 samples exist in this segment IU-ANMO (BHZ), loc:10 Segment: Start: 2006-09-10 17:00:00.0233 2400 samples exist in this segment
Working Tutorial: Importing stations and printing in Resp format
Initialize the services ¶
The following example uses the ServiceUtil class to initialize (get an instance of) the StationService. This code, and all of this example’s following code, would go within the main function of the bare bones outline.
ServiceUtil serviceUtil = ServiceUtil.getInstance(); serviceUtil.setAppName("Tutorials"); StationService stationService = serviceUtil.getStationService();
Specify the Criteria (narrow your search) ¶
This example fetches the metadata from station ANMO in the IU network, valid from 1993 through 2001.
// define the dates of interest</span> DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd"); dfm.setTimeZone(TimeZone.getTimeZone("GMT")); // Date startDate = dfm.parse("1998-10-26"); Date endDate = dfm.parse("1998-10-27"); // // specify the search criteria</span> StationCriteria stationCriteria = new StationCriteria(); stationCriteria = stationCriteria.addNetwork("IU").addStation("ANMO").addLocation("00"). setStartAfter(startDate).setEndBefore(endDate);
Fetch the results ¶
// fetch the data from the service, using the stationCriteria // The fdsn-station service can be queried for different levels of detail. // We're asking for CHANNEL detail, but could have chosen STATION or NETWORK, too. // List<Network> ls = stationService.fetch(stationCriteria, OutputLevel.RESPONSE);
Print the results ¶
RespUtil.write(System.out, ls);
Output from the RESP tutorial ¶
B050F03 Station: ANMO B050F16 Network: IU B052F03 Location: 00 B052F04 Channel: BHZ B052F22 Start date: 1998,299,20:00:00 B052F23 End date: 2000,293,16:00:00 # # +-----------------------------------+ # | Response (Poles and Zeros) | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B053F03 Transfer function type: A B053F04 Stage sequence number: 1 B053F05 Response in units lookup: M/S - Velocity in Meters Per Second B053F06 Response out units lookup: V - Volts B053F07 A0 normalization factor: +8.60830E+04 B053F08 Normalization frequency: +2.00000E-02 B053F09 Number of zeroes: 2 B053F14 Number of poles: 5 # Complex zeroes: # i real imag real_error imag_error B053F10-13 0 +0.00000E+00 +0.00000E+00 +0.00000E+00 +0.00000E+00 B053F10-13 1 +0.00000E+00 +0.00000E+00 +0.00000E+00 +0.00000E+00 # Complex poles: # i real imag real_error imag_error B053F15-18 2 -5.94313E+01 +0.00000E+00 +0.00000E+00 +0.00000E+00 B053F15-18 3 -2.27121E+01 +2.71065E+01 +0.00000E+00 +0.00000E+00 B053F15-18 4 -2.27121E+01 -2.71065E+01 +0.00000E+00 +0.00000E+00 B053F15-18 5 -4.80040E-03 +0.00000E+00 +0.00000E+00 +0.00000E+00 B053F15-18 6 -7.31990E-02 +0.00000E+00 +0.00000E+00 +0.00000E+00 # # +-----------------------------------+ # | Channel Sensitivity/Gain | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B058F03 Stage sequence number: 1 B058F04 Sensitivity: +2.06168E+03 B058F05 Frequency of sensitivity: +2.00000E-02 B058F06 Number of calibrations: 0 # # +-----------------------------------+ # | Response (Coefficients) | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B054F03 Transfer function type: D B054F04 Stage sequence number: 2 B054F05 Response in units lookup: V - Volts B054F06 Response out units lookup: COUNTS - Digital Counts B054F07 Number of numerators: 0 B054F10 Number of denominators: 0 # # +-----------------------------------+ # | Decimation | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B057F03 Stage sequence number: 2 B057F04 Input sample rate (HZ): 5.1200E+03 B057F05 Decimation factor: 00001 B057F06 Decimation offset: 00000 B057F07 Estimated delay (seconds): +0.0000E+00 B057F08 Correction applied (seconds): +0.0000E+00 # # +-----------------------------------+ # | Channel Sensitivity/Gain | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B058F03 Stage sequence number: 2 B058F04 Sensitivity: +4.19430E+05 B058F05 Frequency of sensitivity: +0.00000E+00 B058F06 Number of calibrations: 0 # # +-----------------------------------+ # | Response (Coefficients) | # | IU ANMO 00 BHZ | # | 10/26/1998 to 10/19/2000 | # +-----------------------------------+ # B054F03 Transfer function type: D B054F04 Stage sequence number: 3 B054F05 Response in units lookup: COUNTS - Digital Counts B054F06 Response out units lookup: COUNTS - Digital Counts B054F07 Number of numerators: 64 B054F10 Number of denominators: 0 # Numerator coefficients: # i coefficient error B054F08-09 0 -1.09707E-03 +0.00000E+00 B054F08-09 1 -9.93327E-04 +0.00000E+00 B054F08-09 2 -1.33316E-03 +0.00000E+00 B054F08-09 3 -1.70526E-03 +0.00000E+00 B054F08-09 4 -2.05384E-03 +0.00000E+00 B054F08-09 5 -2.35065E-03 +0.00000E+00 B054F08-09 6 -2.57156E-03 +0.00000E+00 B054F08-09 7 -2.69373E-03 +0.00000E+00 B054F08-09 8 -2.69337E-03 +0.00000E+00 B054F08-09 9 -2.54709E-03 +0.00000E+00 B054F08-09 10 -2.23115E-03 +0.00000E+00 B054F08-09 11 -1.72301E-03 +0.00000E+00 B054F08-09 12 -9.99270E-04 +0.00000E+00 B054F08-09 13 -3.46562E-05 +0.00000E+00 B054F08-09 14 +1.21980E-03 +0.00000E+00 ......
Categories
Release date: Modified date: