SAC(5) DATACENTER COMMANDS SAC(5) NAME SAC, sac - Documentation of SAC file format DESCRIPTION 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. Contents Each signal is stored on disk in a separate SAC data file. 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. Binary Format This is the format that you will use most often. It is used in SAC itself( READ and WRITE commands) and in the subrou- tine library (RSAC1, RSAC2, WSAC1, WSAC2, WSAC0.) These are binary (unformatted) files so that they can be quickly read from disk into memory. The header is 158 32-bit words in length, followed by the data section(s). In order to rapidly read only a small section of a data file (see the CUT com- mand), these files also have a physical record length of 512 bytes (128 32-bit words) and are opened for direct-access. (In the PRIME and UNIX versions there is no physical record structure.) This format is shown schematically in the fol- lowing figure. Structure of SAC Binary Data File --------------------------------- HEADER SECTION -------------- start word: 0 word length: 158 contents: see table UC Berkeley Last change: 6 JULY 1995 1 SAC(5) DATACENTER COMMANDS SAC(5) FIRST DATA SECTION ------------------ start word: 158 word length: NPTS contents: - dependent variable - amplitude - real component SECOND DATA SECTION* ------------------- start word: 158+NPTS word length: NPTS contents: - independent variable if evenly spaced - phase - imaginary component * if present Binary Header The following table shows the contents and layout of the SAC binary data file header. The W and T columns give the begin- ning 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 vari- able 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 sec- tion. W T NAMES--> - - -------- 0 F DELTA DEPMIN DEPMAX SCALE ODELTA 5 F B E O A INTERNAL 10 F T0 T1 T2 T3 T4 15 F T5 T6 T7 T8 T9 20 F F RESP0 RESP1 RESP2 RESP3 25 F RESP4 RESP5 RESP6 RESP7 RESP8 30 F RESP9 STLA STLO STEL STDP 35 F EVLA EVLO EVEL EVDP UNUSED 40 F USER0 USER1 USER2 USER3 USER4 45 F USER5 USER6 USER7 USER8 USER9 50 F DIST AZ BAZ GCARC INTERNAL 55 F INTERNAL DEPMEN CMPAZ CMPINC UNUSED 60 F UNUSED UNUSED UNUSED UNUSED UNUSED UC Berkeley Last change: 6 JULY 1995 2 SAC(5) DATACENTER COMMANDS SAC(5) 65 F UNUSED UNUSED UNUSED UNUSED UNUSED 70 I NZYEAR NZJDAY NZHOUR NZMIN NZSEC 75 I NZMSEC NVHDR INTERNAL INTERNAL NPTS 80 I INTERNAL INTERNAL UNUSED UNUSED UNUSED 85 I IFTYPE IDEP IZTYPE UNUSED IINST 90 I ISTREG IEVREG IEVTYP IQUAL ISYNTH 95 I UNUSED UNUSED UNUSED UNUSED UNUSED 100 I UNUSED UNUSED UNUSED UNUSED UNUSED 105 L LEVEN LPSPOL LOVROK LCALDA UNUSED 110 K KSTNM KEVNM* 116 K KHOLE KO KA 122 K KT0 KT1 KT2 128 K KT3 KT4 KT5 134 K KT6 KT7 KT8 140 K KT9 KF KUSER0 146 K KUSER1 KUSER2 KCMPNM 152 K KNETWK KDATRD KINST KEVNM is 16 characters (4 words) long. All other K fields are 8 characters (2 words) long. Alphanumeric Format This file is essentially the alphanumeric equivalent of the SAC binary data file. The header section is stored on the first 30 cards. This is followed by one or two data sec- tions. The data is in 5G15.7 format. The following table shows the card number, formats and names of the variables on the header section cards. CN FORMAT NAMES--> -- ------ -------- 01 (5G15.7) DELTA DEPMIN DEPMAX SCALE ODELTA 02 (5G15.7) B E O A INTERNAL 03 (5G15.7) T0 T1 T2 T3 T4 04 (5G15.7) T5 T6 T7 T8 T9 05 (5G15.7) F 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 UNUSED 09 (5G15.7) USER0 USER1 USER2 USER3 USER4 10 (5G15.7) USER5 USER6 USER7 USER8 USER9 11 (5G15.7) DIST AZ BAZ GCARC INTERNAL 12 (5G15.7) INTERNAL 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 INTERNAL INTERNAL INTERNAL NPTS 17 (5I10) INTERNAL INTERNAL UNUSED UNUSED UNUSED 18 (5I10) IFTYPE IDEP IZTYPE UNUSED IINST 19 (5I10) ISTREG IEVREG IEVTYP IQUAL ISYNTH 20 (5I10) UNUSED UNUSED UNUSED UNUSED UNUSED UC Berkeley Last change: 6 JULY 1995 3 SAC(5) DATACENTER COMMANDS SAC(5) 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 Sample Alphanumeric Data File 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: u: FUNCGEN SEISMOGRAM u: WRITE ALPHA TEMP1 You can then convert this alphanumeric file to a binary one and read it into SAC with the following commands: u: CONVERT FROM ALPHA TEMP1 TO SAC TEMP2 u: READ TEMP2 This little test shows the equivalence of the alphanumeric and binary file formats. 0.1000000e-01 -1.569280 1.520640 -12345.00 -12345.00 9.459999 19.45000 0. 10.47000 2.000000 -12345.00 20.00000 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 17.78000 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 87.99997 -120.0000 -12345.00 -12345.00 47.99997 -125.0000 -12345.00 -12345.00 -12345.00 123.4560 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 -12345.00 4461.052 0.2718981 185.2046 40.18594 -12345.00 -12345.00 -0.9854718e-01 0. 0. -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 6 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 UC Berkeley Last change: 6 JULY 1995 4 SAC(5) DATACENTER COMMANDS SAC(5) CDV K8108838 -12345 HOLE IPD0 XYZ -12345 KT1 -12345 -12345 -12345 -12345 -12345 -12345 -12345 -12345 ABKD USER0 -12345 -12345 -12345 -12345 -12345 -0.9728001e-01 -0.9728001e-01 -0.9856002e-01 -0.9856002e-01 -0.9728001e-01 -0.9600000e-01 -0.9472002e-01 -0.9344001e-01 -0.9344001e-01 -0.9344001e-01 -0.9344001e-01 -0.9344001e-01 -0.9472002e-01 -0.9472002e-01 -0.9344001e-01 -0.9344001e-01 -0.9216000e-01 -0.9216000e-01 -0.9216000e-01 -0.9216000e-01 -0.9088002e-01 -0.9088002e-01 -0.9216000e-01 -0.9344001e-01 -0.9472002e-01 TABLE: 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 N Number of points per data component. [required] B F Beginning value of the independent variable. [required] E F Ending value of the independent variable. [required] IFTYPE I 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 L TRUE if data is evenly spaced. [required] DELTA F Increment between evenly spaced samples (nominal value). [required] ODELTA F Observed increment if different from nominal value. IDEP I Type of dependent variable: = IUNKN (Unknown) = IDISP (Displacement in nm) = IVEL (Velocity in nm/sec) = IVOLTS (Velocity in volts) = IACC (Acceleration in nm/sec/sec) SCALE F Multiplying scale factor for dependent variable [not currently used] DEPMIN F Minimum value of dependent variable. DEPMAX F Maximum value of dependent variable. DEPMEN F Mean value of dependent variable. NZYEAR N GMT year corresponding to reference (zero) time in file. NZJDAY N GMT julian day. NZHOUR N GMT hour. NZMIN N GMT minute. NZSEC N GMT second. NZMSEC N GMT millisecond. UC Berkeley Last change: 6 JULY 1995 5 SAC(5) DATACENTER COMMANDS SAC(5) NZDTTM N GMT date-time array. Six element array equivalenced to NZYEAR, NZJDAY, NZHOUR, NZMIN, NZSEC, and NZMSEC. KZDATE A Alphanumeric form of GMT reference date. Derived from NZYEAR and NZJDAY. KZTIME A Alphanumeric form of GMT reference time. Derived from NZHOUR, NZMIN, NZSEC, and NZMSEC. O F Event origin time (seconds relative to reference time.) KO A Event origin time identification. A F First arrival time (seconds relative to reference time.) AMARKER A Derived from A and KA. KA K First arrival time identification. F F Fini or end of event time (seconds relative to reference time.) KF A Fini identification. T{i...n} F User defined time picks or markers, {i...n}=0,9. (seconds relative to reference time.) KT{i...n} A User defined time pick identifications, {i...n}=0,9. IZTYPE I Reference time equivalence: = IUNKN (Unknown) = IB (Begin time) = IDAY (Midnight of refernece GMT day) = IO (Event origin time) = IA (First arrival time) = IT{i...n} (User defined time pick {i...n}, {i...n}=0,9) KINST K Generic name of recording instrument. IINST I Type of recording instrument. [not currently used] RESP{i...n} F Instrument response parameters, {i...n}=0,9. [not currently used] KNETWK K Name of seismic network. KSTNM K Station name. ISTREG I Station geographic region. [not currently used] STLA F Station latitude (degrees, north positive). STLO F Station longitude (degrees, east positive). STEL F Station elevation (meters). [not currently used] STDP F Station depth below surface (meters). [not currently used] CMPAZ F Component azimuth (degrees clockwise from north). CMPINC F Component incident angle (degrees from vertical). KCMPNM K Component name. KSTCMP A Station component. Derived from KSTNM, CMPAZ, and CMPINC. LPSPOL L TRUE if station components have a positive polarity (left-hand rule). ADJTM F The amount that the time has been adjusted to correct problems. KEVNM K Event name. IEVREG I Event geographic region. [not currently used] EVLA F Event latitude (degrees, north positive). EVLO F Event longitude (degrees, east positive). EVEL F Event elevation (meters). [not currently used] EVDP F Event depth below surface (meters). [not currently used] IEVTYP I Type of event: = IUNKN (Unknown) = INUCL (Nuclear event) = IPREN (Nuclear pre-shot event) = IPOSTN (Nuclear post-shot event) = IQUAKE (Earthquake) UC Berkeley Last change: 6 JULY 1995 6 SAC(5) DATACENTER COMMANDS SAC(5) = IPREQ (Foreshock) = IPOSTQ (Aftershock) = ICHEM (Chemical explosion) = IOTHER (Other) KHOLE K Hole identification if nuclear event. DIST F Station to event distance (km). AZ F Event to station azimuth (degrees). BAZ F Station to event azimuth (degrees). GCARC F Station to event great circle arc length (degrees). LCALDA L TRUE if DIST, AZ, BAZ, and GCARC are to be calculated from station and event coordinates. IQUAL I Quality of data [not currently used]: = IGOOD (Good data) = IGLCH (Glitches) = IDROP (Dropouts) = ILOWSN (Low signal to noise ratio) = IOTHER (Other) ISYNTH I Synthetic data flag [not currently used]: = IRLDTA (Real data) = ????? (Flags for various synthetic seismogram codes) KDATRD K Date data was read onto computer. USER{i...n} F User defined variable storage area, {i...n}=0,9. KUSER{i...n} K User defined variable storage area, {i...n}=0,2. LOVROK L TRUE if it is okay to overwrite this file on disk. NVHDR N Header version number. Current value is the integer 6. TABLE: Header Data Types This table lists the header types and their definitions. The third column lists type definition undefined description ---- ---------- --------- ----------- F Floating -12345.0 Single precision. N Integer -12345 Name begins with an ``N''. I 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. L Logical FALSE Name begins with an ``L''. Value is either TRUE or FALSE. K Alphanumeric ``-12345'' Name begins with a ``K''. Either 8 or 16 characters long. Derived from other header fields. Enumerated Header Enumerated Header Field Values The enumerated header field values are stored in the header UC Berkeley Last change: 6 JULY 1995 7 SAC(5) DATACENTER COMMANDS SAC(5) as integers. Their names and values are given in the table below. name value name value ---- ----- ---- ----- 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 UC Berkeley Last change: 6 JULY 1995 8