Using SAC

SAC Tutorial Guide for New Users

OVERVIEW

SAC was designed as an aid to research seismologists in the study of seismic events. As such, it is used for quick preliminary analyses, for routine processing, for testing new techniques, for detailed research, and for creating publication quality graphics. It is used by both computer novices and experts. In order to make SAC quick to learn and easy to use, default values for all operational parameters were carefully chosen. At the same time, almost all of these parameters are under direct user control. This design combines ease of use with significant flexibility.

README

The first step is to study the README file that is in the top directory of the distribution: sac. It gives detailed instructions about setting up the environmental variables necessary to run SAC and other pieces of useful information.

USER INTERFACE

SAC is an interactive command-driven program. Commands may be typed at the terminal or placed in a macro file. SAC commands fall into three main categories: parameter-setting, action-producing and data-set manipulation. The parameter-setting commands change values of internal SAC parameters. Action-producing commands perform some operation on the signals currently in selected memory based upon the values of these parameters. Data-set commands determine which files are in active (selected) memory and therefore will be acted upon (data-set commands are not currently operational).

Within a single SAC session, the effect of a parameter-setting command remains in effect until that parameter is reset. The effect of an action-producing command is immediate and transitory. Action-producing commands also have options which normally remain in effect until reset (for that particular command).

When you start up SAC, default values are defined for all of these parameters. SAC can be reinitialized to this default state at any time by executing the INICM command.

MODE OF OPERATION

Each signal is stored in a separate data file. Each data file contains a header that describes the contents of that file. See the section on sac data file format for details. Signals are read from disk into memory using the READ command. CSS 3.0 formated flat files can be read using the READCSS command. SAC can process up to 200 signals of arbitrary size at a time. Once data is in memory other commands are typed at the terminal (or read from a macro file) to perform operations on these signals. All operations work concurrently on all signals in memory. You can look at the results at any time using the plot commands. There are several plot formats to choose from. You have control over titles and labels, plot limits, file identifications, axes and tick mark locations, etc. You can also save the results of these operations at any time using the WRITE command.

HOW SAC HANDLES TIME

The SAC header contains a reference or zero time, stored as six integers (NZYEAR, NZJDAY, NZHOUR, NZMIN, NZSEC, NZMSEC), but normally printed in an equivalent alphanumeric format (KZDATE and KZTIME). This can be set to any reference time you wish. It is often the time of the first data point, but can also be the origin time of the event, midnight, your birthday, etc. It does not even have to be a time encompassed by the data itself. All other times are offsets in seconds from this reference time and are stored as single-precision floating-point values in the header:

B:Begin time of the file.
E:End time of the file.
O:Event origin time.
A:First arrival time.
F:Fini (end of signal.)
Tn:Time markers, where n is an integer from 0 to 9.

ANALYSIS CAPABILITIES

SAC Analysis Capabilities provides an introduction to these features. Command Reference Manual lists all the commands and has links to help files for them.

GETTING STARTED

SAC will then print a short headline including the number and date of the version you have on your system. It may also print a bulletin giving some current information. SAC will then ask you for input by sending the prompt "SAC>".:

% sac
 SEISMIC ANALYSIS CODE [08/15/2006 (Version 100.1)]
 Copyright 1995 Regents of the University of California

SAC>

INTERACTION

SAC is an interactive command driven program. This means that you must type a command to get SAC to do something. It does not prompt you for input. Commands may be typed at the terminal or placed in a command file. Symbols within a command are separated by spaces and commands within a given line may be separated by a semicolon.

We'll start by creating a simple function:

SAC> FUNCGEN impulse

This generates an impulse function and stores it in SAC's memory. To see what this function looks like on your screen type:

SAC> PLOT

ABBREVIATIONS

There are abbreviations for the most used SAC commands. For example, fg and p are the abbreviations for FUNCGEN and PLOT respectively.

For a complete listing of the abbreviations, please consult the ABBREV help file or run help abbrev while in SAC

