Using SAC
Using SAC Commands: A - Z Functional Subprocesses: SPE SSS SAC/IRIS

Data Access

OVERVIEW

Starting in version 102.0, SAC is capable of viewing and downloading event, station, and response metadata and downloading waveforms from online Web services. These abilities include

  • event searches ( EVENT )
  • station searches ( STATION )
  • data: searches and downloading ( DATA )
  • applying station and/or event meta-data to data ( METADATA )
  • reading miniseed directly into SAC ( READ )
  • download instrument responses ( RESPONSE )
  • traveltime data using the the IRIS Traveltime Web Service ( TRAVELTIME )

Definitions

Currently (2020), as described on the IRIS DMC Web Service Web page

<https://service.iris.edu>:

  • miniSEED is the subset of the SEED standard that is used for time series data. Very limited metadata for the time series is included in miniSEED beyond time series identification and simple state-of-health flags. In particular, geographic coordinates, response/scaling information and other information needed to interpret the data values are not included.
  • FDSN StationXML is the XML-based standard for seismological metadata. These metadata contain the most important and commonly used structures of SEED 2.4 metadata with many enhancements.
  • PH5 is the name of the repository at the IRIS DMC commonly used for active-source, controlled-source and mixed-source data sets and is an alternative to the DMC's SEED repository. In DATA, METADATA, and STATION ph5 is an option that when invoked will search this alternate repository.

Web requests are made to the colletion of Web Services at http://service.iris.edu along with event searches through the USGS and ISC.

An EventID is defined by source:uniqueid. See EVENT for more details.

Event search results, EVENT, can be used as input for timing and location in DATA and STATION searches using assocaited EventID. Examples are given below.

The format for latitudes and longitudes is degrees.decimal-degrees. Longitudes run from -180.00 degrees to 180.00 degrees. The formats used for time are given at the end of this file.

For repeated calls to most SAC command in a single session, the program "remembers" previous values for options if not reset explicitly. That is not true for these commands; For any option not explicitly stated in each call, the default is assumed. If there is no default value for an option, it must be explicitly given.

The SAC convention for units differs from others such as EVALRESP and SEED that use SI units (meters, meters/sec, meters/sec/sec). SAC uses nm for displacement. As discussed in TRANSFER, unit conversions may be needed to convert output files from instrument-corrections to get consistency between the data and the SAC header parameter IDEP.

SACLST & SACSET: These two stand-alone programs allow one to parse (saclst) or modify the header or of one or more SAC files. They are analogous to the internal SAC commands LISTHDR and READHDR respectively. One can display the results on the screen, print them, or (for saclst) redirect the output into an application. See ${SACHOME}/utils/README_utils for more details. Examples are given below showing how saclst output can be redirected to applications.

TIME FORMATS

Times are of the form h:m:s or h:m:s.ms where h is the hour, m the minute, s the seconds, and ms the millisecodnds. If the time is left out, the beginning of the day is used, i.e. 00:00:00.000.

Dates are in the form Y-M-D or Y-O where Y is the year, M the month, D the day of the month, and O the day of the year (or ordinal day). Separators for the date components include /, ,, and -. Separators between the date and time is either a T or the date separator.

Date Only Date and Time Date and Time
Y/O Y/OTh:m:s Y/O/h:m:s Y/OTh:m:s.ms Y/O/h:m:s.ms
Y-O Y-OTh:m:s Y-O-h:m:s Y-OTh:m:s.ms Y-O-h:m:s.ms
Y,O Y,OTh:m:s Y,O,h:m:s Y,OTh:m:s.ms Y,O,h:m:s.ms
Y/M/D Y/M/DTh:m:s Y/M/D/h:m:s Y/M/DTh:m:s.ms Y/M/D/h:m:s.ms
Y-M-D Y-M-DTh:m:s Y-M-D-h:m:s Y-M-DTh:m:s.ms Y-M-D-h:m:s.ms
Y,M,D Y,M,DTh:m:s Y,M,D,h:m:s Y,M,DTh:m:s.ms Y,M,D,h:m:s.ms

Durations are of the form [+-]###unit where + is time forward and - is a time backwards from the reference time, unit are given below, and the ### is an integer value.

Duration Abbreviations
Seconds s sec secs seconds
Minutes m min mins minutes
Hours h hrs hours
Days d days
Weeks w wk wks weeks
Months mon months
Years y yr yrs years
Decades dec decades
Centuries cent centuries

INSTRUMENT RESPONSES

Responses for specific files is also simple with files read into memory. Responses can be obtained in sacpz or evalresp format.:

SAC> read XE.DOOR..BHZ.M.1994.160.003345.sac

SAC> response sacpz
Writing data to SAC_PZs_XE_DOOR__BHZ_1994-06-09T00:33:45_1994-06-09T01:33:44 [  1.02 KiB]

SAC> response evalresp
Writing data to RESP.XE.DOOR..BHZ [ 49.80 KiB]

COMPUTING TRAVELTIMES

Traveltimes can also be retrieved and set using the traveltime Web Service at IRIS. Just specific the ONLINE keyword to the TRAVELTIME command:

SAC> data sta CMB net BK cha BHZ gcmt:369471 duration 1h read
Data Center: NCEDC,http://www.ncedc.org
     SourceID                Start sample            End sample         Gap
