Seamless access to data and information from within MATLAB

 
icon

Data from the IRIS-DMC can be retrieved from within MATLAB

Waveform data, event metadata, and station metadata from the IRIS-DMC are now directly accessible from within MATLAB (R2009b and later). The IRIS-WS Java library provides the connectivity for programs such as irisFetch.m and the Waveform Suite, which access data directly from the DMC. No Java knowledge is required.

The sections below explain how to obtain and install the IRIS-WS library, and then how to use one of these methods to access DMC-held data. Additional files may need to be obtained, but these are also detailed in the examples.

Installing the IRIS-WS jar file

No matter which method you intend to use, the inital step will be to retrieve the latest IRIS-WS java JAR file and make it available to MATLAB.

  1. Obtain the most recent IRIS-WS JAR file (go to the download page).
  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.

After installing, the next step is to access the data. Two ways to do this include:

Using irisFetch.m to access IRIS-DMC data

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

This example retrieves seismic traces for the various channels of station ANMO from the IU network, and then plots the resulting waveform(s). By specifying channels and times, one can use irisFetch.Traces() to retrieve one or more seismic traces into native MATLAB data types.

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

Example Code

					 
% make sure the java jar is in the path, this need only be done once per MATLAB session
javaaddpath('IRIS-WS-1.5.jar'); % or equivalent

% Fetch data form IRIS
%   args: Net, Sta, Loc, Cha, Starttime, Endtime [,quality][,includePZ][,verbosity]
mytrace=irisFetch.Traces('IU','ANMO','*','?HZ','2010-02-27 06:30:00',...
        '2010-02-27 07:30:00','includePZ')

% process the data : for example, plot it
% simple example: plot first trace
trace1 = mytrace(1);
sampletimes=linspace(trace1.startTime,trace1.endTime,trace1.sampleCount);
plot(sampletimes,trace1.data);
datetick;

Which generates:

simple graph of a single ANMO channel

That's all there is to it. The following example should give some additional insight into dealing with returned data.

					 
%% Here is a more exhaustive example:  plot and label all traces in time
% This is capable of plotting traces with differing samplerates and trace lengths

data = [];        % each column will contain a different trace's data
sampletimes = []; % sampletime(x,y) contains the corresponding sample time for data(x,y)

for n=1:numel(mytrace)
  thistrace = mytrace(n);
  nSamples = thistrace.sampleCount;

  % scale, and then copy into the nth column of array data after scaling
  data(1:thistrace.sampleCount,n)=thistrace.data ./ thistrace.sensitivity; 

  % fill sampletimes with evenly-spaced times spanning from startTime to endTime
  sampletimes(1:nSamples,n)= linspace(thistrace.startTime,thistrace.endTime,nSamples);
end

sampletimes(sampletimes==0)=nan; % keep padded values from plotting

plot(sampletimes,data);

% make it pretty
datetick;
ylabel(thistrace.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:

output a labeled graph of several ANMO channels

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: nobody@iris.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'})

Using the Waveform Suite to access IRIS-DMC data

A new datasource type has been added to the Waveform Suite. The type 'irisdmcws' provides an interface into the IRIS-DMC data archives in a seamless way as the rest of the Waveform Suite's datasources.

Setting up

  1. Retrieve and install the IRIS-WS jar file, as described above
  2. Obtain r336 or later of gismotools or the Waveform Suite from either the google code site or from Mathworks.
  3. Set MATLAB's search path to recognize the Waveform Suite

Example code

					 
% make sure the java jar is in the path, this need only be done once per MATLAB session
javaaddpath('IRIS-WS-1.5.jar'); % or equivalent

% create the datasource
ds = datasource('irisdmcws')

% create the criteria
scnl = scnlobject('ANMO', '?HZ', 'IU', '*')

% fetch the data
w = waveform(ds, scnl, '2010-02-27 06:30:00','2010-02-27 07:30:00')

% process the data : for example, plot it
%  this is more-or-less equivalent to the most exhaustive example above
plot(w,'xunit','date'); %plot all waveforms
legend(w,'channel','location');

Which generates:

output graph of ANMO channels using the Waveform Suite

Retrieving data from the IRIS-DMC through the use of Java classes

MATLAB is capable of running java methods. All that is required is that the IRIS-WS jar file be downloaded, and added to the MATLAB javaclasspath. See the installation instructions (top), or consult MATLAB's extensive help files to see about permanently adding the jar to your java class path.

Consult the java tutorial pages for a more detailed overview of using the provided classes.