Appendices

Time Syntax

Functions that allow time specification use two reserved keywords or arguments to track time:

• s: Start (begin) time
• t: Termination (end) time

Specify each as a DateTime, Real, or String.

• Real numbers are interpreted as seconds. Special behavior is invoked when both s and t are of Type Real.

• DateTime values should follow Julia documentation\ <https://docs.julialang.org/en/v1/stdlib/Dates/>_

• Strings have the expected format spec YYYY-MM-DDThh:mm:ss.ssssss

  • Fractional second is optional and accepts up to 6 decimal places (μs)

  • Incomplete time Strings treat missing fields as 0.

  • Example: s="2016-03-23T11:17:00.333"

It isn't necessary to choose values so that s ≤ t. The two values are always sorted, so that t < s doesn't error.

Time Types and Behavior

Special Behavior with two Real arguments

If s and t are both Real numbers, they're treated as seconds measured relative to the start of the current minute. This convention may seem unusual, but it greatly simplifies web requests; for example, specifying s=-1200.0, t=0.0 is a convenient shorthand for "the last 20 minutes of data".

Data Requests Syntax

Channel ID Syntax

NN.SSSSS.LL.CC (net.sta.loc.cha, separated by periods) is the expected syntax for all web functions. The maximum field width in characters corresponds to the length of each field (e.g. 2 for network). Fields can't contain whitespace.

NN.SSSSS.LL.CC.T (net.sta.loc.cha.tflag) is allowed in SeedLink. T is a single-character data type flag and must be one of DECOTL: Data, Event, Calibration, blOckette, Timing, or Logs. Calibration, timing, and logs are not in the scope of SeisBase and may crash SeedLink sessions.

The table below specifies valid types and expected syntax for channel lists.

The expected component order is always network, station, location, channel; thus, "UW.TDH..EHZ" is OK, but "UW.TDH.EHZ" fails.

chanspec()

Type ?chanspec in Julia to print the above info. to stdout.

Wildcards and Blanks

Allowed wildcards are client-specific.

• The LOC field can be left blank in any client: "UW.ELK..EHZ" and ["UW" "ELK" "" "EHZ"] are all valid. Blank LOC fields are set to -- in IRIS, * in FDSN, and ?? in SeedLink.
• ? acts as a single-character wildcard in FDSN & SeedLink. Thus, CC.VALT..??? is valid.
• * acts as a multi-character wildcard in FDSN. Thus, CC.VALT..* and CC.VALT..??? behave identically in FDSN.
• Partial specifiers are OK, but a network and station are always required: "UW.EL?" is OK, ".ELK.." fails.

Channel Configuration Files

One entry per line, ASCII text, format NN.SSSSS.LL.CCC.D. Due to client-specific wildcard rules, the most versatile configuration files are those that specify each channel most completely:

# This only works with SeedLink
GE.ISP..BH?.D
NL.HGN
MN.AQU..BH?
MN.AQU..HH?
UW.KMO
CC.VALT..BH?.D

# This works with FDSN and SeedLink, but not IRIS
GE.ISP..BH?
NL.HGN
MN.AQU..BH?
MN.AQU..HH?
UW.KMO
CC.VALT..BH?

# This works with all three:
GE.ISP..BHZ
GE.ISP..BHN
GE.ISP..BHE
MN.AQU..BHZ
MN.AQU..BHN
MN.AQU..BHE
MN.AQU..HHZ
MN.AQU..HHN
MN.AQU..HHE
UW.KMO..EHZ
CC.VALT..BHZ
CC.VALT..BHN
CC.VALT..BHE

Server List

SeisBase Standard Keywords

SeisBase.KW is a memory-resident structure of default values for common keywords used by package functions. KW has one substructure, SL, with keywords specific to SeedLink. These defaults can be modified, e.g., SeisBase.KW.nev=2 changes the default for nev to 2.

.. rubric:: Table Footnotes .. [1] Types: A = Array, B = Boolean, C = Char, DT = DateTime, F = Float, I = Integer, S = String, U8 = Unsigned 8-bit integer (UInt8) .. [2] If KW.comp == 0x00, never compress data; if KW.comp == 0x01, only compress channel i if length(S.x[i]) > KW.n_zip; if comp == 0x02, always compress data. .. [3] Strings have the same names and spellings as file formats in read_data. Note that "sac" in a web request is aliased to "sacbl", i.e., binary little-endian SAC, to match the native endianness of the Julia language. .. [4] String is passed as-is, e.g. "szsrecs=true&repo=realtime" for FDSN. String should not begin with an ampersand. .. [5] Specify region [centerlat, centerlon, minradius, maxradius, depmin, depmax], with lat, lon, and radius in decimal degrees (°) and depth in km with + = down. Depths are only used for earthquake searches. .. [6] Specify region [latmin, latmax, lonmin, lonmax, depmin, depmax], with lat, lon in decimal degrees (°) and depth in km with + = down. Depths are only used for earthquake searches. .. [7] FDSNWS timeseries only. .. [8] If w=true, a file name is automatically generated from the request parameters, in addition to parsing data to a SeisData structure. Files are created from the raw download even if data processing fails, in contrast to getdata(... wsac=true). .. _functionlist:

Utility Functions

This appendix covers utility functions that belong in no other category.

fctoresp(f)
fctoresp(f, c)

regex_find(path::String, r::Regex)

getbandcode(fs, fc=FC)