XFDSN:BK_CMB__B_H_Z      1994-06-09T00:33:45.004000
1994-06-09T01:33:44.953000  ==
Working on file: BK.CMB..BHZ.D.1994.160.003345.sac [ OK ]

SAC> traveltime online picks 0 phase ttall
traveltime: depth: 647.100 km
traveltime: setting phase P        at 618.4500 s [ t = 618.4500 s ] t0
traveltime: setting phase PKIKKIKP at 1782.5400 s [ t = 1782.5400 s ] t1
traveltime: setting phase PKIKPPKIKP at 2280.2400 s [ t = 2280.2400 s ] t2
traveltime:         phase PKIKPPKIKP truncated in kt2
traveltime: setting phase PKPPKP   at 2277.7900 s [ t = 2277.7900 s ] t3
traveltime: setting phase PKiKP    at 974.6000 s [ t = 974.6000 s ] t4
traveltime: setting phase PP       at 789.5900 s [ t = 789.5900 s ] t5
traveltime: setting phase PcP      at 632.6300 s [ t = 632.6300 s ] t6
traveltime: setting phase S        at 1128.5800 s [ t = 1128.5800 s ] t7
traveltime: setting phase SKIKKIKP at 1935.6899 s [ t = 1935.6899 s ] t8
traveltime: setting phase SKS      at 1160.1700 s [ t = 1160.1700 s ] t9

SAC> lh picks

  FILE: BK.CMB..BHZ.D.1994.160.003345.sac - 1
 ---------------------------------------

         NPTS = 72000
            B = -3.960000e-01
            E = 3.599554e+03
      OMARKER = -2.1458e-09
     T0MARKER = 618.45           (P)
     T1MARKER = 1782.5           (PKIKKIKP)
     T2MARKER = 1997.2           (PKIKKIKS)
     T3MARKER = 2280.2           (PKIKPPKI)
     T4MARKER = 2277.8           (PKPPKP)
     T5MARKER = 974.6            (PKiKP)
     T6MARKER = 789.59           (PP)
     T7MARKER = 632.63           (PcP)
     T8MARKER = 1128.6           (S)
     T9MARKER = 1935.7           (SKIKKIKP)
       KZDATE = JUN 09 (160), 1994
       KZTIME = 00:33:45.400

Teleseismic Traveltime Example

Given a region of interest to conduct a teleseismic traveltime experiment, first find the events 30 to 90 degrees from the region of interest, Hawaii (Lon: 158W, Lat: 20N). Here we only look for events within the last year and magnitude > 7 to limit the results, typically we use more expansive search parameters. As this uses a do loop, the commands need to be contained within a macro

% cat data.sm
event mag 7  radial -158 21 30 90  usgs time now -1years  to events
outfile events_usgs_m7.xml

do ev list %events
   message "Event $ev"
   mkdir $ev
   cd $ev
   station $ev cha BHZ outfile stations.txt region -161 -152 18 22
   data $ev  cha BHZ  in stations.txt out request.txt  duration 90m
   miniseed
   cd ..
enddo

% sac
SAC> macro data.sm

This should result in a set of directories named with eventids containing a station file, the data request, and miniseed files to be unpacked. Miniseed files can be unpacked, metadata applied, and traveltime data set using:

SAC> sc to PWD "basename @$(pwd)"
SAC> getbb PWD
SAC> read *.mseed
SAC> metadata %PWD
SAC> traveltime online picks 0
SAC> write over

REDIRECTING SACLST INPUT

Let's say you have a list of sac files and you would like to generate a station list:

saclst knetwk kstnm stlo stlo stel f *.SAC | \
  awk '{print $2,$3,$4,$5}' | \
        sort | \
        uniq > station_lists.txt

To make sure all event locations are consistent for a list of files:

saclst evlo evla evdp f *.SAC   |  awk '{print $2,$3,$4}' | sort | uniq

Find file that are too short in duration with the longest first:

saclst b e f *SAC | \
        awk '{print $1,$2,$3,$3-$2}' | \
        sort -nr -k +4

Or removing files that are too short in duration:

mkdir too_short
for z in $( saclst b e f *SAC | awk '{if($3-$2<30.0){print $1}}'  ) ; do
        mv $z too_short
done

Or using xargs:

saclst b e f *SAC | awk '{if($3-$2<30.0){print $1}} | \
  args -I args mv args too_short

RDSEED - End of Life

Before 2010, the majority of data analysis was done on data sets commonly exchanged as SEED volumes, which could be downloaded from the IRIS Data Management Center over the Internet. For the SEED manual, go to <http://www.fdsn.org/seed_manual/SEEDManual_V2.4.pdf>.

Program RDSEED is a legacy utility for reading SEED volumes. This utility allows the user to read the contents of the SEED file and convert it to many different output formats (including SAC), extracting the data, station information, or instrument responses from the file. Although SEED volumes remains the FDSN-approved file format for representing and distributing digital seismic data, RDSEED is End of Life and no longer supported at IRIS. It has now been made an open-source project on GitHub <https://github.com/iris-edu-legacy/rdseed>. For further details on RDSEED, go to <http://ds.iris.edu/ds/nodes/dmc/software/downloads/rdseed/5-3-1-eol/>.

Using SAC Commands: A - Z Functional Subprocesses: SPE SSS SAC/IRIS