MsPASS Schema#

Many seismologists think of a database schema as the specification of tables and attributes in a relational database. The standard relational schema in seismology is CSS3.0, which is used by systems such as Antelope. In computer science, however, the term has a broader meaning: it describes the structure, types, and constraints of data. MsPASS uses that broader meaning because its primary database backend is MongoDB rather than a relational database.

This section documents the metadata keys recognized by MsPASS. Each table is generated from data/yaml/mspass.yaml during the Sphinx build, so the published tables track the same schema used by the Python database layer.

The tables below are organized in three ways:

  1. A complete alphabetical catalog of valid metadata keys and aliases.

  2. Groups of keys that are normalized into master MongoDB collections, such as receiver and source coordinates.

  3. Groups of keys that have a practical or conceptual relationship, such as ObsPy Trace attributes, three-component orientation metadata, and file storage metadata.

All Valid Attributes#

The table below defines all attributes MsPASS should handle without special treatment. They are arranged in alphabetical order. (Note all keys are case sensitive. In UTF-8 alphabetical order capitals appear before lower case.)

Table 10 All MsPASS Attributes#

Key

Type

Mutable

Concept

DEPMAX

double

Yes

Minimum amplitude of a signal

DEPMEN

double

Yes

Mean amplitude of a signal

DEPMIN

double

Yes

Maximum amplitude of a signal

IEVTYP

int

Yes

Event type code as used in SAC

IZTYPE

int

Yes

Reference time type as used by SAC

KEVNM

string

Yes

Event name

_id

ObjectId

No

ObjectId used to define a data object

calib

double

Yes

Nominal conversion factor for changing sample data to ground motion units.

cardinal

boolean

Yes

When true the data stored are orthogonal and in cardinal (ENZ) geographic directions.

chan

string

No

channel name (e.g. HHZ, BHE, etc.) - normally a SEED channel code

channel_edepth

double

No

depth of a seismic station/instrument in km

channel_elev

double

No

elevation of a seismic station/instrument in km (subtract emplacement depth for borehole instruments)

channel_endtime

double

No

Time of channel ends recording

channel_hang

double

No

Azimuth (in degree) of a seismometer component - horizontal angle

channel_id

ObjectId

Yes

ObjectId used to define a particular component of data

channel_lat

double

No

latitude of a seismic station/instrument in degrees

channel_lon

double

No

longitude of a seismic station/instrument in degrees

channel_starttime

double

No

Time of channel starts recording

channel_vang

double

No

Inclination from +up (in degree) of a seismometer component - vertical angle

delta

double

Yes

Data sample interval in seconds

dfile

string

Yes

External data file name.

dir

string

Yes

Directory path to an external file (always used with dfile)

dist

double

Yes

Source receiver distance

distance_units

string

Yes

Units of dist attribute

esaz

double

Yes

Event to station azimuth

foff

int

Yes

Offset in bytes from beginning of a file to first data sample.

format

string

Yes

The file format of the saved data (e.g., ‘MSEED’, ‘SAC’, …).

gridfs_id

ObjectId

Yes

The _id of data file in the fs.files collection.

iphase

string

Yes

Indicated phase (from CSS3.0) - phase name from travel time curve association

jdate

int

Yes

Julian date string as used in CSS3.0

loc

string

No

location code assigned to an instrument (loc component of SEED net:sta:chan)

mb

double

No

Body wave magnitude

ms

double

No

Surface wave magnitude

nbytes

int

Yes

Number of bytes for storage of sample data - required for some formats

net

string

No

network code (net component of SEED net:sta:chan)

npts

int

Yes

Number of data samples

orthogonal

boolean

Yes

When true the transformation matrix is orthogonal (inverse can then be constructed from transpose instead of inversion).

phase

string

Yes

Phase name assigned by an analyst to a pick

sampling_rate

double

Yes

Data sampling frequency in Hz=1/s

seaz

double

Yes

Station to event azimuth

site_elev

double

No

elevation of a seismic station/instrument in km (subtract emplacement depth for borehole instruments)

site_endtime

double

No

Time of seismic station/instrument ends recording

site_id

ObjectId

Yes

ObjectId used to define a particular instrument/seismic station

site_lat

double

No

latitude of a seismic station/instrument in degrees

