The scnlobject class - geoscience-community-codes/GISMO GitHub Wiki

The scnlobject class was created to simplify handling station, channel, network, and location information. Though not required in all situations, the four-parameter SEED naming convention is now nearly ubiquitous in earthquake seismology. Each scnlobject represents a single sta_chan_net_loc combination (Ahern et al. 2009). Encapsulating these descriptors into a dedicated object improves the management of large numbers of traces by facilitating single-command subsets, concatenations, and queries against waveform objects. Commonly accessed scnlobjects can be stored for automatic retrieval, so that they are not required to be created manually each time. Scnlobjects understand “*” wildcards, further improving the ability to sift through large numbers of traces for desired information.

The scnlobject class is the most basic waveform suite class. The scnlobject class was added to the waveform suite in spring 2009 to handle the labeling of data. It contains the station, channel, network, and location names associated with the time-series data. Scnlobjects play a critical role in being able to query for the data recorded at various locations.

When scnlobject was created, we dealt with data from a single network, and rarely used location codes. Therefore, the emphasis was on stations and channels. However, as data from many networks are becoming easier to combine, (for example, by accessing data from IRIS), it has become apparent that all four descriptor fields need to be used in order to accurately describe your channel. The replacement for scnlobject, channeltag takes this change to heart, and treats them hierarchically.

There are three main advantages to using scnlobjects:

scnlobjects are easily combined
commonly accessed station-channel-network-locations can be stored for automatic retrieval
scnlobjects are easily compared

Creating a scnlobject

An array of one or more scnlobjects will be returned by a scnlobject, depending upon the input values. Each scnlobject represents a single station-channel-network-location combination. Providing a cell array of possible stations with a single channel will create one scnlobject for each station, all of which will have the same channel. Likewise, providing a single station, along with multiple channels will generate a series of scnlobjects for that station, each with that channel. Finally, providing cell arrays of equal lengths for the stations and channels will generate an array of scnlobjects where each station is paired with the corresponding channel.

scnl = scnlobject(station, channel [, network[, location]])
Create a scnlobject. stations and channels may be cell arrays, so that multiple scnlobjects are created simultaniously. the network and location fields are optional.
scnl = scnlobject('OKCF','EHZ','AV','1')
creates a single scnl for this station/channel combo. In this case, a network AV and a location '1' have been assigned as well. The network and location parameters are optional, though.
scnl = scnlobject({'RED','REF'},'EHZ')
create multiple scnlobjects (1x2), one for each station, and assign the same channel to all. A single channel can be assigned to any number of stations.
scnl = scnlobject('OKCE',{'BHZ','BHE','BHN'})
Create an 1x3 scnlobject for station OKCE, with each channel represented. Any number of channels can be assigned to a single station. scnl = scnlobject({'OKCE','OKER','OKSO'},{'BHZ','EHZ','BHZ'}) Create an 1x3 scnlobject, assigning the station-channel pair to each one. In this example the pairs become: OKCE:BHZ, OKER:EHZ, OKSO:BHZ. This works for any number of station-channel pairs

s = scnlobject()
create a default scnlobject. The station and channel will be blank, while the network and location will contain '--'. Using WILDCARDS in SCNLOBJECTS

By entering an asterisk in any field (ie, set(scnl,'station','*'); ) that field is set to a wildcard and will not be used for any search criteria. One particularly useful application of the scnlobject wildcard is when querying a datafile for any /all data contained within it.

Accessing

To retrieve information from scnlobjects, use the get method. Valid properties to ask for are:'station', 'channel', 'network', and 'location'.

value = get(SCNLobject, 'PropertyToGet')

For a single scnlobject, the get method will return a string with the requested property. For multiple scnlobjects, get will return a cell array with the requested information.

>>scnl = scnlobject('ABC','EHZ','AV','1');
get(scnl,'station');

ans =

  ABC

>>scnl = scnlobject('ABC',{'BHZ','BHN','BHE'},'AV','1');
get(scnl,'channel');

ans =

  'BHZ'   'BHN'   'BHE'

Making direct changes to your scnlobject

Using set, you can change the values of your scnlobject. The general form of set is:

modifiedSCNL = set(originalSCNL, 'PropertyToChange', newValue)

If originalSCNL contains an array of scnlobjects, then that property is changed for all scnls. Remember, the originalSCNL is unchanged until the result is assigned to it.

Additional functions of note

Here are additional functions to be aware of:

uniquescnls = unique(scnlobjects) Return an array of unique scnlobjects from a list. That is, remove duplicate scnlobjects. [tf loc]= ismember(object, scnlobjectlist) returns true if that object (scnlobject or waveform) is a member of the scnlobject list. wildcards in individual fields of the scnlobjectlist will mean that that particular field will not be used as a criterion.

Examples

Create a bunch of scnls

A script creating commonly used scnls

% commonly used scnls: station_setup.m

% short period stas for Augustine volcano
scnls.augustine = scnlobject({'AUE','AUP','AUI','AUW','AU13'},'EHZ','AV');

% short period stations for Okmok volcano
scnls.okmok.sp = scnlobject(...
  {'OKCF','OKER','OKTU','OKRE','OKSP','OKWE','OKWR'},'EHZ','AV');

% broadband stations for Okmok volcano
tmp = scnlobject({'OKSO','OKFG','OKCE'},'BHZ','AV');
scnls.okmok.bb = [tmp, set(tmp,'channel','BHN'), set(tmp,'channel','BHE')];

% add a station with all sorts of data channels

scnls.superstation=scnlobject('CGR1',{'BHZ','BHE','BHN','LHZ','BDF'},'AV');

and here's an example matlab session that uses scnls...

load('station_setup.m');
% - the variables scnl and tmp are loaded into matlab

ds = datasource('file',...
'C:/mydatafiles/%04d/%s%03d.mat','year','station','jday') % working with existing waveforms, stored locally in .mat files
% - notice the filename depends on the station, year and julian day.
%   The datasource declaration, too, could have been loaded from a script

ds =
type: FILE
location: C:/mydatafile/[YEAR]/[STATION][JDAY].mat

w = waveform(ds,scnls.augustine,'2/5/2009','2/6/2009') % load Augustine waves

w = 1 x 5 wavform object 
% --details of waveform displayed here--

stanums = 1:25; % load 25 stations that have numerical names
stanames = strcat('STA',num2str(stanums,'%02d')); % change numbers into names like "STA03"
scnl = scnlobject(stanames,'LL'); % create 1x25 station/channel list
w = waveform(ds,scnl,'2/5/2009 02:00', 2/9/2009 14:00) % load all stations for this 4.5-day period

w = 1 x 25 waveform object 
% --details of waveform displayed here--

External Links

Here is an old cookbook for scnlobjects, hosted at the University of Alaska Faribanks Geophysical Institute Seismology Lab. scnlobject cookbook

This page has been ported with edits from http://kiska.giseis.alaska.edu/input/celso/matlabweb/waveform_suite/scnlobject.html