get_seis_channels(S::GphysData)

function guess(fname[, v=V])

inst_codes(S::GphysData)

inst_code(S::GphysData, i::Integer)

inst_code(S::GphysData, i::Integer)
inst_code(C::GphysChannel)

inst_codes(S::GphysData)

inst_code(S::GphysData, i::Integer)

ls(str::String)

m,d = j2md(y,j)

j = md2j(y, m, d)

namestrip(s::String, convention::String="File")

(str0, str1) = parsetimewin(ts1::TimeSpec, ts2::TimeSpec)

resp_a0!(R::Union{PZResp, PZResp64})

resp_a0!(S::GphysData)

resptofc(R::Union{PZResp, PZResp64}))

set_file_ver(fname, ver)

validate_units(S::GphysData)

validate_units(C::GphysChannel)

vucum(str::String)

SeisBase Native Format

Invoking the command wseis writes SeisBase structures to a native data format in little-endian byte order. This page documents the low-level file format. Abbreviations used:

Special instructions:

• Parentheses, "()", denote a custom object Type.
• "{ (condition)" denotes the start of a loop; (condition) is the control flow.
• "}" denotes the end of a loop.

Note that String in Julia has no exact C equivalence. SeisBase writes each String in two parts: an Int64 (String length in bytes) followed by the String contents (as bytes, equivalent to UInt8). Unlike C/Fortran, there are no issues with strings that contain the null character (0x00 or $'\x0'$).

SeisBase File

ID, TS, and TE are the ID, data start time, and data end time of each channel in each object. P is the index of the parent object in C and B. TS and TE are measured from Unix epoch time (1970-01-01T00:00:00Z) in integer microseconds.

Intent: when seeking data from channel i between times s and t, if hash(i) matches ID[j] and the time windows overlap, retrieve index k = P[j] from NP, seek to byte offset B[k], and read an object of type C[k] from file.

If an archive contains no data objects, ID, TS, TE, and P are empty; equivalently, bID == bTS.

Simple Object Types

Fields of these objects are written in one of three ways: as "plain data" types, such as UInt8 or Float64; as arrays; or as strings.

In a simple object, each array is stored as follows:

1. Int64 number of dimensions (e.g. 2)
2. Int64 array of dimensions themselves (e.g. 2, 2)
3. Array values (e.g. 0.08250153, 0.023121119, 0.6299772, 0.79595184)

EQLoc

flag meanings: (0x01 = true, 0x00 = false)

1. x fixed?
2. y fixed?
3. z fixed?
4. t fixed?

In Julia, get the value of flag[n] with $>>(<<(flags, n-1), 7)$.

EQMag

SeisPha

SourceTime

StringVec

A vector of variable-length strings; its exact Type in Julia is Array{String,1}.

.. csv-table:: StringVec :header: Var, Type, N, Meaning :widths: 1, 1, 1, 8

• [1] If ee == 0x00, then no values are stored for L, nb, or str.

Location Types

GenLoc

GeoLoc

UTMLoc

XYLoc

Response Types

GenResp

PZResp

PZResp64 is identical to PZResp with Float64 values for c, p, z, rather than Float32.

The Misc Dictionary

Most compound objects below contain a dictionary (Dict{String,Any}) for non-essential information in a field named $:misc$. The tables below describe how this field is written to disk.

Misc

.. csv-table:: :header: Var, Type, N, Meaning :widths: 1, 2, 1, 8

• [1] If $N == 0$, then N is the only value present.

Dictionary Contents

These subtables describe how to read the possible data types in a Misc dictionary.

String Array (c == 0x81)

Other Array (c == 0x80 or c > 0x81)

String (c == 0x01)

Bits Type (c == 0x00 or 0x01 < c < 0x7f)

Read a single value whose Type corresponds to the UInt8 Type code.

Compound Object Types

Each of these objects contains at least one of the above simple object types.

PhaseCat

• [1] If $N == 0$, then N is the only value present.

EventChannel

A single channel of data related to a seismic event

SeisChannel

A single channel of univariate geophysical data

EventTraceData

A multichannel record of time-series data related to a seismic event.

• [1] If cmp == 0x01, each value in Nx is the number of bytes of compressed data to read; otherwise, this is the number of samples in each channel.
• [2] If cmp == 0x01, read Nx[i] samples of type UInt8 and pass through lz4 decompression to generate data vector i; else read Nx[i] samples of the type corresponding to code Xc[i].

SeisData

A record containing multiple channels of univariate geophysical data.

• [1] If cmp == 0x01, each value in Nx is the number of bytes of compressed data to read; otherwise, this is the number of samples in each channel.
• [2] If cmp == 0x01, read Nx[i] samples of type UInt8 and pass through lz4 decompression to generate data vector i; else read Nx[i] samples of the type corresponding to code Xc[i].

SeisHdr

• [1] Measured from Unix epoch time (1970-01-01T00:00:00Z) in integer microseconds

SeisSrc

SeisEvent

Data Type Codes

Each Type code is written to disk as a UInt8, with the important exception of SeisBase custom object Type codes (which use UInt32).

Loc Type Codes

Resp Type Codes

Other Type Codes

Only the Types below are faithfully preserved in write/read of a :misc field dictionary; other Types are not written to file and can cause $wseis$ to throw errors.

SeisBase Object Type codes

File Format Version History

File format versions <0.50 are no longer supported; please email us if you need to read in very old data.