index| modules| next| previous
  1. ObsPy Documentation (1.2.0)
  2. ObsPy Library Reference
  3. obspy.io.sac - SAC read and write support for ObsPy
  4. obspy.io.sac.sactrace

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.
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__ 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.
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. Enum values listed:
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. 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
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
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().