SAC Data File Format

SAC Data File Format
Using SAC
Using SAC
Commands:
A - Z
Functional
Subprocesses:
SPE
SSS
SAC/IRIS
SAC Data File Format
Overview
This section discusses the contents of the SAC data file, describes the binary
and alphanumeric formats of this file, and documents the SAC header in detail.
Since version 100.0, SAC can handle binary data files in either endian (byte
order), so big-endian systems (Sun Solaris, Mac PPC) can read SAC data files
written on little-endian systems (Linux, MAC i686, Cygwin) and vice versa.
Each signal is stored on disk in a separate SAC data file. Through SAC
version 101.6a, these files contain a fixed length header section followed by
one or two data sections. The header contains floating point, integer, logical,
and character fields. Evenly spaced data files have only one data section which
contains the dependent variable. Unevenly spaced data and spectral data files
contain two data sections. For unevenly spaced data, the first data section
contains the dependent variable and the second contains the independent
variable. For spectral files the first component is either the amplitude or the
real component and the second component is either the phase or imaginary
component.
All reals in the SAC header and data sections are single-precision (32
bits, 4 bytes). As discussed in the section on precision in
TUTORIAL
, although
having single-precision for the data is sufficient, having only
single-precision for time and distance variables in the header is no
longer good enough to handle many modern data sets. SAC version
102.0 solves this problem. The header is unchanged, but a "footer" is
added with 22 header variables in double-precision. Version 102.0 can
handle "old" SAC data files with no footer or files with a footer, so
there is complete compatibility. SAC v102.0 distinguishes between
"old" and "new" files by the header variable NVHDR: if NVHDR = 6, the
SAC file is in "old" format, if NVHDR = 7, it is in "new" format with
a footer. See see the section on
Floating-Point Precision in SAC
in
TUTORIAL
for a more detailed discussion.
SAC Binary Format for NVHDR = 6
The binary format is the most common one use. It is is the default format in
the
READ
and
WRITE
commands and in the subroutine library (RSAC1, RSAC2,
WSAC1, WSAC2, WSAC0.) These are binary (unformatted) files.
Structure of SAC Binary Data File for NVHDR = 6
Header Section
First Data Section
Second Data Section (if present)
start word: 0
start word: 158
start word: 158+NPTS
word length: 158
word length: NPTS
word length: NPTS
see table
dependent variable
amplitude
real component
independent variable unevenly spaced
phase
imaginary component
SAC Binary Header
The following table shows the contents and layout of the SAC binary data file
header. The W and T columns give the beginning word and header data type for
the header variables named on that line. These header variables and data types
are described later in this section. If the name is INTERNAL then that
variable is internal to SAC and not normally of interest to the user. If the
name is UNUSED then that variable is not currently being used. For any given
file, some of these variables will not have meaningful values. These are
refered to as "undefined variables" for that file. For each data type, a
special value signifies this undefined state. They are listed in a table at
the end of this section.
Header Data Types
This table lists the header types and their definitions. The third
column lists the special value used to signify that a particular
header variable is undefined in a particular file.
Type
Definition
Undefined
Description
Floating
-12345.0
Single precision.
Integer
-12345
Name begins with an "N".
Enumerated
-12345
Name begins with an "I". Has a limited set
of integer values. Each value is given a
specific name. Each value represents a
specific condition. Subroutines use the
equivalent alphanumeric name.
Logical
FALSE
Name begins with an "L". Value is either
TRUE or FALSE.
Alphanumeric
"-12345.."
Name begins with a "K". Either 8 or 16
characters long.
Auxilary
Not really in the header.
Derived from other header fields.
Header Variables
Word
Type
NAMES
DELTA
DEPMIN
DEPMAX
UNUSED
ODELTA
INTERNAL
10
T0
T1
T2
T3
T4
15
T5
T6
T7
T8
T9
20
RESP0
RESP1
RESP2
RESP3
25
RESP4
RESP5
RESP6
RESP7
RESP8
30
RESP9
STLA
STLO
STEL
STDP
35
EVLA
EVLO
EVEL
EVDP
MAG
40
USER0
USER1
USER2
USER3
USER4
45
USER5
USER6
USER7
USER8
USER9
50
DIST
AZ
BAZ
GCARC
INTERNAL
55
INTERNAL
DEPMEN
CMPAZ
CMPINC
XMINIMUM
60
XMAXIMUM
YMINIMUM
YMAXIMUM
UNUSED
UNUSED
65
UNUSED
UNUSED
UNUSED
UNUSED
UNUSED
70
NZYEAR
NZJDAY
NZHOUR
NZMIN
NZSEC
75
NZMSEC
NVHDR
NORID
NEVID
NPTS
80
INTERNAL
NWFID
NXSIZE
NYSIZE
UNUSED
85
IFTYPE
IDEP
IZTYPE
UNUSED
IINST
90
ISTREG
IEVREG
IEVTYP
IQUAL
ISYNTH
95
IMAGTYP
IMAGSRC
IBODY
UNUSED
UNUSED
100
UNUSED
UNUSED
UNUSED
UNUSED
UNUSED
105
LEVEN
LPSPOL
LOVROK
LCALDA
UNUSED
110
KSTNM
KEVNM*
116
KHOLE
KO
KA
122
KT0
KT1
KT2
128
KT3
KT4
KT5
134
KT6
KT7
KT8
140
KT9
KF
KUSER0
146
KUSER1
KUSER2
KCMPNM
152
KNETWK
KDATRD
KINST
KEVNM is 16 characters (4 words, 16 bytes) long.
All other K fields are 8 characters (2 words, 8 bytes) long.
Structure of SAC Binary Data File for NVHD = 7
The only difference between a SAC binary data file with NVHDR = 6 and
one with NVHDR = 7 is the addition of a "footer" following the data
section(s). The footer is comprised of 22 double-precision (64-bit)
floating point variables: DELTA, B, E, O, A, T0 ... T9, F, EVLO, EVLA,
STLO, STLA, SB, and SDELTA. The names are the same as in the header;
SAC distinguishes between the single- and double-precision variables
in internal calculations by their location in the file.
SAC Alphanumeric Format
This file is essentially the alphanumeric equivalent of the SAC binary data
file. The header section is stored on the first 30 80-character lines. For both
NVHDR = 6 and NVHDR = 7, this is followed by one or two data sections. The data
are in 5G15.7 format. The following table shows the line number, formats and
names of the variables on the header section lines.
LINE
FORMAT
NAMES
01
(5G15.7)
DELTA
DEPMIN
DEPMAX
UNUSED
ODELTA
02
(5G15.7)
INTERNAL
03
(5G15.7)
T0
T1
T2
T3
T4
04
(5G15.7)
T5
T6
T7
T8
T9
05
(5G15.7)
RESP0
RESP1
RESP2
RESP3
06
(5G15.7)
RESP4
RESP5
RESP6
RESP7
RESP8
07
(5G15.7)
RESP9
STLA
STLO
STEL
STDP
08
(5G15.7)
EVLA
EVLO
EVEL
EVDP
MAG
09
(5G15.7)
USER0
USER1
USER2
USER3
USER4
10
(5G15.7)
USER5
USER6
USER7
USER8
USER9
11
(5G15.7)
DIST
AZ
BAZ
GCARC
SB
12
(5G15.7)
SDELTA
DEPMEN
CMPAZ
CMPINC
XMINIMUM
13
(5G15.7)
XMAXIMUM
YMINIMUM
YMAXIMUM
ADJTM
UNUSED
14
(5G15.7)
UNUSED
UNUSED
UNUSED
UNUSED
UNUSED
15
(5I10)
NZYEAR
NZJDAY
NZHOUR
NZMIN
NZSEC
16
(5I10)
NZMSEC
NVHDR
NORID
NEVID
NPTS
17
(5I10)
NSNPTS
NWFID
NXSIZE
NYSIZE
UNUSED
18
(5I10)
IFTYPE
IDEP
IZTYPE
UNUSED
IINST
19
(5I10)
ISTREG
IEVREG
IEVTYP
IQUAL
ISYNTH
20
(5I10)
IMAGTYP
IMAGSRC
IBODY
UNUSED
UNUSED
21
(5I10)
UNUSED
UNUSED
UNUSED
UNUSED
UNUSED
22
(5I10)
LEVEN
LPSPOL
LOVROK
LCALDA
UNUSED
23
(A8,A16)
KSTNM
KEVNM
24
(3A8)
KHOLE
KO
KA
25
(3A8)
KT0
KT1
KT2
26
(3A8)
KT3
KT4
KT5
27
(3A8)
KT6
KT7
KT8
28
(3A8)
KT9
KF
KUSER0
29
(3A8)
KUSER1
KUSER2
KCMPNM
30
(3A8)
KNETWK
KDATRD
KINST
SAC Alphanumeric Data File Example
The header section and first five lines of the data section of a sample SAC
alphanumeric data file is shown below. You can reproduce this file (with the
entire data section) on your system by executing the following commands:
SAC> FUNCGEN SEISMOGRAM
SAC> LH
SAC> CH NVDHR 7
SAC> WRITE ALPHA TEMP1
You can read this alphanumeric file directly into SAC with the following commands:
SAC> READ TEMP1
SAC> LH
SAC knows the difference between an alphanumeric and binary SAC files
and should be able to read them directly. You can specify an ALPHA
flag to the
READ
command for backwards compatibility:
SAC> READ ALPHA TEMP1
SAC> LH
Listed next are the first lines of TEMP1 -- header plus first 8 lines
of data and ending with the 22 lines of the footer (one line per
variable).:
0.01000000 -1.569280 1.520640 -12345.00 -12345.00
9.459999 19.45000 -41.43000 10.46400 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 48.00000 -120.0000 -12345.00 -12345.00
48.00000 -125.0000 -12345.00 15.00000 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
373.0627 88.14721 271.8528 3.357465 -12345.00
-12345.00 -0.09854718 0.000000 0.000000 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
-12345.00 -12345.00 -12345.00 -12345.00 -12345.00
1981 88 10 38 14
0 7 0 0 1000
-12345 -12345 -12345 -12345 -12345
1 50 9 -12345 -12345
-12345 -12345 42 -12345 -12345
-12345 -12345 -12345 -12345 -12345
-12345 -12345 -12345 -12345 -12345
1 1 1 1 0
CDV K8108838
-12345 -12345 -12345
-12345 -12345 -12345
-12345 -12345 -12345
-12345 -12345 -12345
-12345 -12345 -12345
-12345 -12345 -12345
-12345 -12345 -12345
-0.09728001 -0.09728001 -0.09856002 -0.09856002 -0.09728001
-0.09600000 -0.09472002 -0.09344001 -0.09344001 -0.09344001
-0.09344001 -0.09344001 -0.09472002 -0.09472002 -0.09344001
-0.09344001 -0.09216000 -0.09216000 -0.09216000 -0.09216000
-0.09088002 -0.09088002 -0.09216000 -0.09344001 -0.09472002
-0.09472002 -0.09472002 -0.09472002 -0.09472002 -0.09472002
-0.09344001 -0.09344001 -0.09216000 -0.09088002 -0.09088002
-0.09216000 -0.09216000 -0.09216000 -0.09344001 -0.09472002
....
0.0099999997764825821
9.4599990844726562
19.449998861178756
-41.430000305175781
10.46399974822998
-12345
-12345
-12345
-12345
-12345
-12345
-12345
-12345
-12345
-12345
-12345
-125
48
-120
48
-12345
-1234
SAC Header Variables
This table lists the header variables, their types, and descriptions. They are
grouped by category: required fields, time fields, phase picks, instrument
parameters, station parameters, event parameters, misc. The header types are
defined in the second table.
Name
Type
Description
NPTS
Number of points per data component. [required]
NVHDR
Header version number. Current value is the integer 7.
Older version data (NVHDR < 6) are automatically updated
when read into sac. In SAC v102.0, one can still use
NVHDR = 6. To have double-precision capability,
NVHDR = 7 [required]
Beginning value of the independent variable. [required]
Ending value of the independent variable. [required]
IFTYPE
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}
LEVEN
TRUE if data is evenly spaced. [required]
DELTA
Increment between evenly spaced samples
(nominal value). [required]
ODELTA
Observed increment if different from nominal value.
IDEP
Type of dependent variable:
IUNKN (Unknown)
IDISP (Displacement in nm)
IVEL (Velocity in nm/sec)
IACC (Acceleration in nm/sec/sec)
NOTE
Others use SI units for IDISP, IVEL, IACC.
IVOLTS (Velocity in volts)
DEPMIN
Minimum value of dependent variable.
DEPMAX
Maximum value of dependent variable.
DEPMEN
Mean value of dependent variable.
NZYEAR
GMT year corresponding to reference (zero) time in file.
NZJDAY
GMT Day of the Year.
NZHOUR
GMT hour.
NZMIN
GMT minute.
NZSEC
GMT second.
NZMSEC
GMT millisecond.
NZDTTM
GMT date-time array. Six element array equivalenced to
NZYEAR, NZJDAY, NZHOUR, NZMIN, NZSEC, and NZMSEC.
KZDATE
Alphanumeric form of GMT reference date. Derived from
NZYEAR and NZJDAY.
KZTIME
Alphanumeric form of GMT reference time. Derived from
NZHOUR, NZMIN, NZSEC, and NZMSEC.
IZTYPE
Reference time equivalence:
IUNKN (Unknown)
IB (Begin time)
IDAY (Midnight of refernece GMT day)
IO (Event origin time)
IA (First arrival time)
ITn (User defined time pick n, n=0,9)
Event origin time (seconds relative to reference time.)
KO
Event origin time identification.
NSNPTS
Number of points of original time series file (Stored NPTS).
SB
Begin value of orignal time series file (Stored B).
SDELTA
Time increment in original time series file (Stored DELTA).
Phase Picks
Name
Type
Description
First arrival time (seconds relative to reference time.)
KA
First arrival time identification.
Fini or end of event time (seconds relative to reference time.)
KF
Fini identification.
Tn
User defined time picks or markers, n = 0 - 9
(seconds relative to reference time).
KT{n}
A User defined time pick identifications, n = 0 - 9.
Instrument Fields
Name
Type
Description
KINST
Generic name of recording instrument.
IINST
Type of recording instrument. [not currently used]
RESPn
Instrument response parameters, n=0,9. [not currently used]
Station Fields
Name
Type
Description
KNETWK
Name of seismic network.
KSTNM
Station name.
ISTREG
Station geographic region. [not currently used]
STLA
Station latitude (degrees, north positive)
STLO
Station longitude (degrees, east positive).
STEL
Station elevation above sea level (meters). [not currently used]
STDP
Station depth below surface (meters). [not currently used]
CMPAZ
Component azimuth (degrees clockwise from north).
CMPINC
Component incident angle (degrees from upward vertical;
SEED/MINISEED uses dip: degrees from horizontal down).
KCMPNM
Channel name. SEED volumes use three character names, and
the third is the component/orientation. For horizontals,
the current trend is to use 1 and 2 instead of N and E.
KSTCMP
Station component. Derived from KSTNM, CMPAZ, and CMPINC.
LPSPOL
TRUE if station components have a positive polarity
(left-hand rule).
Event Fields
Name
Type
Description
KEVNM
Event name.
IEVREG
Event geographic region. [not currently used]
EVLA
Event latitude (degrees, north positive).
EVLO
Event longitude (degrees, east positive).
EVEL
Event elevation (meters). [not currently used]
EVDP
Event depth below surface (kilommeters -- previously meters)
MAG
Event magnitude.
IMAGTYP
Magnitude type:
IMB (Bodywave Magnitude)
IMS (Surfacewave Magnitude)
IML (Local Magnitude)
IMW (Moment Magnitude)
IMD (Duration Magnitude)
IMX (User Defined Magnitude)
IMAGSRC
Source of magnitude information:
INEIC (National Earthquake Information Center)
IPDE (Preliminary Determination of Epicenter)
IISC (Internation 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)
IEVTYP
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)
IQBX (Quarry or mine blast - single shot)
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)
IL (Local event of unknown origin)
IR (Regional event of unknown origin)
IT (Teleseismic event of unknown origin)
IU (Undetermined or conflicting information)
IOTHER (Other)
NEVID
Event ID (CSS 3.0)
NORID
Origin ID (CSS 3.0)
NWFID
Waveform ID (CSS 3.0)
KHOLE
Nuclear: hole identifier; Other: location identifier (LOCID).
DIST
Station to event distance (km).
AZ
Event to station azimuth (degrees).
BAZ
Station to event azimuth (degrees).
GCARC
Station to event great circle arc length (degrees).
IBODY
Body / Spheroid definition used in Distance Calculations
undef / -12345 Sac Historical Spheroid version
a: 6378160.0 m
f: 0.00335293
Important Note
: For consistency with previous versions,
it is best to leave the IBODY as undefined.
This is
not
WGS-84, see IEARTH
ISUN / 98 Sun
Meftah2015
Rozelot2001
a: 696000000.0 m
f: 8.189e-6
IMERCURY / 99 Mercury
IAU2000
IAU-WGCCRE
a: 2439700.0 m
f: 0.0
IVENUS / 100 Venus
IAU2000
IAU-WGCCRE
a: 6051800.0 m
f: 0.0
IEARTH / 101 WGS-84, EPSG:4325
a: 6378137.0 m
f: 1.0 / 298.257223563 ( = 0.0033528106647474805)
IMOON / 102 Moon
IAU2000
IAU-WGCCRE
a: 1737400.0 m
f: 0.0
IMARS / 103 Mars
IAU2000
IAU-WGCCRE
a: 3396190.0 m
f: 1.0 / 169.89444722361179 ( = 0.005886007555525457)
Miscellaneous Fields
Name
Type
Description
LCALDA
TRUE if DIST, AZ, BAZ, and GCARC are to be
calculated from station and event coordinates.
IQUAL
Quality of data [not currently used]:
IGOOD (Good data)
IGLCH (Glitches)
IDROP (Dropouts)
ILOWSN (Low signal to noise ratio)
IOTHER (Other)
ISYNTH
Synthetic data flag [not currently used]:
IRLDTA (Real data)
????? (Flags for various synthetic seismogram codes)
KDATRD
Date data was read onto computer.
USER{n}
User defined variable storage area, n = 0,9.
KUSER{n}
User defined variable storage area, n = 0,2.
LOVROK
TRUE if it is okay to overwrite this file on disk.
NXSIZE
Spectral Length (Spectral files only)
NYSIZE
Spectral Width (Spectral files only)
XMINIMUM
Minimum value of X (Spectral files only)
XMAXIMUM
Maximum value of X (Spectral files only)
YMINIMUM
Minimum value of Y (Spectral files only)
YMAXIMUM
Maximum value of Y (Spectral files only)
Enumerated Header Field Values
The enumerated header field values are stored in the header as
integers. Their names and values are given in the table below.
Name
ID
itime
01
irlim
02
iamph
03
ixy
04
iunkn
05
idisp
06
ivel
07
iacc
08
ib
09
iday
10
io
11
ia
12
it0
13
it1
14
it2
15
it3
16
it4
17
it5
18
it6
19
it7
20
it8
21
it9
22
iradnv
23
itannv
24
iradev
25
itanev
26
inorth
27
ieast
28
ihorza
29
idown
30
iup
31
illlbb
32
iwwsn1
33
iwwsn2
34
ihglp
35
isro
36
inucl
37
ipren
38
ipostn
39
iquake
40
ipreq
41
ipostq
42
ichem
43
iother
44
igood
45
iglch
46
idrop
47
ilowsn
48
irldta
49
ivolts
50
imb
52
ims
53
iml
54
imw
55
imd
56
imx
57
ineic
58
ipdeq
59
ipdew
60
ipde
61
iisc
62
ireb
63
iusgs
64
ibrk
65
icaltech
66
illnl
67
ievloc
68
ijsop
69
iuser
70
iunknown
71
iqb
72
iqb1
73
iqb2
74
iqbx
75
iqmt
76
ieq
77
ieq1
78
ieq2
79
ime
80
iex
81
inu
82
inc
83
io_
84
il
85
ir
86
it
87
iu
88
ieq3
89
ieq0
90
iex0
91
iqc
92
iqb0
93
igey
94
ilit
95
imet
96
iodor
97
isun
98
imercury
99
ivenus
100
iearth
101
imoon
102
imars
103
REFERENCES
[IAU2000]
Seidelmann, P., V. Abalakin, M. Bursa, M. Davies, C. De Bergh, J. Lieske,
J. Oberst, J. Simon, E. Standish, P. Stooke, et al. (2002), Report of the
IAU/IAG working group on cartographic coordinates and rotational elements of the
planets and satellites: 2000, Celestial Mechanics and Dynamical Astronomy, 82 (1), 83–111.
[IAU-WGCCRE]
[Meftah2015]
Meftah, M., A. Irbah, A. Hauchecorne, T. Corbard,
S. Turck-Chi`eze, J.-F. Hochedez, P. Boumier, A. Cheva- lier,
S. Dewitte, S. Mekaoui, et al. (2015), On the determination and
constancy of the solar oblateness, Solar Physics, 290(3), 673–687.
8.189e-6 (Flattening)
[Rozelot2001]
Rozelot, J. P., Godier, S., & Lefebvre, S. (2001). On the theory of the
oblateness of the Sun. Solar Physics, 198(2), 223-240.
8.33e-6 (Flattening)
6.50e-6 - 10.20e-6 (Flattening Range)
LATEST REVISION
Version 102.0
Using SAC
Commands:
A - Z
Functional
Subprocesses:
SPE
SSS
SAC/IRIS