Lesson 07 addresses getting and working with seismic metrics data from the MUSTANG database. We will be working with the IRISMustangMetrics package.

Types of Metrics

The MUSTANG project uses several different types of metrics in the evaluation of seismic data quality. These different metric types have different representations in the database and it is important to understand these representations so that you can work effectively with metrics data.

The currently supported metric types include:

Accessing Seismic Metrics

Most metrics are of class SingleValueMetric and the simplest way to access metrics data stored in the MUSTANG database is with getSingleValueMetrics().

This method allows you to retrieve a number of SingleValueMetrics over a period of time as a single tidy dataframe with the following columns:

"metricName" "value" "snclq" "starttime" "endtime" "loadtime"

Note that some column names are changed compared with the default output we saw in Lesson 02.

The following example demonstrates how to obtain and work with daily min, mean and max values over a month for a particular SNCL.

library(IRISSeismic)
library(IRISMustangMetrics)

# Open a connection to IRIS DMC webservices (including the BSS)
iris <- new("IrisClient", debug=TRUE)

starttime <- as.POSIXct("2013-06-01", tz="GMT")
endtime <- starttime + 30*24*3600
metricName <- "sample_max,sample_min,sample_mean"

# Get the measurement dataframe
juneStats <- getSingleValueMetrics(iris,"IU","ANMO","00","BHZ",
                                   starttime,endtime,metricName)
## URL = http://service.iris.edu/mustang/measurements/1/query?net=IU&sta=ANMO&loc=00&cha=BHZ&timewindow=2013-06-01T00:00:00,2013-07-01T00:00:00&output=text&metric=sample_max,sample_min,sample_mean
# Simple ggplot2 plot
library(ggplot2)
p <- ggplot(juneStats, aes(x=starttime,y=value, color=as.factor(metricName))) +
  geom_step()
print(p)

Task 1: Download SingleValueMetrics

Obtain metrics for UW.TOLT..BH? SNCLs during March and April 2015.

Working with Metrics Objects and Lists

Before metrics are uploaded to MUSTANG they are created by R scripts and stored in memory, and sometimes on disk, as lists of ~Metric objects. The simplest and most common of these is the SingleValueMetric.

SingleValueMetric Object

A SingleValueMetric is an S4 object with slots to store the value of a metric for a particular SNCL over a particular period of time. See ?SinlgeValueMetric for details.

Each SingleValueMetric processes the data in a seismic Stream, potentially containing multiple Traces, and returns a single value as in the following example where we calculate a new ‘dynamic_range’ metric:

# Open a connection to IRIS DMC webservices
iris <- new("IrisClient")

# Get the waveform
starttime <- as.POSIXct("2012-01-24 00:00:00", tz="GMT")
endtime <- as.POSIXct("2012-01-25 00:00:00", tz="GMT")
st <- getDataselect(iris,"AK","PIN","","VEA",starttime,endtime)

# Get snclq
snclq <- st@traces[[1]]@id

# Calculate the dynamic_range metric
range <- max(st) - min(st)

# Create a new SingleValueMetric
rangeMetric <- new("SingleValueMetric", snclq=snclq,
                   starttime=starttime, endtime=endtime,
                   metricName="dynamic_range", value=range)

show(rangeMetric)
## SingleValueMetric 
##   metric:        dynamic_range
##   snclq:         AK.PIN..VEA.M
##   starttime:     2012-01-24
##   endtime:       2012-01-25
##   value:         2.000

Task 2: Generate SingleValueMetrics

Create SingleValueMetrics for each the following:

  • mean, max, dynamic_range
  • num_gaps, max_gap – use IRISSeismic::getGaps() to return information on the gaps in a Stream object
  • num_outliers – use seismicRoll::findOutliers to find outliers in each trace separately

Metrics Lists

Several functions in the IRISMustangMetrics package return lists of metrics and there is additional functionality to treat such lists as a unit. This allows the handling of larger conglomorations of metrics representing for example multiple metrics for a single SNCL-day, multiple days for a single SNCL-metric, multiple SNCLs for a single metric-day or any combination of the above.

The metricList2Xml() function is used to create the XML needed to upload metric data to the MUSTANG database while the metricList2DF() function converts a list of metrics into a list of dataframes for easier viewing with R.

The following example uses the stateOfHealthMetric() and basicStatsMetric() functions to append metrics to a growing list which is then converted into a dataframe for easier manipulation.

# Open a connection to IRIS DMC webservices
iris <- new("IrisClient")

# Get the waveform
starttime <- as.POSIXct("2012-01-24", tz="GMT")
endtime <- as.POSIXct("2012-01-25", tz="GMT")
st1 <- getDataselect(iris,"AK","PIN","","BHE",starttime,endtime)
st2 <- getDataselect(iris,"AK","PIN","","BHN",starttime,endtime)
st3 <- getDataselect(iris,"AK","PIN","","BHZ",starttime,endtime)

# Apply a metric and show the results
metricList <- stateOfHealthMetric(st1)
metricList <- append(metricList, basicStatsMetric(st1))
metricList <- append(metricList, basicStatsMetric(st2))
metricList <- append(metricList, basicStatsMetric(st3))
metricDFList <- metricList2DFList(metricList)

# Each element of the list is named after a particular metric
names(metricDFList)
##  [1] "calibration_signal_DF"      "timing_correction_DF"      
##  [3] "event_begin_DF"             "event_end_DF"              
##  [5] "event_in_progress_DF"       "clock_locked_DF"           
##  [7] "amplifier_saturation_DF"    "digitizer_clipping_DF"     
##  [9] "spikes_DF"                  "glitches_DF"               
## [11] "missing_padded_data_DF"     "telemetry_sync_error_DF"   
## [13] "digital_filter_charging_DF" "suspect_time_tag_DF"       
## [15] "timing_quality_DF"          "sample_min_DF"             
## [17] "sample_median_DF"           "sample_mean_DF"            
## [19] "sample_max_DF"              "sample_rms_DF"
# Dataframes may have multiple rows
metricDFList[['sample_max_DF']]
##            snclq  starttime    endtime sample_max quality_flag
## 19 AK.PIN..BHE.M 2012-01-24 2012-01-25       4867           -9
## 24 AK.PIN..BHN.M 2012-01-24 2012-01-25       2946           -9
## 29 AK.PIN..BHZ.M 2012-01-24 2012-01-25       2236           -9

Task 3: Metric Lists

  • use a ‘for loop’ to create hourly basicStatsMetrics and append them to a list
  • plot min, median, mean and max on a single plot as a function of starttime

Seismic Traces < prev | next > ggplot2