IRISSeismic (version 1.10.0)

getDataselect: Retrieve seismic data from EarthScope or other FDSN Data Center

Description

The getDataselect method makes a request of the EarthScope (or other Data Center) dataselect webservice and returns a Stream object in which individual Traces have been sorted by start time.

Usage

getDataselect(
  obj,
  network,
  station,
  location,
  channel, 
  starttime,
  endtime,
  ...
)

Value

A new Stream object is returned.

Arguments

obj

IrisClient object

network

character string with the two letter seismic network code

station

character string with the station code

location

character string with the location code

channel

character string with the three letter channel code

starttime

POSIXct class specifying the starttime (GMT)

endtime

POSIXct class specifying the endtime (GMT)

...

optional arguments quality optional character string identifying the quality. EarthScope webservices defaults to quality="M". repository optional character string identifying whether to exclusively search primary archive or realtime collection buffers. Acceptable values are "primary" or "realtime". If not specified, EarthScope webservices defaults to both repositories. inclusiveEnd optional logical determining whether the endtime is inclusive (default = TRUE) ignoreEpoch optional logical defining behavior when multiple epochs are encountered (default = FALSE)

Author

Jonathan Callahan

Details

This is the primary method for retrieving seismic data. Data requests are made through the dataselect webservice and returned data are parsed using the internal miniseed2Stream() function.

If the location argument contains an empty string to specify a 'blank' location code, a location code of "--" will be used in the dataselect request URL. (See dataselect documentation.)

If inclusiveEnd=FALSE, then getDataselect will subtract 0.000001 seconds from the endtime before passing the value to the dataselect webservice. An endtime of, e.g., as.POSIXct("2016-01-03", tz="GMT") will be passed into dataselect as end=2016-01-02T23:59:59.999999. A data sample at time 2016-01-03T00:00:00 will not be returned unless inclusiveEnd=TRUE.

Error returns from the webservice will stop evaluation and generate an error message.

Sometimes the station webservice will return multiple records for the same SNCL, each with a different scale or starttime. These represent different epochs with potentially different metadata parameters for the SNCL and, by default, will cause a 'Multiple epochs' error message to be generated.

Handling all possible metadata differences so that the data may be merged is beyond the scope of this package. Instead, to avoid errors, users may specify ignoreEpoch=TRUE in which case the very first SNCL-epoch encountered will be used and all others will be discarded.

For access to restricted data, getDataselect will look for a system environmental variable "IrisClient_passw" which should be a string in the form "login:password". Alternatively, getDataselect will look for system environmental variable "IrisClient_netrc" which should point to a .netrc authentication file.

References

The EarthScope dataselect webservice:

https://service.earthscope.org/fdsnws/dataselect/1/

This implementation is similar in functionality to the obspy dataselect function:

https://docs.obspy.org/_modules/obspy/clients/fdsn/client.html

See Also

getSNCL, IrisClient-class

Examples

if (FALSE) {
# Open a connection to EarthScope webservices
iris <- new("IrisClient")
options("nanotimeFormat"="%Y-%m-%dT%H-%M-%E9S")

# Use getDataselect to request data for II.JTS.00.BHZ
starttime <- as.POSIXct("2001-02-28",tz="GMT")
endtime <- as.POSIXct("2001-03-01",tz="GMT")

st <- getDataselect(iris, "II","JTS","00","BHZ",starttime, endtime, 
                    inclusiveEnd=FALSE,ignoreEpoch=TRUE)

# Display structure of trace(s)

str(st)

# Plot trace
plot(st)
}