site_lon

double

No

longitude of a seismic station/instrument in degrees

site_starttime

double

No

Time of seismic station/instrument starts recording

source_depth

double

No

Depth (in km) of the hypocenter of seismic source

source_id

ObjectId

Yes

ObjectId used to define a particular seismic source

source_lat

double

No

Latitude (in degrees) of the hypocenter of seismic source

source_lon

double

No

Longitude (in degrees) of the hypocenter of seismic source

source_magnitude

double

No

Generic magnitude attribute

source_time

double

No

Origin time of the hypocenter of seismic source (epoch time)

sta

string

No

station code assigned to a spot on Earth (sta component of SEED net:sta:chan)

starttime

double

Yes

Time of first sample of data (epoch time or relative to some other time mark)

storage_mode

string

Yes

The storage mode of the saved data (‘file’, ‘url’ or ‘gridfs’)

time_standard

string

Yes

Defines time standard for meaning of t0 (default should be UTC)

tmatrix

list

Yes

Three-component data’s transformation matrix

units

string

Yes

Physical units of sample data (nm/s is normal assumed default)

utc_convertible

boolean

Yes

When true starttime_shift can be used to convert relative time to UTC.

The key in the master list above is always used as the index to locate an attribute for a particular concept in MongoDB. However, MsPASS also implements a generic alias mechanism that allows a function to fetch an attribute internally (i.e. when the data are in memory for processing) using an alternative name (alias). The table below defines all valid aliases for unique keys with the alias keys separated by colons:

Table 11 All MsPASS aliases#

Unique Key

Valid Aliases

DEPMAX

depmax

DEPMEN

depmen

DEPMIN

depmin

IZTYPE

TimeReferenceType

chan

KCMPNM : channel : channel.chan : wfdisc.chan

channel_hang

CMPAZ

channel_vang

CMPINC

delta

dt

dfile

file.dfile : wfdisc.dfile : wfprocess.dfile

dir

file.dir : wfdisc.dir : wfprocess.dir

dist

GCARC : assoc.delta

esaz

AZ

foff

file.foff : wfdisc.foff : wfprocess.foff

loc

channel.loc : location : site.loc

net

channel.net : network : site.net : site_net : wfdisc.net

npts

nsamp : wfdisc.nsamp

seaz

BAZ

site_elev

STEL : site.elev : stel

site_endtime

site.endtime

site_lat

STLA : site.lat

site_lon

STLO : site.lon : stlo

site_starttime

site.starttime

source_depth

EVDP : origin.depth : source.depth

source_lat

EVLA : origin.lat : source.lat

source_lon

EVLO : origin.lon : source.lon

source_magnitude

MAG

source_time

origin.time : source.time

sta

KSTNM : channel.sta : site.sta : station : wfdisc.sta

starttime

t0 : time

units

IDEP : idep

Master Documents for Normalized Attributes#

Site Collection (Receiver coordinates)#

This set of attributes defines the physical location of a seismic sensor on the Earth. It also lists related attributes used for cross-referencing documents in the site collection.

Table 12 Receiver coordinate (site collection) Attributes#

Key

Type

Mutable

Concept

net

string

No

network code (net component of SEED net:sta:chan)

sta

string

No

station code assigned to a spot on Earth (sta component of SEED net:sta:chan)

loc

string

No

location code assigned to an instrument (loc component of SEED net:sta:chan)

site_lat

double

No

latitude of a seismic station/instrument in degrees

site_lon

double

No

longitude of a seismic station/instrument in degrees

site_elev

double

No

elevation of a seismic station/instrument in km (subtract emplacement depth for borehole instruments)

site_starttime

double

No

Time of seismic station/instrument starts recording

site_endtime

double

No

Time of seismic station/instrument ends recording

site_id

ObjectId

Yes

ObjectId used to define a particular instrument/seismic station

Source Collection (Seismic Source coordinates)#

This set of attributes defines location estimates or measured locations of seismic sources. MsPASS does not support the concept of multiple location estimates for the same seismic events that is a major complication in the relational database schema CSS3.0 used, for example, in Antelope. Each source is defined by the unique id source_id listed in the table below.

Table 13 Source coordinate (source collection) Attributes#

Key

Type

Mutable

Concept

source_id

