obspy.io.sac.sactrace¶
Python interface to the Seismic Analysis Code (SAC) file format.
| copyright: | The Los Alamos National Security, LLC, Yannik Behr, C. J. Ammon, C. Satriano, L. Krischer, and J. MacCarthy |
|---|---|
| license: | GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html) |
The SACTrace object maintains consistency between SAC headers and manages header values in a user-friendly way. This includes some value-checking, native Python logicals (True, False) and nulls (None) instead of SAC’s 0, 1, or -12345...
SAC headers are implemented as properties, with appropriate getters and setters.
Features¶
- Read and write SAC binary or ASCII
- autodetect or specify expected byteorder
- optional file size checking and/or header consistency checks
- header-only reading and writing
- “overwrite OK” checking (‘lovrok’ header)
- Convenient access and manipulation of relative and absolute time headers
- User-friendly header printing/viewing
- Fast access to header values from attributes
- With type checking, null handling, and enumerated value checking
- Convert to/from ObsPy Traces
- Conversion from ObsPy Trace to SAC trace retains detected previous SAC header values.
- Conversion to ObsPy Trace retains the complete SAC header.
Usage examples¶
Read/write SAC files¶
# read from a binary file
sac = SACTrace.read(filename)
# read header only
sac = SACTrace.read(filename, headonly=True)
# write header-only, file must exist
sac.write(filename, headonly=True)
# read from an ASCII file
sac = SACTrace.read(filename, ascii=True)
# write a binary SAC file for a Sun machine
sac.write(filename, byteorder='big')
Build a SACTrace from a header dictionary and data array¶
Example
>>> header = {'kstnm': 'ANMO', 'kcmpnm': 'BHZ', 'stla': 40.5, 'stlo': -108.23,
... 'evla': -15.123, 'evlo': 123, 'evdp': 50, 'nzyear': 2012,
... 'nzjday': 123, 'nzhour': 13, 'nzmin': 43, 'nzsec': 17,
... 'nzmsec': 100, 'delta': 1.0/40}
>>> sac = SACTrace(data=np.random.random(100), **header)
>>> print(sac)
Reference Time = 05/02/2012 (123) 13:43:17.100000
iztype IB: begin time
b = 0.0
delta = 0.0250000...
e = 2.4750000...
evdp = 50.0
evla = -15.123000...
evlo = 123.0
iftype = itime
internal0 = 2.0
iztype = ib
kcmpnm = BHZ
kstnm = ANMO
lcalda = False
leven = True
lovrok = True
lpspol = True
npts = 100
nvhdr = 6
nzhour = 13
nzjday = 123
nzmin = 43
nzmsec = 100
nzsec = 17
nzyear = 2012
stla = 40.5
stlo = -108.23000...
Reference-time and relative time headers¶
Example
>>> sac = SACTrace(nzyear=2000, nzjday=1, nzhour=0, nzmin=0, nzsec=0,
... nzmsec=0, t1=23.5, data=np.arange(100))
>>> print(sac.reftime)
2000-01-01T00:00:00.000000Z
>>> sac.b, sac.e, sac.t1
(0.0, 99.0, 23.5)
Move reference time by relative seconds, relative time headers are preserved.
Example
>>> sac = SACTrace(nzyear=2000, nzjday=1, nzhour=0, nzmin=0, nzsec=0,
... nzmsec=0, t1=23.5, data=np.arange(100))
>>> sac.reftime -= 2.5
>>> sac.b, sac.e, sac.t1
(2.5, 101.5, 26.0)
Set reference time to new absolute time, relative time headers are preserved.
Example
>>> sac = SACTrace(nzyear=2000, nzjday=1, nzhour=0, nzmin=0, nzsec=0,
... nzmsec=0, t1=23.5, data=np.arange(100))
>>> # set the reftime two minutes later
>>> sac.reftime = UTCDateTime(2000, 1, 1, 0, 2, 0, 0)
>>> sac.b, sac.e, sac.t1
(-120.0, -21.0, -96.5)
Quick header viewing¶
Print non-null header values.
Example
>>> sac = SACTrace()
>>> print(sac)
Reference Time = 01/01/1970 (001) 00:00:00.000000
iztype IB: begin time
b = 0.0
delta = 1.0
e = 0.0
iftype = itime
internal0 = 2.0
iztype = ib
lcalda = False
leven = True
lovrok = True
lpspol = True
npts = 0
nvhdr = 6
nzhour = 0
nzjday = 1
nzmin = 0
nzmsec = 0
nzsec = 0
nzyear = 1970
Print relative time header values.
Example
>>> sac = SACTrace()
>>> sac.lh('picks')
Reference Time = 01/01/1970 (001) 00:00:00.000000
iztype IB: begin time
a = None
b = 0.0
e = 0.0
f = None
o = None
t0 = None
t1 = None
t2 = None
t3 = None
t4 = None
t5 = None
t6 = None
t7 = None
t8 = None
t9 = None
Header values as attributes¶
Great for interactive use, with (ipython) tab-completion...
sac.<tab>
sac.a sac.kevnm sac.nzsec
sac.az sac.kf sac.nzyear
sac.b sac.khole sac.o
sac.baz sac.kinst sac.odelta
sac.byteorder sac.knetwk sac.read
sac.cmpaz sac.ko sac.reftime
sac.cmpinc sac.kstnm sac.scale
sac.copy sac.kt0 sac.stdp
sac.data sac.kt1 sac.stel
sac.delta sac.kt2 sac.stla
sac.depmax sac.kt3 sac.stlo
sac.depmen sac.kt4 sac.t0
sac.depmin sac.kt5 sac.t1
sac.dist sac.kt6 sac.t2
sac.e sac.kt7 sac.t3
sac.evdp sac.kt8 sac.t4
sac.evla sac.kt9 sac.t5
sac.evlo sac.kuser0 sac.t6
sac.f sac.kuser1 sac.t7
sac.from_obspy_trace sac.kuser2 sac.t8
sac.gcarc sac.lcalda sac.t9
sac.idep sac.leven sac.to_obspy_trace
sac.ievreg sac.lh sac.unused23
sac.ievtyp sac.listhdr sac.user0
sac.iftype sac.lovrok sac.user1
sac.iinst sac.lpspol sac.user2
sac.imagsrc sac.mag sac.user3
sac.imagtyp sac.nevid sac.user4
sac.internal0 sac.norid sac.user5
sac.iqual sac.npts sac.user6
sac.istreg sac.nvhdr sac.user7
sac.isynth sac.nwfid sac.user8
sac.iztype sac.nzhour sac.user9
sac.ka sac.nzjday sac.validate
sac.kcmpnm sac.nzmin sac.write
sac.kdatrd sac.nzmsec
...and documentation (in IPython)!
sac.iztype?
Type: property
String form: <property object at 0x106404940>
Docstring:
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
Convert to/from ObsPy Traces¶
Example
>>> from obspy import read
>>> tr = read()[0]
>>> print(tr.stats)
network: BW
station: RJOB
location:
channel: EHZ
starttime: 2009-08-24T00:20:03.000000Z
endtime: 2009-08-24T00:20:32.990000Z
sampling_rate: 100.0
delta: 0.01
npts: 3000
calib: 1.0
back_azimuth: 100.0
inclination: 30.0
response: Channel Response
...
>>> sac = SACTrace.from_obspy_trace(tr)
>>> print(sac)
Reference Time = 08/24/2009 (236) 00:20:03.000000
iztype IB: begin time
b = 0.0
delta = 0.009999999...
e = 29.989999...
iftype = itime
iztype = ib
kcmpnm = EHZ
knetwk = BW
kstnm = RJOB
lcalda = False
leven = True
lovrok = True
lpspol = True
npts = 3000
nvhdr = 6
nzhour = 0
nzjday = 236
nzmin = 20
nzmsec = 0
nzsec = 3
nzyear = 2009
scale = 1.0
>>> tr2 = sac.to_obspy_trace()
>>> print(tr2.stats)
network: BW
station: RJOB
location:
channel: EHZ
starttime: 2009-08-24T00:20:03.000000Z
endtime: 2009-08-24T00:20:32.990000Z
sampling_rate: 100.0
delta: 0.01
npts: 3000
calib: 1.0
sac: AttribDict(...)
Private Functions
Warning
Private functions are mainly for internal/developer use and their API might change without notice.
| _get_e | |
| _get_kevnm | |
| _iztype_reftime | Get the new reftime for a given iztype. |
| _set_kevnm |
Classes
| BoolHeader | |
| DataHeader | |
| EnumHeader | |
| FloatHeader | |
| GeographicHeader | |
| IntHeader | |
| RelativeTimeHeader | |
| SACHeader | |
| SACTrace | Convenient and consistent in-memory representation of Seismic Analysis Code |
| StringHeader |