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)

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 obspy.io.sac.util.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, obspy.io.sac.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

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.

SACTrace._allt(shift)

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

Similar to SAC’s “chnhdr allt”.

Note

This method is triggered by setting an instance’s iztype or changing its reference time, which is the most likely use case for this functionality. If what you’re trying to do is set an origin time and make a file origin-based:

SAC> CHNHDR O GMT 1982 123 13 37 10 103 SAC> LISTHDR O O 123.103 SAC> CHNHDR ALLT -123.103 IZTYPE IO

…it is recommended to just make sure your target reference header is set and correct, and set the iztype:

>>> from obspy import UTCDateTime
>>> from obspy.core.util import get_example_file
>>> file_ = get_example_file("test.sac")
>>> sac = SACTrace.read(file_)
>>> sac.o = UTCDateTime(year=1982, julday=123,
...                     hour=13, minute=37,
...                     second=10, microsecond=103)
>>> sac.iztype = 'io'

The iztype setter will deal with shifting the time values.

SACTrace._byteswap()

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

SACTrace._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.

SACTrace._format_header_str(hdrlist='all')

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

classmethod SACTrace._from_arrays(hf=None, hi=None, hs=None, data=None)

Low-level array-based constructor.

This constructor is good for getting a “blank” SAC object, and is used in other, perhaps more useful, alternate constructors (“See Also”). No value checking is done and header values are completely overwritten with the provided arrays, which is why this is a hidden constructor.

Parameters:

• hf (numpy.ndarray of floats) – SAC float header array

• hi (numpy.ndarray of ints) – SAC int header array

• hs (numpy.ndarray of str) – SAC string header array

• data – SAC data array, optional.

If omitted or None, the header arrays are intialized according to obspy.io.sac.arrayio.init_header_arrays(). If data is omitted, it is simply set to None on the corresponding SACTrace.

Example

>>> sac = SACTrace._from_arrays()
>>> print(sac)  
Reference Time = XX/XX/XX (XXX) XX:XX:XX.XXXXXX
    iztype not set
lcalda     = True
leven      = False
lovrok     = False
lpspol     = False

SACTrace._set_distances(force=False)

Calculate dist, az, baz, gcarc. If force=True, ignore lcalda. Raises SacHeaderError if force=True and geographic headers are unset.

Special Methods

SACTrace.__delattr__(name, /)

Implement delattr(self, name).

SACTrace.__dir__()

Default dir() implementation.

SACTrace.__eq__(value, /)

Return self==value.

SACTrace.__format__(format_spec, /)

Default object formatter.

SACTrace.__ge__(value, /)

Return self>=value.

SACTrace.__getattribute__(name, /)

Return getattr(self, name).

SACTrace.__gt__(value, /)

Return self>value.

SACTrace.__hash__()

Return hash(self).

SACTrace.__init__(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)

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

..rubric:: Example

>>> sac = SACTrace(nzyear=1995, nzmsec=50, data=np.arange(100))
>>> print(sac)  
Reference Time = 01/01/1995 (001) 00:00:00.050000
   iztype IB: begin time
b          = 0.0
delta      = 1.0
e          = 99.0
iftype     = itime
internal0  = 2.0
iztype     = ib
lcalda     = False
leven      = True
lovrok     = True
lpspol     = True
npts       = 100
nvhdr      = 6
nzhour     = 0
nzjday     = 1
nzmin      = 0
nzmsec     = 50
nzsec      = 0
nzyear     = 1995

SACTrace.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

SACTrace.__le__(value, /)

Return self<=value.

SACTrace.__lt__(value, /)

Return self<value.

SACTrace.__ne__(value, /)

Return self!=value.

SACTrace.__new__(**kwargs)

SACTrace.__reduce__()

Helper for pickle.

SACTrace.__reduce_ex__(protocol, /)

Helper for pickle.

SACTrace.__repr__()

SACTrace.__setattr__(name, value, /)

Implement setattr(self, name, value).

SACTrace.__sizeof__()

Size of object in memory, in bytes.

SACTrace.__str__()

SACTrace.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).