Overview

SAC, the acronym for Seismic Analysis Code, was

developed at Lawrence Livermore National Laboratory,
University of California, in the early 1980's.
It is a command-driven program generally
implemented on many types of UNIX operating systems
and has become a standard data manipulation tool in
seismology.
Its binary data format is one of the principle data
formats used today in storing and manipulating
seismological time series data.
With SAC:
one can interactively read seismogram data and
perform many standard data processing operations,
such as
filtering
time picks
amplitude picks
correlation
Fourier transforms
seismic instrument corrections
particle motion rotation
trace envelopes
spectral ratios
linear regressions
frequency-wavenumber analysis

and create a variety of plots of the data and

resulting analysis

There are also utility programs that can be used to

view plots or to convert SAC graphics files into other
formats such as PostScript.
These files can then be used with other graphics
programs such as Adobe Illustrator to construct more
complex figures.
One can also interact directly with the UNIX operating
system while using SAC, calling system functions or
running secondary programs as needed.
Macros (scripts of SAC commands) can be combined
with CShell scripts for automating seismic processing.
SAC binary data files can be written and read from
fortran and C programs using input/output routines
contained in the SAC library, "sac.a".
last modified 3/05/01

CERI Implementation
SAC is part of CERI's supported software.
On login, each user sources the "ceri_common.cshrc"
file which sets the following UNIX environmental
variables. These variables are needed by the SAC
program to access internal databases.

##########################################
#The Following are sac Variables#
##########################################
setenv SACDIR /ceri_common/supported
/sac2000/sac
set path = ($path $SACDIR/bin)
setenv SACCFLAGS "-w -DBSD4.2 -DSUNOS4.0"
setenv SACFFLAGS "-w -Nn2000 -Nq300"
setenv SACPFLAGS "-P"
setenv SACXWINDOWS x11
setenv SACAUX $SACDIR/aux
setenv SACGRAPHICSDEVICE X
setenv LD_LIBRARY_PATH
$SACDIR/lib:$LD_LIBRARY_PATH
#

Important Note:
At this time (3/05/01) CERI does not have a generally
available copy of the SAC library, "sac.a" or "sacio.a",
that can be used in compiling fortran or C programs on
SUN Solaris systems. A copy is available at /tetemeko
/local/sac/lib/sac.a if you need to compile programs
with SAC I/O routines.

The SAC program is started by typing, for example:

system prompt> sac2000

You then see:

NEW SEISMIC ANALYSIS CODE [March 28, 1996 (Version 00.51)]
Copyright 1995 Regents of the University of California
SAC>

And SAC is ready to go!

last modified 3/05/01

SAC Commands
SAC commands are entered at the command prompt.
Generally data are constructed within SAC or read
from a file before other operations are attempted.
Alternatively, sometimes certain SAC commands are
invoked to prepare a certain kind of data operation or
to set up parameters for a plot.
The definitive website on SAC commands is located at
http://www.llnl.gov/sac/ .
Here is an alphabetical list of commands contained
within SAC. Note, that a command may have a
shorthand form (on the left of each word pair).
lds
lds
listdatasets
lds
fortran
line
external_interface line
linefit
fft
fft
absolutevalue
linefit
dft
fft
absolutevalue
linlin
fileid
fileid
abs
abs
linlin
filterdesign
add
add
linlog
filterdesign
addf
addf
linlog
fd
am
keepam
listhdr
filterdesign
apk
apk
listhdr
fir
fir
axes
axes
lh
floor
floor
axis
axes
listhdr
funcgen
load
funcgen
fg
funcgen load
loadctable
loadctable

qdp
qdp
quantize
quantize
quit
quit
done
quit
end
quit
exit
quit
q
quit
quitsub
quitsub

vspace
vspace
vsp
vspace

lct
loadctable
log
log
log10
log10
loglab
loglab
loglin
loglin
loglog
loglog
lowpass
lowpass
lp
lowpass
bandpass
bandpass
bp
bandpass
bandrej
bandrej
br
bandrej
bbfk
bbfk
beam
beam
beamform
beam
begindevices
begindevices
bd
begindevices
begg
begindevices
bg
begindevices
beginframe
beginframe
begfr
beginframe
bf
beginframe
beginwindow
beginwindow
bw
beginwindow
benioff
benioff
binoperr

