#irisws
Access to the Incorporated Research Institutions in Seismology (IRIS) Web Services (WS) from within R
This project is intended to serve as a tool to access Incorporated Research Institutions in Seismology (IRIS) Web Services (WS) using the R programming language. The repository is a self-consistent R-package, meaning one can do the following:
install.packages("devtools", dependencies=TRUE)
library(devtools)
install_github("abarbour/irisws", dependencies=TRUE)
and from then on
library(irisws)
# inspect documentation
?irisws
# list current webservice functions:
webservices()
# and so on...
The latter command prints a list of the webservice access-functions currently included.
This project has limited functionality at the moment, and is evolving -- you should update often. But, once this code is of suitable completeness (and reasonably well tested), I plan to upload it to CRAN. Feel free to contact me (@abarbour) should you have questions, or wish to contribute; or, use github as it was intended and submit some pull requests! :)
Note that you will also need to do the following for all features in the package to function properly:
pkgs <- c("httr","lubridate","png","RCurl","reshape2","XML","XML2R")
install.packages(pkgs, dependencies=TRUE)
but these should've been installed at
the install_github
stage.
Among other types of data, seismic data is easily accessed with the timeseries webservice. For example, the following command will download an image (generated internally) of two hours of 1-Hz pore pressure data at PBO station B084, containing signals from the 2010 M7.2 El Mayor Cucapah earthquake:
require(irisws)
# download the data plotted in a png file
# (the figure itself is generated within the IRIS-WS internal framework)
w <- ws.timeseries(network="PB", # network code
station="B084", # station code
location="--", # location code
channel="LDD", # channel code
starttime="2010.094T22:00:00", # the beginning of the data
duration=7200, # how many second from 'starttime' to download
output="plot", # output format
filename="myplot.png") # the filename of the output
which, upon success, is loaded into w
.
Loading is an optional feature, but TRUE
by default.
The figure returned by the original query should resemble something like this:
The object w
in this example also includes additional
information besides the data returned from IRIS-WS:
str(w, nchar.max = 40)
#List of 5
# $ file : chr "myplot.png"
# $ query : chr "http://service.iris.edu/irisws/timeseri"| __truncated__
# $ success : logi TRUE
# $ opts : list()
# $ querydata: 'nativeRaster' int [1:700, 1:1000] -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 ...
# ..- attr(*, "channels")= int 4
The data loaded into w
-- in this case an object with class "nativeRaster"
-- can be accessed
with the querydata
method:
qd <- querydata(w)
str(qd)
# 'nativeRaster' int [1:700, 1:1000] -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 ...
# - attr(*, "channels")= int 4
One could then, for example, plot the image from within R
(> 2.11):
if (exists("rasterImage")) {
plot(1:2, type='n')
rasterImage(querydata(w), 1.2, 1.27, 1.8, 1.73, interpolate=FALSE)
}
We just demonstrated how to set the output format to a internally-generated plot
( with output="plot"
), but there are in fact a number of (more useful)
formats which can be obtained -- see the documentation ( ?ws.timeseries
) for ways
to specify other formats.
In regards to obtaining data in a different output format, the package
includes a limited support framework for working with
Seismic Analysis Code (SAC) files
directly -- these are commonly
used in seismological applications, and are usually
named with the suffix .sac
.
To illustrate some of the functionality, we have
included a .sac
(binary) file to play with,
which can be read-in and plotted, for example:
require(irisws)
sacfi <- system.file("sac/elmayorB084_LDD.sac", package="irisws")
# this is a little-endian binary file, so be sure to specify it so the result
# makes sense (your system might be "big")
x <- read.sac(sacfi, is.binary=TRUE, endianness="little")
# the function 'read.sac' returns an object of class 'saclist', for which
# there is a plot method:
plot(x)
The plot.saclist
method yields a figure similar to the one shown above.
I have difficulty keeping track of the the various parameters
required for a given webservice (not to mention the myriad optional
arguments).
Because of this, we include a mechanism
to quickly inspect for parameters via the associated
.wadl
description;
this eliminates the need to check the service's webpage,
unless details of the different options are needed.
require(irisws)
# Access the .wadl file for the timeseries application
wd <- waddler("timeseries")
# find the parameters acceptable in a query...
print(p <- parameters(wd))
# and ones which are required
print(subset(p, required))
Another way to solve this would be to hard-code the query-parameter names as function arguments, but this will be left for development in the distant future.