obspy.io.sac.sactrace.SACTrace

class SACTrace(leven=True, delta=1.0, b=0.0, e=0.0, iztype='ib', nvhdr=6, npts=0, iftype='itime', nzyear=1970, nzjday=1, nzhour=0, nzmin=0, nzsec=0, nzmsec=0, lcalda=False, lpspol=True, lovrok=True, internal0=2.0, data=None, **kwargs)[source]

Bases: object

Convenient and consistent in-memory representation of Seismic Analysis Code (SAC) files.

This is the human-facing interface for making a valid instance. For file-based or other constructors, see class methods .read and .from_obspy_trace. SACTrace instances preserve relationships between header values.

param data

Associated time-series data vector. Optional. If omitted, None is set as the instance data attribute.

type data

numpy.ndarray of float32

Any valid header key/value pair is also an optional input keyword argument. If not provided, minimum required headers are set to valid default values. The default instance is an evenly-space trace, with a sample rate of 1.0, and len(data) or 0 npts, starting at 1970-01-01T00:00:00.000000.

var reftime

Read-only reference time. Calculated from nzyear, nzjday, nzhour, nzmin, nzsec, nzmsec.

var byteorder

The byte order of the underlying header/data arrays. Raises SacError if array byte orders are inconsistent, even in the case where ‘<’ is your native order and byteorders look like ‘<’, ‘=’, ‘=’.

Any valid header name is also an attribute. See below, header, or individial attribution docstrings for more header information.

THE SAC HEADER

NOTE: All header names and string values are lowercase. Header value access should be through instance attributes.

Field Name

Type

Description

a =

F

First arrival time (seconds relative to reference time.)

az =

F

Event to station azimuth (degrees).

b =

F

Beginning value of the independent variable.

baz =

F

Station to event azimuth (degrees).

cmpaz =

F

Component azimuth (degrees, clockwise from north).

cmpinc =

F

Component incident angle (degrees, from vertical).

delta =

F

Increment between evenly spaced samples (nominal value).

depmax =

F

Maximum value of dependent variable.

depmen =

F

Mean value of dependent variable.

depmin =

F

Minimum value of dependent variable.

dist =

F

Station to event distance (km).

e =

F

Ending value of the independent variable.

evdp =

F

Event depth below surface (meters).

evel =

F

Event elevation (meters).

evla =

F

Event latitude (degrees north positive).

evlo =

F

Event longitude (degrees east positive).

f =

F

Fini/end of event time (seconds relative to reference time.)

gcarc =

F

Station to event great circle arc length (degrees).

idep =

I

Type of dependent variable:

  • IUNKN (Unknown)

  • IDISP (Displacement in nm)

  • IVEL (Velocity in nm/sec)

  • IVOLTS (Velocity in volts)

  • IACC (Acceleration in nm/sec/sec)

ievreg =

I

Event geographic region.

ievtyp =

I

Type of event:

  • IUNKN (Unknown)

  • INUCL (Nuclear event)

  • IPREN (Nuclear pre-shot event)

  • IPOSTN (Nuclear post-shot event)

  • IQUAKE (Earthquake)

  • IPREQ (Foreshock)

  • IPOSTQ (Aftershock)

  • ICHEM (Chemical explosion)

  • IQB (Quarry or mine blast confirmed by quarry)

  • IQB1 (Quarry/mine blast with designed shot info-ripple fired)

  • IQB2 (Quarry/mine blast with observed shot info-ripple fired)

  • IQMT (Quarry/mining-induced events: tremors and rockbursts)

  • IEQ (Earthquake)

  • IEQ1 (Earthquakes in a swarm or aftershock sequence)

  • IEQ2 (Felt earthquake)

  • IME (Marine explosion)

  • IEX (Other explosion)

  • INU (Nuclear explosion)

  • INC (Nuclear cavity collapse)

  • IO_ (Other source of known origin)

  • IR (Regional event of unknown origin)

  • IT (Teleseismic event of unknown origin)

  • IU (Undetermined or conflicting information)

  • IOTHER (Other)

iftype =

I

Type of file:

  • ITIME {Time series file}

  • IRLIM {Spectral file—real and imaginary}

  • IAMPH {Spectral file—amplitude and phase}

  • IXY {General x versus y data}

  • IXYZ {General XYZ (3-D) file}

iinst =

I

Type of recording instrument.

imagsrc =

I

Source of magnitude information:

  • INEIC (National Earthquake Information Center)

  • IPDE (Preliminary Determination of Epicenter)

  • IISC (International Seismological Centre)

  • IREB (Reviewed Event Bulletin)

  • IUSGS (US Geological Survey)

  • IBRK (UC Berkeley)

  • ICALTECH (California Institute of Technology)

  • ILLNL (Lawrence Livermore National Laboratory)

  • IEVLOC (Event Location (computer program) )

  • IJSOP (Joint Seismic Observation Program)

  • IUSER (The individual using SAC2000)

  • IUNKNOWN (unknown)

imagtyp =

I

Magnitude type:

  • IMB (52): Bodywave Magnitude

  • IMS (53): Surfacewave Magnitude

  • IML (54): Local Magnitude

  • IMW (55): Moment Magnitude

  • IMD (56): Duration Magnitude

  • IMX (57): User Defined Magnitude

iqual =

N

Quality of data, as integers. Enum values listed:

  • IGOOD (45) (Good data)

  • IGLCH (46) (Glitches)

  • IDROP (47) (Dropouts)

  • ILOWSN (48) (Low signal to noise ratio)

  • IOTHER (44) (Other)

istreg =

I

Station geographic region.

isynth =

I

Synthetic data flag:

  • IRLDTA (Real data)

  • ????? (Flags for various synthetic seismogram codes)

iztype =

I

Reference time equivalence:

  • IUNKN (5): Unknown

  • IB (9): Begin time

  • IDAY (10): Midnight of reference GMT day

  • IO (11): Event origin time

  • IA (12): First arrival time

  • ITn (13-22): User defined time pick n, n=0,9

ka =

K

First arrival time identification.

kcmpnm =

K

Component name.

kevnm =

K

Event name.

kf =

F

Fini or end of event time identification.

khole =

k

Hole identification if nuclear event.

kinst =

K

Generic name of recording instrument

knetwk =

K

Name of seismic network.

ko =

K

Event origin time identification.

kstnm =

K

Station name.

kt0 =

F

User defined time pick identification.

kt1 =

F

User defined time pick identification.

kt2 =

F

User defined time pick identification.

kt3 =

F

User defined time pick identification.

kt4 =

F

User defined time pick identification.

kt5 =

F

User defined time pick identification.

kt6 =

F

User defined time pick identification.

kt7 =

F

User defined time pick identification.

kt8 =

F

User defined time pick identification.

kt9 =

F

User defined time pick identification.

kuser0 =

K

User defined variable storage area 0.

kuser1 =

K

User defined variable storage area 1.

kuser2 =

K

User defined variable storage area 2.

lcalda =

L

TRUE if DIST AZ BAZ and GCARC are to be calculated from st event coordinates.

leven =

L

TRUE if data is evenly spaced.

lovrok =

L

TRUE if it is okay to overwrite this file on disk.

lpspol =

L

TRUE if station components have a positive polarity (left-hand rule).

mag =

F

Event magnitude.

nevid =

N

Event ID (CSS 3.0)

norid =

N

Origin ID (CSS 3.0)

npts =

N

Number of points per data component.

nvhdr =

N

Header version number. Current value is the integer 6. Older version data (NVHDR < 6) are automatically updated when read into sac.

nwfid =

N

Waveform ID (CSS 3.0)

nzhour =

N

GMT hour.

nzjday =

N

GMT julian day.

nzmin =

N

GMT minute.

nzmsec =

N

GMT millisecond.

nzsec =

N

GMT second.

nzyear =

N

GMT year corresponding to reference time in file.

o =

F

Event origin time (seconds relative to reference time.)

odelta =

F

Observed increment if different from nominal value.

scale =

F

Multiplying scale factor for dependent variable

stdp =

F

Station depth below surface (meters).

stel =

F

Station elevation (meters).

stla =

F

Station latitude (degrees, north positive)

stlo =

F

Station longitude (degrees, east positive).

t0 =

F

User defined time (seconds picks or markers relative to reference time).

t1 =

F

User defined time (seconds picks or markers relative to reference time).

t2 =

F

User defined time (seconds picks or markers relative to reference time).

t3 =

F

User defined time (seconds picks or markers relative to reference time).

t4 =

F

User defined time (seconds picks or markers relative to reference time).

t5 =

F

User defined time (seconds picks or markers relative to reference time).

t6 =

F

User defined time (seconds picks or markers relative to reference time).

t7 =

F

User defined time (seconds picks or markers relative to reference time).

t8 =

F

User defined time (seconds picks or markers relative to reference time).

t9 =

F

User defined time (seconds picks or markers relative to reference time).

user0 =

F

User defined variable storage area 0.

user1 =

F

User defined variable storage area 1.

user2 =

F

User defined variable storage area 2.

user3 =

F

User defined variable storage area 3.

user4 =

F

User defined variable storage area 4.

user5 =

F

User defined variable storage area 5.

user6 =

F

User defined variable storage area 6.

user7 =

F

User defined variable storage area 7.

user8 =

F

User defined variable storage area 8.

user9 =

F

User defined variable storage area 9.

Attributes

__dict__

__doc__

__module__

__weakref__

list of weak references to the object (if defined)

a

F First arrival time (seconds relative to reference time.)

az

F Event to station azimuth (degrees).

b

F Beginning value of the independent variable.

baz

F Station to event azimuth (degrees).

byteorder

The byte order of the underlying header/data arrays.

cmpaz

F Component azimuth (degrees, clockwise from north).

cmpinc

F Component incident angle (degrees, from vertical).

delta

F Increment between evenly spaced samples (nominal value).

depmax

F Maximum value of dependent variable.

depmen

F Mean value of dependent variable.

depmin

F Minimum value of dependent variable.

dist

F Station to event distance (km).

e

F Ending value of the independent variable.

evdp

F Event depth below surface (meters).

evla

F Event latitude (degrees north positive).

evlo

F Event longitude (degrees east positive).

f

F Fini/end of event time (seconds relative to reference time.)

gcarc

F Station to event great circle arc length (degrees).

idep

ievreg

I Event geographic region.

ievtyp

iftype

iinst

I Type of recording instrument.

imagsrc

imagtyp

internal0

iqual

N Quality of data, as integers.

istreg

I Station geographic region.

isynth

iztype

ka

K First arrival time identification.

kcmpnm

K Component name.

kdatrd

kevnm

K Event name.

kf

F Fini or end of event time identification.

khole

k Hole identification if nuclear event.

kinst

K Generic name of recording instrument

knetwk

K Name of seismic network.

ko

K Event origin time identification.

kstnm

K Station name.

kt0

F User defined time pick identification.

kt1

F User defined time pick identification.

kt2

F User defined time pick identification.

kt3

F User defined time pick identification.

kt4

F User defined time pick identification.

kt5

F User defined time pick identification.

kt6

F User defined time pick identification.

kt7

F User defined time pick identification.

kt8

F User defined time pick identification.

kt9

F User defined time pick identification.

kuser0

K User defined variable storage area 0.

kuser1

K User defined variable storage area 1.

kuser2

K User defined variable storage area 2.

lcalda

L TRUE if DIST AZ BAZ and GCARC are to be calculated from st event coordinates.

leven

L TRUE if data is evenly spaced.

lovrok

L TRUE if it is okay to overwrite this file on disk.

lpspol

L TRUE if station components have a positive polarity (left-hand rule).

mag

F Event magnitude.

nevid

N Event ID (CSS 3.0)

norid

N Origin ID (CSS 3.0)

npts

N Number of points per data component.

nvhdr

N Header version number.

nwfid

N Waveform ID (CSS 3.0)

nzhour

N GMT hour.

nzjday

N GMT julian day.

nzmin

N GMT minute.

nzmsec

N GMT millisecond.

nzsec

N GMT second.

nzyear

N GMT year corresponding to reference time in file.

o

F Event origin time (seconds relative to reference time.)

odelta

F Observed increment if different from nominal value.

reftime

Get or set the SAC header reference time as a UTCDateTime instance.

scale

F Multiplying scale factor for dependent variable

stdp

F Station depth below surface (meters).

stel

F Station elevation (meters).

stla

F Station latitude (degrees, north positive)

stlo

F Station longitude (degrees, east positive).

t0

F User defined time (seconds picks or markers relative to reference time).

t1

F User defined time (seconds picks or markers relative to reference time).

t2

F User defined time (seconds picks or markers relative to reference time).

t3

F User defined time (seconds picks or markers relative to reference time).

t4

F User defined time (seconds picks or markers relative to reference time).

t5

F User defined time (seconds picks or markers relative to reference time).

t6

F User defined time (seconds picks or markers relative to reference time).

t7

F User defined time (seconds picks or markers relative to reference time).

t8

F User defined time (seconds picks or markers relative to reference time).

t9

F User defined time (seconds picks or markers relative to reference time).

unused23

user0

F User defined variable storage area 0.

user1

F User defined variable storage area 1.

user2

F User defined variable storage area 2.

user3

F User defined variable storage area 3.

user4

F User defined variable storage area 4.

user5

F User defined variable storage area 5.

user6

F User defined variable storage area 6.

user7

F User defined variable storage area 7.

user8

F User defined variable storage area 8.

user9

F User defined variable storage area 9.

Public Methods

copy

from_obspy_trace

Construct an instance from an ObsPy Trace.

lh

Alias of listhdr method.

listhdr

Print header values.

read

Construct an instance from a binary or ASCII file on disk.

to_obspy_trace

Return an ObsPy Trace instance.

validate

Check validity of loaded SAC file content, such as header/data consistency.

write

Write the header and (optionally) data arrays to a SAC binary file.

Private Methods

Warning

Private methods are mainly for internal/developer use and their API might change without notice.

_allt

Shift all relative time headers by some value (addition).

_byteswap

Change the underlying byte order and dtype interpretation of the float, int, and (if present) data arrays.

_flush_headers

Flush to the header arrays any header property values that may not be reflected there, such as data min/max/mean, npts, e.

_format_header_str

Produce a print-friendly string of header values for __repr__ , .listhdr(), and .lh()

_from_arrays

Low-level array-based constructor.

_set_distances

Calculate dist, az, baz, gcarc.

Special Methods

__dir__

Default dir() implementation.

__format__

Default object formatter.

__init__

Initialize a SACTrace object using header key-value pairs and a numpy.ndarray for the data, both optional.

__init_subclass__

This method is called when a class is subclassed.

__new__

Create and return a new object.

__reduce__

Helper for pickle.

__reduce_ex__

Helper for pickle.

__repr__

Return repr(self).

__sizeof__

Size of object in memory, in bytes.

__str__

Return str(self).

__subclasshook__

Abstract classes can override this to customize issubclass().