macro
macro
m
macro
map
map
markptp
markptp
markp
markptp
marktimes
getbb
getbb marktimes
gmap
gmap markt
marktimes
grayscale
markvalue
grayscale
gs
grayscale markvalue
markv
grid
grid
group
group markvalue
merge
gtext
gtext
merge
gt
gtext
message
message
mes
message
mtw
mtw
mul
mul
mulf
mulf
mulomega

read
read
r
read
readalpha
readalpha
ra
readalpha
readbbf
readbbf
rbbf
readbbf
readcss
readcss
rcss
readcss
readerr
readerr
rerr
readerr
readhdr
readhdr
rh
readhdr
readsdd
readsdd
rsdd
readsdd
readsp
readsp
rsp
readsp
rename
rename
report

wait
wait
wcss
writecss
whpf
whpf
width
width
wiener
wiener
wnr
wiener
wild
wild
window
window
write
write
w
write
writebbf
writebbf
wbbf
writebbf
writecss
writecss
wcss
writecss
writehdr
writehdr
wh

binoperr
boec
binoperr
border

mulomega

report
reverse
reverse
rglitches
rglitches
rmean
rmean
rms
rms
rotate
rotate
rot
rotate
rq
rq
rtrend
rtrend
rtr
rtrend

writehdr
writesdd
writesdd
writesp
writesp
wsp
writesp

news
news
nplotc
nplotc
null
null

scallop
scallop
scp
scallop
setbb
setbb
setdevice
setdevice
setmacro
setmacro
sgf
sgf
hcd
sgf
smooth
smooth
spe
spe
spectrogram
spectrogram
spg
spectrogram
sqr
sqr
sqrt
sqrt
sss
sss
stretch
stretch
sub
sub
subf
subf
symbol
symbol
sym
symbol
synchronize
synchronize
synch
synchronize

xdiv
xdiv
xfudge
xfudge
xfull
xfull
xgrid
xgrid
xlabel
xlabel
xlabl
xlabel
xlim
xlim
xlin
xlin
xlog
xlog
xvport
xvport
xvp
xvport
xwind
xvport

border

capf
capf
ccipf
capf
cds
cds
currentdataset
cds
chnhdr
chnhdr
ch
chnhdr
chpf
chpf
color
color
col
color
comcor
comcor
contour
contour
cont
contour
convert
convert
conv
convert
convolve
convolve
convo
convolve
copy
copy
copyhdr
copyhdr
correlate
correlate
cor
correlate
cut
cut
cuterr
cuterr

hanning
hanning
han
hanning
help
help
h
help
highpass
highpass
hp
highpass
hilbert
hilbert

syntax
syntax
syn
syntax
systemcommand
systemcommand
sc
systemcommand

datagen
datagen
dg
datagen
decimate
decimate
delete
delete
dif
dif
div
div
divf
divf
divomega
divomega

echo
echo
enddevices
enddevices
ed
enddevices
eg
enddevices
endg
enddevices
endframe
endframe
ef
endframe
endfr
endframe
envelope

ifft
ifft
idft
ifft
image
image
inicm
inicm
installmacro
installmacro
int
int
interpolate
interpolate
interp
interpolate

oapf
oapf
ocipf
oapf
ohpf
ohpf

keepam
keepam
khronhite
khronhite

pause
pause
picks
picks
plabel
plabel
plot
p
plot1
plot1
p1
plot1
plot2
plot2
p2

taper
taper
ticks
ticks
title
title
trace
trace
transcript
transcript
transfer
transfer
trans
transfer
transfertable
transfertable
tsize
tsize

plot unsetbb
plot unsetbb
unwrap
unwrap

ydiv
ydiv
yfudge
yfudge
yfull
yfull
ygrid
ygrid
ylabel
ylabel
ylabl
ylabel
ylim
ylim
ylin
ylin
ylog
ylog
yvport
yvport
yvp
yvport
ywind
yvport