CHANGING OPTIONS IN REPEATED CALLS TO SAC COMMANDS

As an example, the FUNCGEN command can generate a number of different functions. To see them, use the HELP command:

SAC> help fg

Using fg can be very useful when first learning how to use SAC because you can see how the other SAC operations work on these functions. For example:

SAC> fg sine 2 npts 200 delta 0.01

This generates a 2 Hz sine wave in SAC's memory. The function will contain 200 data points and have a sampling interval of 0.01 seconds. You can use the PLOT command to plot this function also.

When you specify a value for a particular option, this becomes the new current value, which means you don't have to keep entering values for options that you don't want to change. For example, you can now generate this same 2 Hz sine wave using the same sampling interval but with 400 data points by simply typing:

SAC> fg npts 400

SAC remembers sine as the function called most recently by fg. This is common for most commands in SAC: if a new argument for an option is not given, SAC uses the most recently used value in the current session. (Sometimes one forget that an option had been used, so one may not correctly anticipate correctly the result of the operation.)

DEFAULT VALUES

All commands have "nice" default values for most options. The use of current and default values for command options can save you a lot of typing. For example, let's look at the BANDPASS command. This command applies a bandpass filter to the data currently in memory:

SAC> fg impulse npts 100 delta 0.01
SAC> bandpass bessel corner 0.1 0.3 npole 4

These two commands generate an impulse function and then apply a bandpass filter to that impulse. The filter is a four-pole Bessel filter with corner frequencies at 0.1 and 0.3 Hz. (To see the default values for BANDPASS, enter HELP BANDPASS.) You can see the result in the time domain by typing PLOT or you can see the amplitude response by taking the Fourier transform and using the PLOTSP command:

SAC> fft
SAC> plotsp am

You can now try a different set of corner frequencies very easily:

SAC> fg
SAC> bandpass corner 0.2 0.5

SAC generates the same impulse function and applies the same Bessel filter except for the new corner frequencies.

SAC DATA FILES

SAC is a program to examine, analyze, and plot data. This data is stored on disk as SAC data files. Each data file contains a single data set. For seismic data this means a single data component recorded at a single seismic station. SAC does not currently work on multiplexed data. The data will generally be evenly spaced time series data. SAC can also handle unevenly spaced data and spectral data. The spectral data can be in either real-imaginary or amplitude-phase format. Use help bandpass to see the defaults.

SAC HEADER

Each data file also contains a header record which describes the contents of that file. Certain header entries are always present (e.g., the number of data points, the file type.) Others are always present for certain file types (e.g., sampling interval, begin time, etc. for evenly spaced time series files.) Other header variables provide information needed by a particular operation (e.g., seismic component orientation used by the ROTATE command.) Still others are not used by SAC at all. They are simply informational. Section sac data file format lists and discusses all header values. The LISTHDR command displays the contents of the headers for the data files currently in memory. You may wish to examine the header from the sample seismogram mentioned earlier:

SAC> FG seismogram
SAC> LH

If a particular header variable does not have a value for a particular file, then that variable is said to be "undefined" for that file. The LISTHDR command does not list undefined header variables, unless it is invoked with the INC or INCLUSIVE option (which includes undefined header variables). (Entr help lh to see the options.)

A few important header variables are listed below:

NVHDR:If 7, Double-precision used for internal calculations with header variables
B:Beginning value of the independent variable;
IFTYPE:Type of file;
LEVEN:TRUE if data set is evenly spaced;
DELTA:Increment between evenly spaced samples;
IDEP:Type of dependent variable;
KZDATE:Alphanumeric form of GMT reference date;
KZTIME:Alphanumeric form of GMT reference time;
A:First arrival time (seconds relative to reference time);
T n:User defined time picks or markers, n=0,9.

READING AND WRITING DATA FILES

Reading Data Files