ObjectId

Yes

ObjectId used to define a particular seismic source

source_lat

double

No

Latitude (in degrees) of the hypocenter of seismic source

source_lon

double

No

Longitude (in degrees) of the hypocenter of seismic source

source_depth

double

No

Depth (in km) of the hypocenter of seismic source

source_time

double

No

Origin time of the hypocenter of seismic source (epoch time)

source_magnitude

double

No

Generic magnitude attribute

mb

double

No

Body wave magnitude

ms

double

No

Surface wave magnitude

Attributes with Conceptual Relationship#

ObsPy Trace Object#

The ObsPy package on which MsPASS leans heavily defines a Trace object with a fixed set of required parameters. The names can be aliased but the unique keys of all of the attributes below are identical to the name defined for the ObsPy Trace object.

Table 14 Required Attributes for obspy Trace object#

Key

Type

Mutable

Concept

calib

double

Yes

Nominal conversion factor for changing sample data to ground motion units.

chan

string

No

channel name (e.g. HHZ, BHE, etc.) - normally a SEED channel code

delta

double

Yes

Data sample interval in seconds

loc

string

No

location code assigned to an instrument (loc component of SEED net:sta:chan)

net

string

No

network code (net component of SEED net:sta:chan)

npts

int

Yes

Number of data samples

sampling_rate

double

Yes

Data sampling frequency in Hz=1/s

sta

string

No

station code assigned to a spot on Earth (sta component of SEED net:sta:chan)

starttime

double

Yes

Time of first sample of data (epoch time or relative to some other time mark)

Channel Attributes#

Table 15 Channel attributes#

Key

Type

Mutable

Concept

channel_id

ObjectId

Yes

ObjectId used to define a particular component of data

chan

string

No

channel name (e.g. HHZ, BHE, etc.) - normally a SEED channel code

loc

string

No

location code assigned to an instrument (loc component of SEED net:sta:chan)

channel_lat

double

No

latitude of a seismic station/instrument in degrees

channel_lon

double

No

longitude of a seismic station/instrument in degrees

channel_elev

double

No

elevation of a seismic station/instrument in km (subtract emplacement depth for borehole instruments)

channel_edepth

double

No

depth of a seismic station/instrument in km

channel_hang

double

No

Azimuth (in degree) of a seismometer component - horizontal angle

channel_vang

double

No

Inclination from +up (in degree) of a seismometer component - vertical angle

channel_starttime

double

No

Time of channel starts recording

channel_endtime

double

No

Time of channel ends recording

Three-Component Data Attributes#

These attributes describe the orientation and transformation matrix used by three-component seismic data objects.

Table 16 Three-component data attributes#

Key

Type

Mutable

Concept

tmatrix

list

Yes

Three-component data’s transformation matrix

cardinal

boolean

Yes

When true the data stored are orthogonal and in cardinal (ENZ) geographic directions.

orthogonal

boolean

Yes

When true the transformation matrix is orthogonal (inverse can then be constructed from transpose instead of inversion).

External File Attributes#

Table 18 File attributes#

Key

Type

Mutable

Concept

dir

string

Yes

Directory path to an external file (always used with dfile)

dfile

string

Yes

External data file name.

foff

int

Yes

Offset in bytes from beginning of a file to first data sample.

format

string

Yes

The file format of the saved data (e.g., ‘MSEED’, ‘SAC’, …).

nbytes

int

Yes

Number of bytes for storage of sample data - required for some formats

storage_mode

string

Yes

The storage mode of the saved data (‘file’, ‘url’ or ‘gridfs’)

gridfs_id

ObjectId

Yes

The _id of data file in the fs.files collection.

Indexing Attributes for MongoDB#

Table 19 MongoDB attributes#

Key

Type

Mutable

Concept

_id

ObjectId

No

ObjectId used to define a data object

site_id

ObjectId

Yes

ObjectId used to define a particular instrument/seismic station

channel_id

ObjectId

Yes

ObjectId used to define a particular component of data

source_id

ObjectId

Yes

ObjectId used to define a particular seismic source

gridfs_id

ObjectId

Yes

The _id of data file in the fs.files collection.

storage_mode

string

Yes

The storage mode of the saved data (‘file’, ‘url’ or ‘gridfs’)