zcolors
zcolors
zlabels
zlabels
zlevels
zlevels
zlines
zlines
zticks
zticks

envelope
erase
erase
era
erase
evaluate
evaluate
eval
evaluate
exp
exp
exp10
exp10
external
external_interface
ext
external_interface

plot2
plotalpha
plotalpha
pa
plotalpha
plotc
plotc
pc
plotc
plotctable
plotctable
plotdy
plotdy
plotpk
plotpk
ppk
plotpk
plotpktable
plotpktable
plotpm
plotpm
ppm
plotpm
plotsp
plotsp
psp
plotsp
plotxy
plotxy
pxy
plotxy
production
production
prod
production

A description of each command can be obtained while

in the SAC program by typing
SAC> help commandname

For example, here is what you would see for the

command, abs:

SAC> help abs

SAC Command Reference Manual

ABS

SUMMARY:
Takes the absolute value of each data point.
SYNTAX:
ABS
ERROR MESSAGES:
1301: No data files read in.
1307: Illegal operation on spectral file
HEADER CHANGES:
DEPMIN, DEPMAX, DEPMEN
LATEST REVISION:
January 8, 1983 (Version 8.0)
SAC>

SAC commands can be grouped into several functional

categories:
Executive Function Module, e.g.,
manipulate blackboard variables
help
macro
quit
Data-Set Module
Data File Module, e.g.,
read
cut
listhdr
Graphics Environment Module, e.g.,
xvport

title
Graphics Control Module, e.g.,
begindevices
enddevices
Graphics Action Module, e.g.,
plot
plot1
plotpk
Spectral Analysis Module, e.g.,
fft
plotsp
bandpass
Unary Operations Module, e.g.,
add
mul
sqrt
Binary Operations Module, e.g.,
merge
addf
divf
Signal Correction Module, e.g.,
rtrend
rmean
rotate
decimate
Event Analysis Module, e.g.,
ohpf
oapf
Signal Measurement Module, e.g.,
rms
marktimes
XYZ (3D) Data Module, e.g.,

spectrogram
contour
Instrument Correction Module
transfer
Subprocess Invoking Module
spe (Spectral Estimation Subprocess)
sss (Signal Stacking Subprocess)
Analysis Tools
filterdesign
FK Spectrum
bbfk
beam
map

As you can probably tell, there are many things that

you can tell the SAC program to do. Usually, it pays to
"play" with SAC, executing commands to process a few
seismograms to understand what you want to do with
the data. Once you have your processing clarified, the
commands can be written into a file and used as a
script - the SAC macro - to process more data, or to keep
a record of exactly what you did to the data.
last modified 3/05/01

SAC Data Formats

SAC can read data in a variety of formats:
SAC Binary Format (read)
CSS format (readcss)
SDD format (readsdd)
ASCII formats (readalpha)
Use the "help" facility in SAC or refer to the online
manual for detailed descriptions of these formats.

SAC Binary Format

This is the standard format for most seismic data. A
SAC binary file consists of a header of ascii data that
defines the following binary seismic data. The data
may consist of equally incremented or irregularly
spaced time series data, or complex spectral data.
SAC header:
The header portion of the file is very important to the
datafile since it contains information on sampling
interval, station location, event location, ground
motion components, and all other parameters
important in earthquake data processing. These
parameters are used by the various SAC commands to
manipulate the data.
For example, here is a listing of the header variables
for NS waveform data recorded at MLNT from the

recent Shelby Co. microearthquake:

Commands/Results

Explanation

SAC> r MLNT.EGN.NM.1.sac
SAC> lh

Read the data file

list the header using "lh"

FILE: MLNT.EGN.NM.1.sac
-----------------------

file name

