FuncLab A MATLAB Interactive Toolbox For Handling
FuncLab A MATLAB Interactive Toolbox For Handling
FuncLab A MATLAB Interactive Toolbox For Handling
discussions, stats, and author profiles for this publication at: https://www.researchgate.net/publication/274246373
CITATIONS READS
16 244
2 authors:
Some of the authors of this publication are also working on these related projects:
All content following this page was uploaded by Matthew J. Fouch on 10 August 2016.
S E I S M O L O G I S T
Electronic Seismologist
FuncLab: A MATLAB Interactive Toolbox with receiver function data. We describe the structural build-
ing blocks that make FuncLab an efficient computational sys-
for Handling Receiver Function Datasets tem, features of the primary GUIs, and three additional mod-
ules for commonly employed analysis for regional network and
Kevin C. Eagar1,2 and Matthew J. Fouch1,3
single station studies.
INTRODUCTION OVERVIEW AND DATASET PREPARATION
Receiver functions have become a widely used tool to study
FuncLab is a data management system that works in the
the seismic velocity structure beneath a single station by imag-
MATLAB environment. It is a suite of tools designed to man-
ing impedance boundaries where mode conversions from P
age receiver function data and metadata, visually inspect indi-
to S waves occur. In recent years, the community has seen an
vidual receiver functions and seismograms for quality control,
increase in the amount of broadband seismic data available
and visualize the results of the quality-controlled data. The
through systems such as the IRIS Data Management Center
package also includes a number of add-on modules that handle
(IRIS DMC), requiring new approaches to managing and han-
post-processing analysis and stacking. We use this module-
dling large datasets in computationally efficient ways. Many
based approach to provide the opportunity for future develop-
receiver function studies have focused on tectonic and geody-
ment of new FuncLab add-ons by the community.
namic questions on regional scales of a few hundred square kilo-
Prior to using FuncLab, the user usually computes receiver
meters (e.g., Zandt et al. 1995; Sheehan et al. 1995; Dueker and
functions and performs signal processing functions, where the
Sheehan 1997). These studies typically have utilized data from
choice of parameters is completely user-dependent. Generally
temporary networks operating on time scales of a few months
speaking, a typical receiver function computation utilizes
to a few years. Others have concentrated on global trends, using
three-component broadband seismic data of a recorded earth-
data from increasing numbers stations that have operated for
years or decades (e.g., Andrews and Deuss 2008; Lawrence and
Shearer 2006; Tauzin et al. 2008). Over the last several years, 3000
the seismological community has seen a rapid increase in the
number of deployed passive broadband seismic stations and a
2500
resulting increase in data available for receiver function analysis.
Large initiatives such as EarthScope’s USArray Transportable
# BB Stations
Array enable immediate open access to data and have provided 2000
the community with an order of magnitude more data than in
the previous three decades (Figure 1) based on smaller regional
1500
temporary studies using data from IRIS PASSCAL-style field
experiments (e.g., Suckale et al. 2009; Wilson et al. 2005).
While the computation of receiver functions has been 1000
well studied and is a relatively straightforward and rapid pro-
cess, an efficient method to analyze and further evaluate very
500
large receiver function datasets is not widely available. In this
paper, we present an efficient workflow and MATLAB toolbox
for organizing receiver function data, which we call FuncLab. 0
FuncLab is a package of m-files (MATLAB scripts) written for 1985 1990 1995 2000 2005 2010
596 Seismological Research Letters Volume 83, Number 3 May/June 2012 doi: 10.1785/gssrl .83.3.596
quake in the range of 30°–95° distance from the station. The ferences in directory structure. No additional MATLAB tool-
horizontal recordings are rotated along the free surface to the boxes are required, but it is recommended that the Mapping
point in the radial and tangential directions from the backazi- Toolbox be installed in order to use all the plotting capabilities.
muth of the earthquake. A method of source normalization is The package contains a collection of m-files designed around
then performed by deconvolving the vertical seismogram from the concept of a project, or a complete dataset that can be pro-
the radial seismogram. The FuncLab package includes a set of cessed and analyzed collectively.
C-shell scripts that outline the basic preprocessing steps using A FuncLab project contains a set of related imported
the Seismic Analysis Code (SAC) and iterative deconvolution seismic data, files used to organize metadata and store proj-
receiver function computation using a Fortran 77 code devel- ect information, and other files created during data analyses.
oped and distributed by C. Ammon (Ligorria and Ammon Each project in FuncLab is housed in a separate directory with
1999) with parameters used for upper mantle and crustal stud- an organized structure created when the project is initiated.
ies of the Pacific Northwest (Eagar et al. 2010; 2011). FuncLab FuncLab is designed so that the main part of the program is
requires data in SAC format (Goldstein et al. 2003) and auto- responsible for managing the data and metadata within a proj-
matically handles little and big endian byte ordering of the ect and basic visualization of the dataset. Additional analytical
binary files. Currently, other data formats are not supported. tools are not contained in the main program, but instead are
Data must be organized in a formal directory structure incorporated as separate add-on modules that utilize conven-
before working with it in FuncLab. This structure was origi- tions specified in FuncLab to operate on the data.
nally used for data gathered using the Standing Order for
Data (SOD) data request tool (Owens et al. 2004), and there- Main FuncLab GUI
fore FuncLab was designed with this structure in mind. An Once receiver function data are organized with the FuncLab
example SOD recipe is also included on the FuncLab Web conventions described in the FuncLab User Manual, the user
site, http://geophysics.asu.edu/funclab. FuncLab also expects invokes the main FuncLab Graphical User Interface (GUI)
that the seismogram and receiver function files have a specific at the MATLAB command line using the funclab command.
naming convention, which partly arose from the original use The GUI is used from this point forward. The start of a new
of the iterative time-domain deconvolution code (Ligorria and project requires at least one directory containing data that has
Ammon 1999). The radial and transverse receiver functions, been preprocessed as described above and in the User Manual.
as well as the original vertical, radial, and transverse seismo- FuncLab automatically creates the project directory and struc-
grams, are needed to utilize the full functionality of the pack- ture while importing data directories to the project.
age. More details regarding proper setup of data directories and FuncLab saves the metadata for each station-earthquake
SAC file processing, including necessary header information, pair of waveform files in the Project.mat MAT-file. Metadata
can be found in the User Manual. for the records, such as station name, event origin time, time-
The IRIS Data Management Center (DMC) distrib- series sample rate, and SAC file pathname, are stored within
utes a data product providing fully automated computation this file. One of the most common limitations of the MATLAB
of receiver functions for all open broadband seismic stations environment is its inefficiency in storing large amounts of data
(http://www.iris.edu/dms/products/ears/). The purpose of the in memory, since heavy memory usage slows dramatically the
EarthScope Automated Receiver Survey (EARS) (Crotwell performance of computations. Instead of storing the seismic
and Owens 2005) is to provide automated analysis of bulk waveform data from an entire FuncLab project, we optimize
crustal properties using the well-established method of H-κ our algorithms by loading data only when needed for viewing
stacking (Zhu and Kanamori 2000). The DMC now includes or computation. This strategy significantly speeds up processes
a method for downloading all EARS receiver functions on a and enables the development of larger project datasets.
station-by-station basis. We provide a shell script to convert The main FuncLab GUI allows the user to interact with
EARS-formatted files and directory structure to a format read- the entire dataset (Figure 2). A drop-down menu defines the
able by FuncLab, allowing users easy access to receiver func- manner in which receiver function metadata is organized
tion data without computing the time series themselves. The for visualization in the GUI (we refer to these structures as
script includes instructions for direct download of EARS data. “tables,” although FuncLab is not a formal relational database
FuncLab therefore provides a straightforward application to management system). Records common to a particular sta-
customize receiver function analysis that leverages EARS data tion are viewed in “Station Tables.” The stations are then listed
products beyond the automated design of the EARS system. and selectable in the left-hand panel. The records within the
“Station Table” are listed by the event origin time in the cen-
TOOLBOX DESCRIPTION ter panel. The total number of records and number of active
records are listed below the panel. Metadata about the selected
This section describes aspects of the primary FuncLab data record in the center panel are then listed in the right-hand
management system. FuncLab is compatible with MATLAB panel. The user can also view the records organized by event
version 7.1.0.21 and above, but at the time of publication has origin by selecting the “Event Tables” in the drop-down menu.
not been tested beyond version 7.11 (R2010b). At present, Other options in the drop-down menu become available when
FuncLab is not compatible on Windows platforms given dif- using add-on analysis tools discussed below.
Trace Editor New data that have not yet been evaluated through the Trace
FuncLab provides the powerful aspect of organization and effi- Editor are colored red, while data previously viewed in the GUI
ciency through its ability to visualize many data at once. One are colored blue. All records with status “off” are shaded gray.
of the main interactive visualization tools is the Trace Editor Furthermore, right-clicking the waveform brings up a menu to
(Figure 3). The primary function of the Trace Editor is to start another GUI for visualizing the seismograms and radial
evaluate and select waveforms efficiently for further analysis. receiver function changing the record status, and displaying
Selecting the Manual Trace Edit GUI will read in the receiver event and record information useful in determining the appro-
function SAC files of the records in the selected table in the priate status of the record (Figure 4).
left-hand panel. Receiver functions are also normalized to the FuncLab also allows for automated trace editing, which is
largest positive amplitude for each trace. The trace editing GUI currently based on two criteria, and is intended to be a first pass
displays the receiver functions as time series waveforms with through a new receiver function dataset. First, a record’s status
time increasing down the y-axis and each record one unit wide is set to “on” if the maximum amplitude after one pulse width
across the x-axis. from time zero is above a chosen threshold. The pulse width is
Each record’s status can be changed in the GUI, allowing defined as
the user complete flexibility to specify good records that will
be used in future analyses (i.e., stacking and visualization pro- 1
cesses). Records with status “off” are not used in subsequent PW = , (1)
α 2 ln2
analyses but remain part of the dataset and are not deleted
from the project. This approach has the advantage of greater where α is the Gaussian parameter. The second criterion is a
freedom to perform multiple stages of trace editing or easily minimum fit or measure of uncertainty in the receiver func-
change the status of a record at the user’s discretion. The color tion, set in the SAC header (see User Manual). All other records
of the waveform is another indicator of the record’s status. that do not meet these criteria are set to “off.”
▲▲ Figure 4. Screenshot of trace editing system. Vertical, radial, and transverse seismograms and the associated radial receiver func-
tion are displayed. Event magnitude, distance, and depth are listed at top left. Status check box allows the user to change the record
status to “on” (checked) or “off” (unchecked). This screen is accessed by right-clicking a waveform in the trace editing GUI.
(B)
(C)
▲▲ Figure 5. Examples of data visualization output included in FuncLab. (A) Record section of station XC-OR087 table (data from Eagar
et al. 2011), including (from left to right) the vertical, radial, and transverse time series, followed by the radial and transverse receiver
functions. (B) Stacked receiver function amplitudes in ray parameter bins. Blue denotes positive amplitudes and red denotes negative
amplitudes. Left panels are the radial receiver functions. Right panels are the transverse receiver functions. Top panels show histogram
of receiver functions per bin. (C) Stacked receiver function amplitudes in backazimuth bins. Color and histograms are the same as in (B).