This documentation has not been updated since 2011. The Waveform Suite no longer exists as an independent project. Instead it is a key component of GISMO. Visit the GISMO site on github.com to access the latest documentation on The Waveform Suite and to download the current version.

Welcome to the online documentation and tutorial pages for the waveform suite for MATLAB!

Within these pages you'll find information to get you up and running with the waveform suite. The waveform suite is a collection of matlab classes that work together to speed up and simplify the import and manipulation of time-series data. Originally conceived to manipulate seismic data, it may be applied to any regularly sampled time-series data that is associated with a location.

The waveform object:

  • makes playing with data easier by automating the tedious aspects of data manipulation
  • makes programs more stable by ensuring proper data typing
  • makes code more portable by reading multiple formats and functioning on multiple systems
  • makes troubleshooting faster by providing more detailed messages and warnings

The README can be found on my downloads page.

Creating a Waveform

Generic information about the waveform constructor class

w = waveform
creates a blank waveform. You get a waveform with a blank station and channel, and a location and network of '--', a frequency of NaN Hz, and a start time equal to antelope's default start time '1/1/1970 00:00:00'. Changing any or all of this waveform's information can be done through the set function.
w = waveform(station, component, freq, start, data)
manually puts together a waveform object using each of these specified values. This is designed to allow you to create a waveform based on data from other places or from data that you've conjured up yourself. Additional values can be added/changed through the set function.
w =waveform(datasource, scnlobject, startTime,endTime)
Retrieves waveform(s) from the selected datasource, returning all waveforms that are described by the scnlobject list (ie, matching the correct station/channel/network/location parameters), for the times requested. The datasource object allows waveform to retrieve from any one of a number of sources: Antelope or Winston databases, SAC or SEISAN files, or even waveforms saved as .mat files.

What, exactly, is in a waveform object?

The beauty of object-oriented program is that it really doesn't matter how the information is stored, so long as it is accessible in a standard way

A waveform object contains only the following information:

You can use the struct(waveform) command to return the absolutely raw data and see for yourself... struct returns a structure based on the listed object.

However, much more information can be asked of it via the waveform/get routine.

Accessing

To retrieve information from waveforms, use the get method.

value = get(SCNLobject, 'PropertyToGet')

Here is a sample of the types of data / derived data that can be retrieved;

for additional valid properties, type help waveform/get

For a single waveform, the get method will return the requested property . For multiple waveforms, get will return either a numeric or cell array with the requested information.

Making direct changes to your waveform

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

modifiedWave = set(originalWave, 'PropertyToChange', newValue)

If originalWave contains an array of waveforms, then that property is changed for all waveforms. Remember, the originalWave is unchanged until it is assigned the result.

Additional functions of note

Here are additional functions to be aware of:

Plot
plot one or more waveforms, labeling the graph as well as taking account of units
  1. h = plot(waveform)
    Plots a waveform object, handling the title and axis labeling. The output parameter h is optional. If used, the handle to the waveform plots will be returned. These can be used to change properties of the plotted waveforms.
  2. h = plot(waveform, ...)
    Plots a waveform object, passing additional parameters to matlab's PLOT routine.
  3. h = plot(waveform, 'xunit', xvalue, ...)
    sets the xunit property of the graph, which is used to determine how the times of the waveform are interpereted. Possible values for XVALUE are 'seconds', 'minutes', 'hours', 'days', 'day_of_year', 'date'. For multiple waveforms, specifying XUNITs of 'seconds', 'minutes', 'hours' will cause all the waveforms to be plotted starting at 0. An XUNIT of 'date' will force all waveforms to plot starting at their starttimes. the default XUNIT is seconds

For the following examples assume:

W is a 10-minute long waveform starting:04/02/2005 01:00:00
% W2 is a 1-minute long waveform (same station) starting: 04/02/2005 01:05:00

PLOT EXAMPLE 1:

This example plots the waveforms at their absolute times...

plot(W,'xunit','date');plots the waveform in blue
hold on;
h = plot(W2,'xunit','date', 'r', 'linewidth', 1);
%plots your other waveform in red, and with a wider line

PLOT EXAMPLE 2:

% This example plots the waveforms, starting at time 0

plot(W);plots the waveform in blue with seconds on the x axis
hold on;
plot(W2,'xunit','seconds', 'color', [.5 .5 .5]);plots your other

                                        % waveform, starting in unison
                                        % with the prev waveform, then
                                        % change the color of the new
                                        % plot to grey (RGB)

For a list of properties you can set (such as color, linestyle, etc...) type get(h) after plotting something.

Also, now Y can be autoscaled with the property pair: 'autoscale',true although it only works for single waveforms...

if the wave parameter is a vector of waveform objects, then plot will plot them all on the same axis, and to scale. You can also pass formatting comands to the plot function.

h = plot(wave,'xunit','date', 'r.-', 'linewidth', 1);

This plots your other waveform in a red dash-dotted line, and makes the line thicker.

demean

remove the voltage offset from the data. This basically just subtracts the mean of the data. One nice feature is that this is designed to work with arrays of waveform objects.

fixedWave = demean(VNSS20050403PMwave);

mean

figures out the average (mean) of the waveform's data, then returns that value as a scalar.

avgVoltageOffset = demean (mySampleWave);

You can also pass this function an array of waveforms, and it will return a same-shaped array of mean values.

hilbertHilbert Example
returns the real part of a hilbert transform based on the waveform's data.
This is great for generating envelopes.

hilbert_envelope = hilbert(mySampleWave);

stack
combines waveforms. If you have waveform objects with similar sample rates and durations, you can stack their waveforms.

This clones the first waveform in the array, (station ID, start time, etc) and then sums the data from each of the included waveforms. This does no error checking, so it will crash if your arrays don't overlap. You'll definitely want to change the header information for the waveform using the get command after successfully stacking things, so that it becomes obvious that the data is stacked.

In this example, veni1 .. veni4 are waveform objects

w = [veni1 veni2 veni3 veni4];
mystack = stack(w);
mystack = set(mystack,'STATION','VNSS_Stack');

extract
returns a waveform consisting of a subset of data from within another waveform array.

Let's start with a waveform that was loaded like so:

bigWave = waveform('OKCF','SHZ','10/5/2005 12:00','10/5/2005 24:00');

Twelve hours of data... that's an awful big wave to have to deal with, especially at a 100Hz sample rate. Maybe I'd like to work with the 14:00 - 15:00 subsection... You could go back to the database and reload. But, maybe you've done some funky filtering or something else that you don't want to have to repeat. Here are two ways to do that:

subWave = extract(bigWave,'TIME','10/5/2005/14:00','10/5/2005 15:00');

subWave = extract (bigWave,'Index&Duration', 100 * 60 * 60 * 2, '1:00');

Where 100 * 60 * 60 * 2 is the expected offset of your second hour of data...

fix_data_length
sets the data from multiple waveforms to the same length, Several functions in matlab require using data of the same length, and this function will do that. By default, it will find the longest waveform, and then pad all the others with zero to make them match up.

myWaves = fix_data_length(myWaves);

Examples

Several examples can be checked out from