NPTS = 18100
B = 0.0000000e+00
E = 1.8098999e+02
IFTYPE = TIME SERIES
FILE
LEVEN = TRUE
DELTA = 9.9999998e-03
DEPMIN =
-4.1800000e+02
DEPMAX = 6.6300000e+02
DEPMEN = 1.0872928e+00
OMARKER = 0
KZDATE = JAN 31 (031),
2001
KZTIME = 01:22:59.370
IZTYPE = BEGIN TIME
KINST = NM
KSTNM = MLNT
CMPAZ = 0.0000000e+00
CMPINC = 9.0000000e+01
STLA = 3.5334000e+01
STLO = -8.9830002e+01
EVLA = 3.5228001e+01
Waiting

number of points in the file

begin time
ending time
type of file
evenly sampled time series
time increment
minimum amplitude in file
maximum amplitude in file
mean amplitude of file
origin marker time
date (Julian day)
UT reference
reference time equivalence
generic name of instrument
station name
component azimuth relative to north
component "incidence angle" reletive to
the vertical
station latitude
station longitude
event latitude

EVLO = -8.9998001e+01
DIST = 1.9284590e+01
AZ = 5.2375816e+01
BAZ = 2.3247301e+02
GCARC = 1.7342965e-01
LOVROK = TRUE
SAC>

event longitude
station distance from event in km
station azimuth from event in degrees
event back azimuth from station in
degrees
great circle arc length in degrees
parameter enabling the file to be modified

Some of the information in the SAC header is computed

automatically once the appropriate header variables
have been defined. For example, "DIST", "AZ", "BAZ",
and "GCARC" are computed once the station and event
locations are defined by their geographical
coordinates.
Other information is essential for particular SAC
commands to work. For example "CMPAZ" and
"CMPINC" must be defined to use the "rotate" command
to rotate horizontal seismic data into tangential and
radial motions or to compute a particle motion plot
using "ppm".
Once data are manuipulated by SAC, the result can be
written to disk, in SAC binary format, using the "write"
("w") command.
SAC> r file1
SAC> hp bu co 1 n 2 p 1
SAC> w file2
last modified 3/05/01

SAC Plotting
A particular strength of SAC is in visualizing the data
after it is processed. SAC can be programmed to give a
wide variety of plot types. Usually, a graphics window
is initialized to view the plot and commands can be
given to interactively change plot characteristics. Once
the plot has been constructed in suitable form, it can be
saved to a SAC graphics file in "sgf" format. These sgf
files are then usually converted to another format, like
PostScript, for output to a printer or as input to another
graphics program.
This plot was made using the following commands
while working on a Macintosh at home:

Commands/Results
SAC> r mlnt.z mlnt.r mlnt.t
SAC> xvport 0.1 0.6
SAC> qdp off
SAC> xlim 58 70
SAC> title on "Rotated Data
at MLNT"
SAC> xlabel on "Time, sec"
SAC> ylabel on "Digital
Counts"
SAC> bd tek4014
SAC> p1
SAC> bd sgf
SAC> p1
SAC> ed sgf
SAC> sgftops f001.sgf plot1 1
y
SAC> q

Explanation
Read the three data files
change the x direction aspect ratio for the
plot
turn of the "quick and dirt plot" option
only plot time series data between 58 and
70 seconds
make a title
make a label for the x axis
make a label for the y axis
turn on the tek4014 device to plot to tek
window on my mac at home
plot all of this stuff using "plot1", view and
decide to save to a file
begindevice sgf to save to a sgf file
use p1 again, all other commands have
been saved by SAC
enddevice sgf to finish the sgf plot file
use the sgftops conversion utility to
convert the sgf file to PostScript
quit

At this point I ftp'd the plot file to the Mac and used
Adobe Illustrator to convert the PostScript plot into a
gif file for this webpage. Usually, I combine a number
of SAC plots with Adobe Illustrator to produce a figure.
Common plotting commands include:
plot (p) - plot a single seismogram
plot1 (p1) - plot almost any number of seismograms
plotpk (ppk) - interactive windowing and phase
picking routine
ppm - plot particle motion for two components of
motion (usually two horizontal components)
plotsp - plot the amplitude and phase spectra.
last modified 3/05/01

