SAC header specification, including documentation.
Header names, order, and types, nulls, as well as allowed enumerated values, are
specified here. Header name strings, and their array order are contained in
separate float, int, and string tuples. Enumerated values, and their allowed
string and integer values, are in dictionaries. Header value documentation is
in a dictionary,
DOC, for reuse throughout the package.
PySAC helper functions and data. Contains functions to validate and convert enumerated values, byteorder consistency checking, and SAC reference time reading.
Two of the most important functions in this module are
obspy_to_sac_header. These contain the conversion routines between SAC
header dictionaries and ObsPy header dictionaries. These functions control
the way ObsPy reads and writes SAC files, which was one of the main
motivations for authoring this package.
Low-level array interface to the SAC file format.
Functions in this module work directly with numpy arrays that mirror the SAC
format, and comprise much of the machinery that underlies the
The 'primitives' in this module are the float, int, and string header arrays,
the float data array, and a header dictionary. Convenience functions are
provided to convert between header arrays and more user-friendly dictionaries.
These read/write routines are very literal; there is almost no value or type checking, except for byteorder and header/data array length. File- and array- based checking routines are provided for additional checks where desired.
Reading and writing are done with
write_sac for binary SAC
write_sac_ascii for alphanumeric files.
Conversions between header dictionaries and the three SAC header arrays are done
Validation of header values and data is managed by
which can currently do six different tests.
SACTrace class, which is the main user-facing interface to the
SAC file format.
SACTrace object maintains consistency between SAC headers and manages
header values in a user-friendly way. This includes some value-checking, native
Python logicals and nulls instead of SAC's header-dependent logical/null
Reading and writing SAC files¶
PySAC can read and write evenly-spaced time-series files. It supports big or little-endian binary files, or alphanumeric/ASCII 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')
SACTrace class, SAC headers are implemented as properties, with
appropriate getters and setters. The getters/setters translate user-facing
native Python values like
None to the appropriate SAC
header values, like
'-12345 ', etc.
Header values that depend on the SAC
.data vector are calculated on-the-fly,
and fall back to the stored header value.
A convenient read-only dictionary of non-null, raw SAC header values is
SACTrace._header. Formatted non-null headers are viewable using
print(sac) or the
listhdr() methods. Relative time headers and
picks are viewable with
Reference time and relative time header handling¶
The SAC reference time is built from "nz..." time fields in the header, and it
is available as the attribute
.reftime, an ObsPy
reftime can be modified in two ways: by resetting it with a new absolute
UTCDateTime instance, or by adding/subtracting seconds from it. Modifying
reftime will also modify all relative time headers such that they are
still correct in an absolute sense. This includes
t9. This means that adjusting the
reference time does not invalidate the origin time, the first sample time, or
Here, we build a 100-second
SACTrace that starts at Y2K.
sac = SACTrace(nzyear=2000, nzjday=1, nzhour=0, nzmin=0, nzsec=0, nzmsec=0, t1=23.5, data=numpy.arange(101)) sac.reftime sac.b, sac.e, sac.t1
2000-01-01T00:00:00.000000Z (0.0, 100.0, 23.5)
Move reference time by relative seconds, relative time headers are preserved.
sac.reftime -= 2.5 sac.b, sac.e, sac.t1
(2.5, 102.5, 26.0)
Set reference time to new absolute time, two minutes later. Relative time headers are preserved.
sac.reftime = UTCDateTime(2000, 1, 1, 0, 2, 0, 0) sac.b, sac.e
(-120.0, -20.0, -96.5)