eseis (version 0.8.1)

aux_stationinfofile: Create station info file from cube files.

Description

This function reads GPS tags from Omnirecs/Digos Datacube files and creates a station info file from additional input data. It depends on the gipptools software package (see details).

Usage

aux_stationinfofile(
  file,
  input,
  output,
  gipptools,
  ID,
  name,
  z,
  d,
  sensor_type,
  logger_type,
  sensor_ID,
  logger_ID,
  gain,
  dt,
  start,
  stop,
  n,
  order = "margin",
  unit = "dd",
  quantile = 0.95,
  cpu,
  write_file = TRUE,
  write_raw = FALSE,
  write_data = FALSE
)

Value

A set of files written to disk and a data frame with seismic station information.

Arguments

file

Character value, file name of the output station info file, with extension but without path.

input

Character value, path to directory where all cube files to be processed as stored. Each set of files from one logger must be stored in a separate sub-directory named after the cube ID.

output

Character value, path to directory where output data is written to.

gipptools

Character value, path to gipptools or cubetools directory.

ID

Character vector, seismic station ID. Each value must not contain more than 5 characters. Longer entries will be clipped. If omitted, a default ID will be created.

name

Character vector, seismic station name. If omitted, the station ID is used as name.

z

Numeric vector, elevation of the seismic stations

d

Numeric vector, deployment depth of the seismic sensor

sensor_type

Character vector, sensor types

logger_type

Character vector, logger types

sensor_ID

Character vector, sensor IDs

logger_ID

Character vector, logger IDs

gain

Numeric or character vector, gain values. If omitted, the information will be extracted from Cube files, if possible.

dt

Numeric or character vector, sampling intervals. If omitted, the information will be extracted from Cube files, if possible.

start

POSIXct or character vector, time when station started operating. If omitted, the information will be extracted from Cube files, if possible.

stop

POSIXct or character vector, time when station stopped operating. If omitted, the information will be extracted from Cube files, if possible.

n

Numeric value, number of cube file to process for GPS coordinate extraction. If omitted, all files are processed.

order

Character value, keyword indicating how files will be chosen to extract meta data. One out of "margin" (first and last Cube file, necessary to extract start and end time of the record), "random" (random order of files) and "ascending" (files in ascending order). Default is "margin".

unit

Character value, coordinates unit of the location. One out of "dd" (decimal degrees) and "utm" (metric in UTM zone). Default is "dd".

quantile

Numeric value, quantile size to which the extracted coordinate sample size is restricted. This is mainly used to remove coordinate outliers, due to spurious GPS signals. Default is 0.95. Set to 1 to omit any sample rejection.

cpu

Numeric value, fraction of CPUs to use for parallel processing. If omitted, one CPU is used.

write_file

Logical value, option to write station info file to disk. Default is TRUE.

write_raw

Logical value, option to write (keep) raw ASCII GPS data. Default is FALSE.

write_data

Logical value, option to write gps raw data as rda-file. File name will be the same as for file. Default is FALSE.

Author

Michael Dietze

Details

A station info file is an ASCII table that contains all relevant information about the individual stations of a seismic network. The variables contain a station ID (containing not more than 5 characters), station name (an longer description of the station), latitude, longitude, elevation, deployment depth, sensor type, logger type, sensor ID, logger ID, gain (signal preamplification by the logger), dt (sampling interval), start and stop time of the station records.

The start and stop times can be automatically collected from the meta data stored along in each Cube file. For that, the function has to select the first and last file in a data record of a station. This is automatically done if the option order = "margin" is selected and the number of files per station to process is two, hence n = 2.

Automatically, the resulting ASCII file will have all 14 columns as defined above. One has to delete unwanted columns (or add additional ones) from the text file, manually after the file has been generated.

The function requires the software gipptools (http://www.gfz-potsdam.de/en/section/geophysical-deep-sounding/infrastructure/geophysical-instrument-pool-potsdam-gipp/software/gipptools/) is installed. Note that GPS tag extraction may take several minutes per cube file. Hence, depending on the number of files and utilised CPUs the processing may take a while.

Specifying an input directory (input) is mandatory. This input directory must only contain the subdirectories with the cube files to process, each set of cube files must be located in a separate subdirectory and these subdirectories must have the same name as specified by the logger IDs (logger_ID). An appropriate structure would be something like:

1. input

   1. A1A

      1. file1.A1A

      2. file2.A1A

   2. A1B

      1. file1.A1B

      2. file2.A1B

Examples

if (FALSE) {

## basic example with minimum effort
aux_stationinfofile(file = "stationinfo.txt", 
                    input = "path/to/cube/dirs", 
                    output = "path/to/stationfile/", 
                    gipptools = "software/gipptools-2024.354", 
                    logger_ID = c("A1A", "A1B"))

## example with more adjustments
aux_stationinfofile(file = "stationinfo.txt", 
                    input = "path/to/cube/dirs", 
                    output = "path/to/stationfile/", 
                    gipptools = "software/gipptools-2024.354",
                    ID = c("STAN", "STAS"),
                    name = c("Station North", "Station South"), 
                    z = c(1000, 1100),
                    d = c(0.5, 0.5),
                    sensor_type = c("TC120s", "TC120s"), 
                    logger_type = c("Cube3extBOB", "Centaur"), 
                    sensor_ID = c("4711", "0815"), 
                    logger_ID = c("A1A", "A1B"), 
                    gain = c(32, 16), 
                    dt = c(1/100, 1/200),
                    n = 3, 
                    order = "margin", 
                    unit = "utm",
                    cpu = 0.5, 
                    write_raw = TRUE,
                    write_data = TRUE)
}