Blackboard Variables
SAC also has the internal functionality of a calculator.
The "Blackboard" is simply a feature that saves user
defined variables. These variables can be manipulated
and used in calculations. Results can be fed into SAC
commands for further data processing. Thus, SAC has
built into it a simple programming language.
The syntax for manipulating blackboard variables is
relatively simple but sometimes obscure. Refer to the
SAC manual for details.
Variables can be defined, evaluated, and put into
simple equations. There are also IF, ELSEIF, ELSE
statements in addition to DO loops. Sometimes it is a
real tradeoff whether to write a fancy SAC macro to
utilize blackboard variables or just use your favorite
programming language to do the same thing.
Examples are given in the Macros section of these
webpages.
last modified 3/05/01

Macros
A SAC macro is a script of SAC commands. SAC macros
can take several forms depending on how you want to
implement them. These include:
A simple macro file containing SAC commands
without keywords or dependent arguments
A macro with dependent arguments
A macro with keywords

Example 1 - A simple macro based on the plotting

example
macro name = mlntplot
r mlnt.z mlnt.r mlnt.t
xvport 0.1 0.6
qdp off
xlim 58 70
title on "Rotated Data at MLNT"
xlabel on "Time, sec"
ylabel on "Digital Counts"
bd sgf
p1
ed sgf
sgftops f001.sgf plot1 1 y

How it is used

SAC> macro mlntplot

Example 2 - The same macro driven by dependent

arguments

macro name = mlntplot2

r $1 $2 $3
xvport 0.1 0.6
qdp off
xlim 58 70
title on "Rotated Data at
MLNT"
xlabel on "Time, sec"
ylabel on "Digital Counts"
bd sgf
p1
ed sgf
sgftops f001.sgf plot1 1 y

How it is used

SAC> macro mlntplot2 mlnt.z mlnt.r

mlnt.t

Example 3 - The same macro driven by keywords

macro name =
mlntplot3

How it is used

$keys files values

r $files
xvport 0.1 0.6
qdp off
xlim $values
title on "Rotated Data at
SAC> macro mlntplot3 files mlnt.z mlnt.r
MLNT"
mlnt.t values 58 70
xlabel on "Time, sec"
ylabel on "Digital Counts"
bd sgf
p1
ed sgf
sgftops f001.sgf plot1 1 y

Macros can also call other macros. This is very useful

in applying a generic operation to many specific data
files.
Another useful trick, particularly when using SAC with

CShells, is to use the UNIX directed input. For example,

using the first macro above, we could produce the plot
by typing the following at the UNIX system prompt:
sysprompt> sac2000 < mlntplot > sac.output

"sac.output" is a file that catches all the sac i/o that

would normally be seen on the screen.
Macro examples from the SAC files of C.A. Langston ("The truth is out where?")
mom_correlate - find the best scale factor between
two time series in the least-squares sense
datasynplot.macro - plot data and synthetic
seismograms together
reduce.macro - read in a file, reduce the traveltime
and scale
last modified 3/05/01

CShell Scripts
The UNIX CShell enables SAC macros to be built within
a CShell script and then run. This is particularly useful
when running synthetic seismogram codes that output
time series in SAC binary format. These synthetic time
series can then be processed with SAC with the same
data processing performed on real data.
Here are four CShell Scripts that incorporate SAC in
them to varying degrees

kintcalc2 - produce synthetic seismograms from a

wavenumber integration program.
data_model_plot - make the SAC macros to produce
data/synthetic comparisons.
picksetup2, phasepick2 - use ppk interactively to
pick amplitude and times from seismograms. Save
the picks in file for more processing.
last modified 3/05/01

Use in Fortran Programs

Time series data can be generated in your own fortran
(and C ) programs and output in SAC binary format.
Many of my programs use this capability since it is
useful to compare data and synthetic seismograms in
the same format. It also useful to read SAC binary files
to perform more specialized functions that SAC does
not include.
This is accomplished by called the following IO
routines available in the SAC library, "sac.a".
rsac1 - reads an evenly spaced data file.
rsac2 - reads an unevenly spaced data file.
wsac1 - writes an evenly spaced data file.
wsac2 - writes an unevenly spaced data file.
In addition to these routines, there are a number of
subroutines that access or define each SAC header
variable. See the SAC manual for details.