SAC commands work on data already in SAC's working memory, not data on disk. The READ command is used to transfer data from disk to memory. Up to 100 data files can be in memory at the same time, and this limitation should be removed in upcoming versions. These can be of any size up the maximum size of SAC's working memory. You can use wildcard characters in the READ command to represent groups of files which have a similar set of characters in their names. Each time you use the READ command to transfer data from disk to memory the data currently in memory is destroyed. If you want this data saved, you must write it to disk before reading more data into memory. There is an option called MORE in the READ command that lets you read data into memory without destroying the old data. See the Command Reference Manual for details.

Writing Data Files

At any time during your analysis, you may transfer this modified data back to disk using the WRITE command. You may overwrite the old data files on disk using the OVER option or create new ones by specifying their file names. Action commands (such as ADD, DECIMATE, and FFT) modify the data that is currently in memory. The data files on disk are not modified.

Reading and Writing Examples

A complete discussion of reading and writing SAC data files is given in sac reading and writing routines.

The examples below demonstrates several uses of the READ and WRITE commands.

Scaling Example

The first example reads two files into memory, multiplies each data point in each file by a constant, and then writes the results to disk in two new files:

SAC> R file1 file2
SAC> MUL 10 20
SAC> W file3 file4

Decimation Example

The next example reads a single file into memory, desamples the data by a factor of five ( DECIMATE also applies an anti-aliasing filter), and then writes the results back to disk using the same file name:

SAC> R file1 file2 file3 file4
SAC> DECIMATE 5
SAC> WRITE OVER

Sample Data Files

You're going to need some data files for use in the next section on plotting. You'll also need them if you want to try any of the other commands discussed later in this guide. If you don't have any sample SAC data files around to play with, you can use FUNCGEN to generate some. This is shown in the example below:

SAC> fg triangle npts 200 delta 1.0
SAC> write file1
SAC> fg boxcar
SAC> write file2
SAC> fg step
SAC> write file3

This results in you having three files in your directory called file1, file2, file3 which contain the triangle, boxcar, and step functions respectively. Each will have 200 data points in them and be sampled at 1 sample per second. If you already had files in your directory by those names, they would be replaced by these new ones.

PLOTTING IN SAC

Displaying the Results

After reading data into SAC you can see it on your screen in several different formats using the various plot commands. Default values for each of the graphics display commands have been chosen to make it as easy as possible to display your data. By changing these default values before plotting, you also have complete control over the details of how each plot will look.

You've already used PLOT to display data files. With this command, each data file is plotted one at a time. SAC pauses between files to give you a chance to examine the data. This is shown in the following example.:

SAC> read file1 file2 file3
SAC> plot
Waiting [press return]
Waiting [press return]
Waiting [press return]
SAC>

Typing a "q" and then return will exit the plot command and not plot the remainder of the files in memory.

Additional Plot Commands

Several other canned plot formats are available. PLOT1 plots each file along a common x axis but with a separate y axes. By default all files are placed on the same plot. Try this with the three files from the example above. PLOT2 is an overlay plot. Again all files are plotted together, this time using both a common x and a common y axis. PLOTPK uses a format similar to PLOT1. It lets you use the cursor to blow up parts of the plot, determine values of selected data points, pick phase arrival times, etc.

Display Options

By default, all SAC plots are self-scaling. SAC determines what limits to use for the x and y axes. If you want to set these limits yourself, you may do so using the XLIM and YLIM commands. If you wish, you may also change the location of annotated axes, change the linestyle, select a symbol to be plotted at each data point, create titles and labels, make logarithmic plots, change the size and type of text, and control a number of other even more exotic aspects of the plot. These commands are part of the Graphics Environment Module, and are defined in links from the Command Reference Manual.

An Overview of Graphics Capability in SAC

File Graphics in SAC has an overview of graphics in SAC. Of particular interest may be the command SAVEIMG that allows one to save displayed plots in several formats.

FLOATING-POINT PRECISION IN SAC

Background

In all version of SAC through and including v101.6a, all reals in the SAC header/data are single-precision (32 bits; 4 bytes). The smallest time increment within SAC I/O is 0.001 s (header variable NZMSEC is milliseconds). When SAC was written 30+ years ago, a sampling rate of 0.01 s was about as high as the technology allowed, and single SAC files used in analysis were at most several minutes in duration. Now thanks to GPS and advances in both hardware and software, many experiments routinely have sampling rates of 0.001 s, and single SAC data files can be up to hours/days in duration. If SAC is to remain useful for such data sets, single-precision is not sufficient. SAC v102.0 includes double-precision for both time and distance calculations using header variables, and does so in a way that maximizes compatibility so that existing SAC data files can still be used.

We discuss floating-point precision in SAC and give examples showing errors at large times due to the limitations of single-precision for header variables and how these have been resolved using the modified SAC data file structure introduced in v102.0.

Single-Precision in SAC

./precision_fig1.png

Figure (1): the bit structure of a single-precision floating-point number.

In a 32-bit floating-point number, 23 bits define the maximum precision. For all floating-point numbers with a size between \(2^{n-1}\) and \(2^n\) floating-point values are separated by \(\delta(n)\), given by

\begin{equation*} \delta(n)=\frac{2^{n-1}}{2^{23}} = \frac{t(n)_{ref}}{2^{23}}, \end{equation*}

where, in our applications of the above equation, \(\delta(n)\) and the reference time \(t(n)_{ref}\) are times in seconds. For n=17, \(t(17)_{ref}\) = 65,536 s and \(\delta(17)\) = 0.0078 s. Incrementing n by 1 doubles the floating-point increment.

In the examples below, we use the following macro that sets DELTA = 0.01 s and B = 48 hours = 172,800.00 s, (for which \(t(18)_{ref}\) = 131,072 s and the floating-point increment \(\delta(18)=0.0156\) s = 156% DELTA):

fg sine 2.0 delta 0.01 npts 13
symbol 2
fileid location ul
ch b 172800
ch t0 (&1,b + &1,delta * 1)
ch t1 (&1,b + &1,delta * 2)
ch t2 (&1,b + &1,delta * 3)
ch t3 (&1,b + &1,delta * 4)
ch t4 (&1,b + &1,delta * 5)
ch t5 (&1,b + &1,delta * 6)
ch t6 (&1,b + &1,delta * 7)
ch t7 (&1,b + &1,delta * 8)
ch t8 (&1,b + &1,delta * 9)
ch t9 (&1,b + &1,delta * 10)
lh picks

From the macro, we see that waveform times (squares) should be at 176,800.00, 176,800.01, ... ; and the ten time picks should be at 176,800.01, 176,800.02, ... .

./precision_fig2.png

Figure (2): SAC v101.6a using the above macro.

In v101.6a, SAC used double-precision for some internal calculations, but not in calculations used to increment times when plotting waveforms or in producing the time labels in plots. In Fig. (2), the time picks and the symbols are at the same times, which is because they were both calculated using single precision. (Even though the time-plot labels in Figure 2 are distracting, we can ignore them as they were not calculated the same way as the plotted times.)

The separation between all the squares is supposed to be DELTA = 0.01 s, but \(\delta(18)=0.0156\) s is the minimum separation between neighboring values. The first time point is at 176,800.00 s. The plotted time for the symbol of the next point will be at the nearest floating-point neighbor to 176,800.01 s, which is 176,800.0156 s rather than 176,800.00 s so that is where the next symbol is plotted. 176,800.02 s is closer to 176,800.0146 s than to 176,800.0312 s, so that symbol is at the same time as the previous symbol \(-\) and time picks T0 and T1 overlap at that same time as the symbols).

In 2017 the problems with the time plot labels and waveform times were fixed, which was possible with the existing SAC data-file format because the calculations of those times are done internally so could be done in double precision. Because B, DELTA, T0 ... T9 are header variables, they could not be changed to double precision.

./precision_fig3.png

Figure (3): SAC v101.6a but double-precision internal calculations for times.

Figure (3) uses double precision for the internal calculations for times but uses the same procedure as used in Fig. (2) for time picks. The waveform time symbols (and the time axis) are now "correct", but the time picks are unchanged from Figure 2.

Upgrade To Double Precision

Header variable NVHDR is the SAC version number. For the past several decades NVHDR = 6. In SAC v102.0, the file structure has been changed to address the precision problem. The change is done in such a way that existing SAC files can be read and processed as before.

The file structure when NVDHR = 7 is discussed in sac data file format; when NVDHR = 7 there is a "footer" in the file structure that contains double-precision versions of 22 time/distance (single-precision) header variables. These 22 variables are DELTA, B, E, O, A, T0 ... T9, F, EVLO, EVLA, STLO, STLA, and internal variables 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.

If a SAC file with NVHDR = 6 is read into memory using SAC v102.0, double-precision copies of those 22 header variables are stored in memory, but the single-precision version of those header variables is still used so long as NVHDR = 6. However, if one enters CH NVDHR 7, one has the potential of changing the precision of variable like DELTA for internal calculations.

Important

Switching a file from NVHDR = 6 to 7 does not magically produce a proper double-precision value. Values stored in 32 and 64 bits will only be modified when a value is changed through CHNHDR or equivalent methods.

SAC v102.0 introduces OUTPUT_FORMAT, which can change the format for floating-point variables in SAC commands LISTHDR, MESSAGE, and EVALUATE.

Setting NVHDR = 7 leads to time picks being calculated and stored in double precision. Using the default for OUTPUT_FORMAT does not show enough significant figures to distinguish between the values for NVHDR 6 or 7. Using longE for the output format shows the difference:

SAC> fg impulse
SAC> setbb OUTPUT_FORMAT longE
SAC> ch t0 (1.0/3.0)
SAC> lh nvhdr t0
    nvhdr = 6
    t0 = 3.333333432674408e-01
SAC> ch nvhdr 7
SAC> lh nvhdr t0
    nvhdr = 7
    t0 = 3.333333333333333e-01

If one ran the above macro in SAC v102.0, one gets the same result ass shown in Fig. (3). If one then enters CH NVHDR 7 ; P1 one gets the plot shown in Fig. (4). If one then enters SETBB OUTPUT_FORNMAT longE ; LH, one can see the differences in T0, T1, T2, etc. See GETBB for more information about OUTPUT_FORMAT.

./precision_fig4.png

Fig. (4): SAC v102.0 with ch NVHDR 7 preceding P1.

In Figure 4, the times/picks, and tic-marks are all lined up.

For an unevenly-spaced, time-series file (IFTYPE=ITIME[1] and LEVEN=False[0]), the time data are single-precision, so for times \(\ge\) 1e7 seconds, the times will be incorrect.

Distance And Geographic Variables Precision

There are several distance-related variables in the header, but DIST, AZ, BAZ, and GCARC are not used as input for internal computation; they are derived from the header variables EVLA, EVLO STLA, and STLO,, which is why only those four are in the footer.

Distance precision using real*4 (32-bits) is less restrictive than for time precision. Half the circumference of the Earth is about 20,000 km, so if the numerator in the right-hand side of the above equation is a distance reference in meters, \(\Delta(n)_{ref}\), the half circumference has a distance reference \(\Delta(24)_{ref}\) with a \(\delta(24)\) = 2 m. The largest relative latitude or longitude for that distance would be about 180 degrees in longitude at the equator, which has a similar reference. A more significant limitation for such distances is probably the accuracy of of the reference ellipsoid. Promoting the station and hypocenter latitudes and longitudes removes any potential distance-related precision problems.

Dynamic Range

20 years ago, 16 bits was the standard for data. Today 24 bits is standard. \(2^{24}\) = 16,777,216. Using single precision for the SAC amplitude data is sufficient.

Maximum Number Of Points

Integer header variable NPTS has 4 bytes (32 bits). The SAC header uses signed integers, so the maximum value is \(2^{31}\) - 1 = 2,147,483,647. If the sampling rate is 0.001 s, the maximum record length is 24.85 days.