aux_getevent: Load seismic data of a user-defined event

In coffeemuggler/eseis: Environmental Seismology Toolbox

Load seismic data of a user-defined event

Description

The function loads seismic data from a data directory structure (see aux_organisecubefiles()) based on the event start time, duration, component and station ID.

Usage

aux_getevent(
  start,
  duration,
  station,
  component = "BHZ",
  format,
  dir,
  simplify = TRUE,
  eseis = TRUE,
  try = FALSE,
  verbose = FALSE
)

Arguments

start	POSIXct value, start time of the data to import. If lazy users only submit a text string instead of a POSIXct obejct, the function will try to convert that text string.
duration	Numeric value, duration of the data to import, in seconds.
station	Character value, seismic station ID, which must correspond to the ID in the file name of the data directory structure (cf. aux_organisecubefiles).
component	Character value, seismic component, which must correspond to the component name in the file name of the data directory structure (cf. aux_organisecubefiles). Default is "BHZ" (vertical component of a sac file).
format	Character value, seismic data format. One out of "sac" and "mseed". If omitted, the function will try to identify the right format automatically.
dir	Character value, path to the seismic data directory. See details for further info on data structure.
simplify	Logical value, option to simplify output when possible. This basically means that if only data from one station is loaded, the list object will have one level less. Default is TRUE.
eseis	Logical value, option to read data to an eseis object (recommended, see documentation of aux_initiateeseis), default is TRUE
try	Logical value, option to run the function in try-mode, i.e., to let it return NA in case an error occurs during data import. Default is FALSE.
verbose	Logical value, option to show messages during function execution. Default is FALSE.

Details

The data to be read needs to be adequately structured. The data directory must contain SAC files organised by year (e.g.2022) then by Julian Day in full three digits (e.g. 001) and then by a dedicated SAC file name, containing the station ID, two-digit year, three-digit Julian Day, start time hour, minute and second, three channel ID and the file extension SAC. All these items need to be separated by stops (e.g. sac/2022/001/LAU01.22.001.08.00.00. BHZ.SAC). This data structure will be most conveniently created by the functions aux_organisecubefiles() or aux_organisecentaurfiles(), or by manually written R code.

The function assumes complete data sets, i.e., not a single hourly data set must be missing. The time vector is loaded only once, from the first station and its first component. Thus, it is assumed that all loaded seismic signals are of the same sampling frequency and length.

Value

A list object containing either a set of eseis objects or a data set with the time vector ($time) and a list of seismic stations ($station_ID) with their seismic signals as data frame ($signal). If simplify = TRUE (the default option) and only one seismic station is provided, the output object containseither just one eseis object or the vectors for $time and $signal.

Author(s)

Michael Dietze

Examples

## set seismic data directory
dir_data <- paste0(system.file("extdata", package="eseis"), "/")

## load the z component data from a station
data <- aux_getevent(start = as.POSIXct(x = "2017-04-09 01:20:00", 
                                        tz = "UTC"), 
                      duration = 120,
                      station = "RUEG1",
                      component = "BHZ",
                      dir = dir_data)                       
## plot signal
plot_signal(data = data)

## load data from two stations
data <- aux_getevent(start = as.POSIXct(x = "2017-04-09 01:20:00", 
                                        tz = "UTC"), 
                     duration = 120,
                     station = c("RUEG1", "RUEG2"),
                     component = "BHZ",
                     dir = dir_data)

## plot both signals
par(mfcol = c(2, 1))
lapply(X = data, FUN = plot_signal)
                     

coffeemuggler/eseis documentation built on Aug. 19, 2023, 9:57 p.m.