An Example
Here is an f77 program that constructs a gaussian time
function an outputs the result in SAC binary format.
Source Code
c ------ gauss.f program to create gaussian time
function
CHARACTER*90 KNAME
CHARACTER*3 ANS

Explanation

dimension YARRAY(8192)
CHARACTER*80 PASNAME
*
Create the far field time function
-------------------WRITE(*,100)
100 FORMAT('INPUT time width and time shift
of gaussian pulse:')
READ(*,*) twidth,tshift
alpha=2.2/twidth
WRITE(*,101)
101 FORMAT('INPUT DT AND NPTS WANTED:')
READ(*,*) DT,NPOINT
DO 10 I=1,NPOINT
TM=DT*(I-1) - twidth - tshift
EGG=alpha*alpha*tm*tm
IF(EGG.GT.25.) EGG=25.
YARRAY(I)=EXP(-EGG)
C YARRAY(I)=-2.*TM*ALPHA*ALPHA*EXP(-EGG)
10 CONTINUE
C---------- NOW CREATE A HEADER IN SAC
FORMAT.--------------------C
C - Set all header fields to their default values.
C
CALL NEWHDR
C
C - USER ACTION: Shown below are incomplete
statements used
C
to define each of the SAC header fields.
C
Using your own variables, complete the
statements
C
which define the SAC header fields that
you
C
want to be in the file. Delete the
remaining lines.
C
C - The definitions for each of these variables can
be found in the
C appendix to the SAC Command Reference
Manual.
C

calculate the gaussian

function

Set up a new SAC

header

C - Fields which begin with an "L" are logical

fields and must
C be either .TRUE. or .FALSE.
C - Fields which begin with an "N" are integer
fields.
C - Fields which begin with an "I" are also
integers, but can only
C be set to a limited number of values, each
corresponding
C to a specific condition. See the above
mentioned appendix.
C - Fields which begin with a "K" are character
variables of
C length 8 unless otherwise noted.
C - All other fields are real.
C
C - The following fields are required:
C
NPTS=NPOINT
B=0.
DELTA=DT
E=B+FLOAT(NPTS-1)*DELTA
CALL SETFHV('B',B,NERR)
CALL SETFHV('E',E,NERR)
CALL SETNHV('NPTS',NPTS,NERR)
CALL SETLHV('LEVEN',.TRUE.,NERR)
CALL SETFHV('DELTA',DELTA,NERR)
CALL SETIHV('IZTYPE','IB',NERR)
CALL SETLHV('LPSPOL',.TRUE.,NERR)
CALL SETIHV('IEVTYP','IUNKN',NERR)
CALL SETIHV('IFTYPE','ITIME',NERR)
CALL SETIHV('IDEP','IDISP',NERR)
CALL SETLHV('LOVROK',.TRUE.,NERR)
C
KNAME='gauss.tfunc'
C
C - WRITE THE FILE TO DISK.
C
CALL
WSAC1(KNAME,YARRAY,npts,b,delta,NERR)
C

Set header variables

needed

use wsac1 to create an

evenly spaced binary
file

WRITE(1,200) KNAME
200 FORMAT(1X,'SAC FILE ',A32,' HAS BEEN
WRITTEN TO DISK')
99 CONTINUE
STOP
END

Here is the make file used to compile this program:

FFLAGS = -g
MYBIN = /yourdirectory/bin
LIB = $(SACDIR)/lib
gauss: gauss.f
f77 $(FFLAGS) -o $(MYBIN)/gauss gauss.f $(LIB)/sac.a

Important Note:
At this time (3/05/01) CERI does not have a generally
available copy of the SAC library, "sac.a" or "sacio.a",
that can be used in compiling fortran or C programs on
SUN Solaris systems. A copy is available at /tetemeko
/local/sac/lib/sac.a if you need to compile programs
with SAC I/O routines.
last modified 3/06/01