Manuals: irisFetch.m

NAME

irisFetch.m – provides a MATLAB (MATrix LABoratory) interface to the IRIS archive.

SUMMARY

The Matlab library IRISFETCH allows seamless access to data stored within the IRIS-DMC as well as other data centers that implement FDSN web services. irisFetch.m provides a thoroughly documented collection of routines that allow access to:

  • seismic trace data, containing information akin to a basic SAC file
  • station metadata, providing details ranging from the network through response level
  • event parameters, including magnitudes locations, and picks

All retrieved data is converted into structs for use in MATLAB scripts.

DESCRIPTION

Available irisFetch methods (functions)

irisFetch allows seamless access to data stored within the IRIS-DMC via FDSN services

  • irisFetch waveform retrieval Methods:
    • Traces – retrieve sac-equivalent waveforms with channel metadata
  • irisFetch FDSN station webservice Methods:
    • Channels – retrieve metadata as an array of channels
    • Stations – retrieve metadata as an array of stations
    • Networks – retrieve metadata as an array of networks
  • irisFetch FDSN event webservice Methods:
    • Events – retrieve events parameters (such as origins and magnitudes) from a catalog
  • irisFetch miscelleneous Methods:
    • Resp – retrive RESP formatted response data from the irisws-resp service
    • version- display the current version number
    • connectToJar – attempt to connect to the required IRIS-WS JAR file
    • runExamples – displays and runs some sample queries to the web service.

Installing the IRIS-WS jar file

irisFetch requires a Java JAR file (IRIS-WS.jar) to communicate with the FDSN web services. Therefore, before using irisFetch, retrieve the latest IRIS-WS java JAR file and make it available to MATLAB.

  1. Obtain the most recent IRIS-WS-2.0.x.jar file (go to the download area).
  2. Add the jar to MATLAB’s java class path (e.g., using javaaddpath('jar_filename') ). Hint: Adding the javaaddpath command to MATLAB’s startup.m file will cause it to be automatically loaded each time MATLAB starts.

If the jar file is not on your computer and in matlab’s javaclasspath, then irisFetch will attempt to locate a suitable version online and use it remotely. It is highly recommended, though, that the IRIS-WS jar file be installed locally.

Setting up

  1. Retrieve and install the IRIS-WS jar file, as described above
  2. Download the irisFetch.m file, placing it somewhere along your MATLAB search path

EXAMPLES

Trace Examples

Retrieve a trace, and then plot it

% make sure the java jar is in the path, this need only be done once per MATLAB session
javaaddpath('IRIS-WS-2.0.0.jar'); % or later version
% Fetch data form IRIS
%   args: Net, Sta, Loc, Cha, Starttime, Endtime [,quality][,includePZ][,verbosity]
mytrace=irisFetch.Traces('IU','ANMO','00','BHZ','2010-02-27 06:30:00', '2010-02-27 07:30:00')
% process the data : for example, plot it
sampletimes=linspace(mytrace.startTime,mytrace.endTime,mytrace.sampleCount);
plot(sampletimes,mytrace.data);
datetick;

Which generates:

Advanced plotting

The following example retrieves multiple traces and then plots them. It should give some additional insight into working with returned data.

% Here is a more exhaustive example:  plot and label all traces in time
mytrace=irisFetch.Traces('IU','ANMO','*','LHZ,BHZ,VHZ','2010-02-27 06:45:00','2010-02-27 07:35:00');
colors=brighten(lines(numel(mytrace)),-0.33); % define line colors
for n=1:numel(mytrace)
  tr = mytrace(n);
  data=double(tr.data) ./ tr.sensitivity;    % scale the data
  sampletimes = linspace(tr.startTime,tr.endTime,tr.sampleCount);
  plot(sampletimes, data, 'color', colors(n,:));
  hold on;
end
hold off;
datetick;
ylabel(tr.sensitivityUnits); % assumes all units are the same 
title(['UI-ANMO traces, starting ', datestr(mytrace(1).startTime)]); 
legend(strcat({mytrace.channel},'-',{mytrace.location}),'location','northwest');

Which generates:

Access to restricted data

Access to restricted data using irisFetch.Traces requires an additional parameter containing a username and password. These requests are authenticated via digest access authentication. For anonymous access, the user: nobodyiris.edu@ and password anonymous may be used.

The following example requests the exact same information as the example code above, but includes anonymous access authentication.

mytrace=irisFetch.Traces('IU','ANMO','*','?HZ','2010-02-27 06:30:00', '2010-02-27 07:30:00','includePZ', {'nobody@iris.edu', 'anonymous'})

Fetching data from other data centers

By default the Java IRIS WS library, and therefore the irisFetch library, will interact with web services at the IRIS DMC. The library can also be used to fetch data from other data centers with compatible web services. How to do this is documented in each method of the library and illustrated below.

To set the domain for all web service interfaces when using the Traces method simply add the new base URL as an argument. In this example the services at NCEDC are used:

mytrace=irisFetch.Traces('BK','HOPS','*','BHZ','2010-02-27 06:30:00','2010-02-27 07:30:00','http://service.ncedc.org')

The Traces method can interact with multiple web services depending on the options used, some data centers may not support all of these services. Chances are good that any data center supporting the fdsnws-dataselect service will also offer the fdsnws-station service, but it is less likely that they will support the IRIS-specific irisws-sacpz service and so you may find that the ‘includePZ’ option of the Traces method does not work in some cases.

To set the URL for service-specific methods such as a request for station metadata add ‘BASEURL’ followed by an alternate URL as arguments. In this example the NCEDC’s fdsnws-station service is explicitly identified:

mystations=irisFetch.Stations('CHANNEL','BK','HOPS','00','BHZ','BASEURL','http://service.ncedc.org/fdsnws/station/1/')

See Also

Release date:     Modified date: