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: builtins.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. [required]
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). [required]
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. [required]
evdp = F Event depth below surface (meters). [not currently used]
evel = F Event elevation (meters). [not currently used]
evla = F Event latitude (degrees north positive).
evlo = F Event longitude (degrees east positive).
f = F Fini or 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. [not currently used]
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 [required]: * 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. [currently not used]
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 = I Quality of data [not currently used]: * IGOOD (Good data) * IGLCH (Glitches) * IDROP (Dropouts) * ILOWSN (Low signal to noise ratio) * IOTHER (Other)
istreg = I Station geographic region. [not currently used]
isynth = I Synthetic data flag [not currently used]: * 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. [required]
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. [required]
nvhdr = N Header version number. Current value is the integer 6. Older version data (NVHDR < 6) are automatically updated when read into sac. [required]
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 [not currently used]
stdp = F Station depth below surface (meters). [not currently used]
stel = F Station elevation (meters). [not currently used]
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__ str(object=’‘) -> str
__module__ str(object=’‘) -> str
__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. [required]
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). [required]
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. [required]
evdp F Event depth below surface (meters). [not currently used]
evla F Event latitude (degrees north positive).
evlo F Event longitude (degrees east positive).
f F Fini or 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:
ievreg I Event geographic region. [not currently used]
ievtyp I Type of event:
iftype I Type of file [required]:
iinst I Type of recording instrument. [currently not used]
imagsrc I Source of magnitude information:
imagtyp I Magnitude type:
internal0
iqual I Quality of data [not currently used]:
istreg I Station geographic region. [not currently used]
isynth I Synthetic data flag [not currently used]:
iztype I Reference time equivalence:
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. [required]
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. [required]
nvhdr N Header version number. Current value is the integer 6.
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 [not currently used]
stdp F Station depth below surface (meters). [not currently used]
stel F Station elevation (meters). [not currently used]
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
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,
_flush_headers Flush to the header arrays any header property values that may not be
_format_header_str Produce a print-friendly string of header values for __repr__ ,
_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
__new__ Create and return a new object.
__reduce__ helper for pickle
__reduce_ex__ helper for pickle
__repr__
__sizeof__ size of object in memory, in bytes
__str__
__subclasshook__ Abstract classes can override this to customize issubclass().