Software Downloads – irisFetch.m v. 2.0.6 – Manual

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'})

Working with SAC formatted data

The irisFetch library includes several methods (outlined below) to handle input and output of data formatted in Seismic Analysis Code (SAC). These methods currently only offer support for binary SAC files.

SAC files are written to disk using automatically generated filenames with the following general form: NN.SSSS.LL.CCC.YYYY.DDD.HH.MM.SS.SAC where NN, SSSS, LL, CCC represent the network, station, location, and channel codes, respectively, and the start time of the request is formatted as YYYY.DDD.HH.MM.SS where DDD is the calendar day of the year.

  • irisFetch.Traces – append the optional argument 'WRITESAC:/example/directory/' to a call to irisFetch.Traces to write seismic waveform and associated station metadata to a local directory specified by the string /example/directory/.
>> mytrace=irisFetch.Traces('IU','ANMO','*','*Z','2010-02-27 06:30:00','2010-02-27 07:30:00','WRITESAC:/example/directory/')
  • irisFetch.SACfiles – usage is similar to irisFetch.Traces but this method will write waveform data directly to disk without first storing data in Matlab memory.
>> irisFetch.SACfiles('IU','ANMO','*','*Z','2010-02-27 06:30:00','2010-02-27 07:30:00','/example/directory/')
  • irisFetch.SAC2Trace and irisFetch.Trace2SAC – these complementary functions allow users to easily translate between data stored in Matlab as Trace structures and binary SAC files.
>> mytrace=irisFetch.SAC2Trace('/example/directory/')
>> irisFetch.Trace2SAC(mytrace,'/example/directory/')

Retrieving data from global FDSN data centers and the IRIS Federator

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.

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/')

If the target datacenter is unknown, users may use the IRIS Federator to retrieve waveform data from other data centers. This is accomplished by adding the optional argument 'federated' to a call to irisFetch.Traces method.

>> mytrace = irisFetch.Traces('AK,BK','*','*','BHZ','2004-01-01 00:00:00','2004-01-02 00:00:00','federated')

Potential memory issue

When requesting relatively high volumes of time series data, the IRIS-WS Java library may run out of available heap memory within the MATLAB environment. This can result in empty structures being returned to the MATLAB workspace.

To alleviate this issue, the amount of heap memory available in the Java environment within MATLAB can be increased. To change this setting in MATLAB 2014 versions go to your “Preferences” menu, click on “General”, then click on “Java Heap Memory” (the setting may be in different locations depending on your version of MATLAB). By default, MATLAB will set the amount of available heap memory to 512 MB, but we recommend increasing this to 1,024 MB if you are encountering issues with empty structures.

NOTE: Sometimes this out of memory error does not produce an obvious diagnostic message and may fail “silently” within your MATLAB program.