getChannel {IRISSeismic}

Retrieve Channel metadata from IRIS DMC

Description

The getChannel method obtains channel metadata from the IRIS DMC station web service and returns it in a dataframe.

Usage

getChannel(obj, network, station, location, channel,
           starttime, endtime, includerestricted,
           latitude, longitude, minradius, maxradius)

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)

includerestricted

optional logical identifying whether to report on restricted data

latitude

optional latitude used when specifying a location and radius

longitude

optional longitude used when specifying a location and radius

minradius

optional minimum radius used when specifying a location and radius

maxradius

optional maximum radius used when specifying a location and radius

Details

The getChannel method uses the station web service to obtain data for all channels that meet the criteria defined by the arguments and returns that data in a dataframe. Each row of the dataframe represents a unique channel-epoch.

Each of the arguments network, station, location or channel may contain a valid code or a wildcard expression, e.g. "BH?" or "*". Empty strings are converted to "*". Otherwise the ascii string that is used for these values is simply inserted into the web service request URL.

For more details see the webservice documentation.

Value

A dataframe with the following columns:

network, station, location, channel, latitude, longitude, elevation,
  depth, azimuth, dip, instrument, scale, scalefreq, scaleunits, 
  samplerate, starttime, endtime, snclId

Rows are ordered by snclId.

The snclId column, eg. "US.OCWA..BHE", is generated as a convenience. It is not part of the normal return from the station web service.

Note: The snclIds is not a unique identifier. If the time span of interest crosses an epoch boundary where instrumentation was changed then multiple records (rows) will share the same snclId.

Author(s)

Jonathan Callahan [e-mail]

References

The IRIS DMC station webservice:

https://service.iris.edu/fdsnws/station/1/

This implementation was inspired by the functionality in the obspy get_stations() method.

https://docs.obspy.org/packages/autogen/obspy.clients.fdsn.client.Client.get_stations.html

See Also

IrisClient-class, getAvailability, getUnavailability

Examples

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

# Date of Nisqually quake
starttime <- as.POSIXct("2001-02-28",tz="GMT")
endtime <- starttime + 2*24*3600

# Use the getEvent web service to determine what events happened in this time period
result <- try(events <- getEvent(iris,starttime,endtime,6.0))
if (inherits(result,"try-error")) {
  message(geterrmessage())
} else {
  events

# biggest event is Nisqually
  eIndex <- which(events$magnitude == max(events$magnitude))
  e <- events[eIndex[1],]
}

# Which stations in the US network are within 5 degrees of the quake epicenter?
result <- try(stations <- getStation(iris,"US","*","*","BHZ",starttime,endtime,
                          lat=e$latitude,long=e$longitude,maxradius=5))
if (inherits(result,"try-error")) {
  message(geterrmessage())
} else {
  stations
}

# Get some detailed information on any BHZ channels at the "Octopus Mountain" station
result <- try(channels <- getChannel(iris,"US","OCWA","*","BHZ",starttime,endtime))
if (inherits(result,"try-error")) {
  message(geterrmessage())
} else {
  channels
}