Original: 1979 Revised: 05jan82 hv1.1: 20nov82 < 05jan83 01mar84 hv2.0: 26jan88 & 05apr88 16feb91 22oct92 | BBF-Format ESG Time Series Data Files Table of Contents ================= 1.0 Introduction 2.0 File Structure 3.0 Time Series Samples 4.0 Direct-Access I/O 5.0 Some Programming Techniques 6.0 Sample Program 7.0 File Naming Conventions 7.1 DRD (=Digitally Recorded Data) File Names 7.2 AGRAM Data File Names 8.0 Header Blocks 8.1 First Integer Header Block 8.2 First Real Header Block 9.0 BBFILE and TSPLOT: programs that display the Contents of Blocked Binary Data Files 1. Introduction =============== The content of most of the time series data files collected and maintained by the USGS Branch of Enginering Geology and Seismology are all arranged in a similar, somewhat standard format. The files are sometimes referred to as "blocked binary data files" or some abbreviation thereof, like "bbf", because the files are arranged in fixed-sized blocks of binary data. The files are also sometimes referred to as "DR100" files because it was the data recorded with Sprengnether DR100 digital recorders that was the first to be stored in the blocked binary form that later came to be used for almost all the digital seismograms processed by the Branch. Seismograms from a variety of recorders are currently maintained in the blocked binary data files. The file format, especially the contents of the header blocks, has evolved to accomodate various sources of data and various methods for processing the data. The waveforms come from two principal sources: permanently-installed, and portable recording instruments. The permanently-installed strong- motion recorders are usually analog accelerographs producing records that must be digitized before they can be processed with a computer. The portable instruments record acceleration and/or velocity in digital form. The digitized analog data and the digtal-recorded data are processed rather differently in the initial stages of their routine computer processing and the content of the resulting time series data files reflect these differences to some extent. The processed analog data files are called "AGRAM" data files (after the name of the processing software that produces them) to distinguish them from the ***played-back, tidied*** "DRD", or digitally recorded data files. In the meantime, many of the statements that April is uncertain about are flagged with three asterisks (***) to let readers know that Chuck may have more information about the topic or may disagree with the way it is presented here. 2. File Structure ================== Each file is a sequence of 512-byte blocks. Each block contains 256 two-byte binary integer values, 128 four-byte binary real (= "floating-point") values, or, very rarely, 512 ASCII characters. The first several blocks in each file are "header" blocks that contain auxiliary information about the time series samples contained in the remaining "data" blocks. Each file has a minimum of two header blocks, the first of which contains 256 integer values and the second of which contains 128 real values. The time series samples stored in the data blocks may be in either integer or real format. The AGRAM files contain real time series samples and the DRD files usually contain integer time series samples. A single waveform is stored in each file, with the exception of the AGRAM/BUTTER output files. Each BUTTER output file contains data for all the traces on a digitized record, including the reference traces and the time trace. 3. Time Series Samples ====================== The data blocks in the DRD files, and in most of the AGRAM files as well, contain single-valued samples evenly spaced in time. The sample values (real numbers) in most the AGRAM files represent cm/sec/sec, cm/sec, or cm, depending on whether it is an acceleration, velocity or displacement data file. The samples (integers) in the DRD files represent instrument counts that can be converted to other units using instrument characteristic information that is stored in the header blocks or in separate "DBS" files. The factor, F, used to convert instrument counts to cm/sec/sec or cm/sec (depending on whether it is acceleration or velocity data) is F = 1.0/( C * V * G ) where: C = coil constant from the .DBS file, from the file header at RHEAD(51), or default value of .5 for acceleration data or .0068 for velocity data V = counts per volt from the .DBS file, from the file header at RHEAD(46), or default value = 204.8 G = gain from the .DBS file, or = 10.0**(gain/20.) when the gain value comes from the file header at RHEAD (52), or = 128.0, the default value used when no gain is given in a .DBS file or the data file header. *** OOps, do we need the pre-amp gain, RHEAD(53) in here too? *** Note that when the gain value is found in a .DBS file it is a factor, when it is found in the header block of the data file it is in decibels. Although it is not quite ready for general use, there is a subroutine, DIGDAT, on the AGRAMLIB library that can be used to check for the existence of a .DBS file; retrieve the C,V, and G values from the .DBS file, the data file header blocks, or the default list; then calculate the instrument-counts-to-cm/sec/sec conversion factor. If you'd like a copy of a preliminary version of the subroutine, talk to April. *** when and where are there .DBS files? *** Unlike the equally sampled data in most the blocked binary data files, the files produced by the first two programs, BUTTER and SCALE, in the AGRAM process contain unequally spaced samples and consequently contain two values (x and y) for each sample. In BUTTER output files, x and y are in digitization units (=microns if the digitization was done at IOM/TOWILL). In SCALE output files, x is in seconds, and y is scaled, uncorrected instrument response in cm/sec/sec. 4. Direct-access I/O ===================== The blocked binary files need not be read sequentially; the calling program can access any block in any sequence. In FORTRAN, the file access can be done through statements like: lundat = filnam = nih = nrh = nth = array = OPEN (UNIT=lundat,FILE=filnam, X STATUS='OLD', ACCESS='DIRECT', RECL=128, READONLY) READ (lundat,REC= 7+nih+nrh+nth) (array(J), J=1 ,128) READ (lundat,REC= 3+nih+nrh+nth) (array(J), J=129,256) CLOSE (UNIT=lundat) In this example, the code reads the contents of the seventh data block followed by the contents of the third data block (there's no reason why anyone would really want to do that!) into an array named ARRAY. Note the RECL keyword in the open statement. RECL indicates the length of each block (or "record") in the file in "longwords", a longword being 4 bytes. The RECL portion of the OPEN statement could have been omitted in this example because it is an existing file that is being opened. The RECL phrase is required when opening a new file, however. Note the REC= phrases in the READ statements: they indicate which block will be read from the file. Note also that it is real data (i.e., AGRAM-style) that is read from the file in this example. Code using machine-specific I/O operations in place of the FORTRAN I/O statements illustrated above can be more efficient. Such code can avoid the use of FORTRAN buffers, since the i/o is always done for one or more complete disk sectors, and pass the data directly to/from the disk from/to the array space in the calling program. Joanne Vinton once wrote some subroutines to do this via some of the subroutines provided along with the VAX/VMS operating system. For more information, see her instructions on the VAX/750 at TECH:BLOCKIO.MEM. 5. Some Programming Techniques =============================== The first header block, like any block containing integers, contains 256 two-byte integer values. Since integers are 4 bytes long by default in the VAX FORTRAN, some extra attention must be given to code that reads or writes the half-sized integers in the blocked binary data files. The most straight-forward approach is to declare the array in which the integer header values will be kept as an INTEGER*2 array, as in: INTEGER*2 IHEAD(256) ÿ ... READ (lundat,REC= 1) (IHEAD(J), J=1,256) Unfortunately, code that is meant to be portable should not include INTEGER*2 declarations, so another method is used in the AGRAM programs. The information is read into an array of 4-byte (32-bit) integers and subroutine EXPAND (on SMASHLIB and AGRAMLIB) is called immediately afterward to expand the 2-byte integers to 4-byte integers. Example: INTEGER IHEAD(256) ÿ ... READ (lundat,REC= 1) (IHEAD(J), J=1,128) !read 128*4 bytes CALL EXPAND (IHEAD,IHEAD) !now we have 256 4-byte integers Another subroutine, SQUISH, is called immediately before writing a block of integers to a blocked binary data file. SQUISH compacts the integers from 4 bytes back down to 2 bytes. SQUISH merely removes the higher order two-bytes in each integer, but if those two bytes are not zero, SQUISH will not proceed, under the assumption that by some coding error the caller is attempting to write a larger integer than can be stored in 2 bytes onto a blocked binary data file. This can lead to problems if the few integer header cells that contain Hollerith data (e.g., IHEAD(210)) are loaded in an obvious way. Neither IHEAD(210) = 2HAB or IHEAD(210) = 4H AB will work well, for they both leave non-zero bits in the first (highest numeric significance) half of the IHEAD(210) cell. So another SMASHLIB/AGRAMLIB subroutine, PUT2C, is used to insert two hollerith characters into the second (lowest numeric significance) 2 bytes of a 4-byte integer, leaving the first 2 bytes as zero so subroutine SQUISH can handle that header block cell just like any other integer. Subroutine GET2C is the retrieving counterpart to PUT2C. Illustration: On the VAX, i = 2HAB leaves i = 20204241 (hex), i = 4H AB leaves i = 42412020 (hex), call put2c('AB',i) leaves i = 00004241 (hex), where hex 20 represents the blank character. 6. Sample Program ================== There is a little sample program named BBDATA that illustrates how to read and write blocked binary data files. BBDATA does nothing but read a blocked binary data file, plot the data, alter the data slightly by adding a constant to each sample, then write another blocked binary data file. It uses subroutines FREAD2 and FWRIT2 to read and write the files; these subroutines can be called, as is, from other programs or their code can be used as examples. The calling program in BBDATA.FOR and linking command in BBDATA.LNK can be used as a template or first draft when creating a new program that manipulates blocked binary data files. The program, consisting of BBDATA.FOR, BBDATA.LNK, and several .INC include files referenced from BBDATA.FOR, is on the VAX/750 in the directory at GSVAX1::PUB1:[AGRAM.SAMPLE.BBDATA]. The reading and writing subroutines, FREAD2 and FWRIT2, are on the SMASHLIB library on all 3 VAXes (they will soon be on the newer, more portable AGRAMLIB library too). For an example of how to link to the SMASHLIB library, see the BBDATA.LNK file. For general instructions about BBDATA, FREAD, and FWRITE, see the text file at GSVAX1::PUB1:[AGRAM.DOCS]BBDATA.DOC. 7. File Naming Conventions ============================ 7.1 DRD (=Digitally recorded data) file names ============================================== The DRD files usually have names that indicate where and when the record occured. They take the form: JJJHHMMSC.STA, where JJJ is the Julian day, HH is the hour, MM is the minute, S is the second (in letters A-T, each letter representing a 3 second interval), C is the component number (this number is 1, 2, or 3 for acceleration; 4, 5, or 6 for velocity; and 7, 8, or 9 for displacement. and STA is the 3 letter station name. Some examples: **** 7.2 AGRAM Data File Names ========================== The routine, preliminary processing for the AGRAM data is rather different than that for the digitally recorded data. Unlike the digitally recorded data for which there is usually just a single file maintained on the disk for each waveform, there are several files for each waveform processed by the AGRAM programs, each of which represents the waveform after a different stage in the processing. Because there are several files per waveform (and for other reasons too!), the files processed by the AGRAM programs generally do not conform to the digitally recorded data naming convention. The files that result at the end of the AGRAM process could be renamed once processing is complete (they could be renamed, but I don't think they are, as a rule), but during processing the names are: anything.BUT for BUTTER output files, " .R0n for SCALE output files (the n is replaced by the component number: 1, 2,or 3), " .G0n for HIFRIC output files, " .A0n for AVD or CORAVD output files, " .V0n " " , and " .D0n " " . The file name prefix, shown as "anything" above, is some abbreviation that suggests the earthquake and/or station involved. It is not difficult to select a unique name for these analog records, as it is for the digitally recorded records, because there are so few of them. As a result, the names selected for the AGRAM files tend to be easier to remember and type than the DRD file names. 8. Header Blocks ================ The first few blocks in each data file are called header blocks; they contain auxiliary information about the time-series contained in the remaining blocks. There are three types of header blocks: first there are one or more integer headers, followed by one or more real headers, and then possibly some text headers. The contents of the first integer header and the first real header should conform to the conventions listed in sections 8.1 and 8.2. Any other header blocks exist only for the convenience of special-purpose programs and they are not filled according to any generally followed convention. In fact, additional headers are very rarely used; most files have only one integer header, one real header, and no text headers. The lists given in sections 8.1 and 8.2 show what may be stored in each of the cells of the two required header blocks. Many of the cells are rarely used and usually just contain a number that indicates that the value is undefined. ("Undefined" is usually represented by -32768 in integer blocks and by +1.7e+38 or -0.3e-38 in real blocks). Very few of the cells in the required header blocks are filled with anything but "undefined" in the AGRAM files. A single character in the first column of the lists below indicates whether and how the header cell is used by the AGRAM programs: * indicates that the header value is set and used by the AGRAM programs. Or the value will probably be set and used in the future. + indicates that the header value is set by one of the AGRAM programs for information only, the value is not picked up and actually used by another AGRAM program. ÿ . indicates that the header value is not one that is ever set by any of the AGRAM programs, but it is one that some AGRAM programs may use while processing a DRD file. (blank) indicates that the header value is not set or used by any of the AGRAM programs. Although the AGRAM programs do not make use of many of the header values that occur in the DRD files, each AGRAM program does (or should!) copy all the header values from its input file to its output file. Throughout this write-up, and particularly in the lists below, a cell in the required header blocks is refered to as IHEAD(#) or RHEAD(#), just as though IHEAD and RHEAD were arrays in a FORTRAN program into which the first integer header block and the first real header block of a file had been read. A distinction is sometimes made in the lists about which version of the header block convention is applicable. The versions are noted as HV1.0 (header version 1.0), HV1.1 (header version 1.1) and HV2.0 (header version 2.0). There are change-bars in the right- hand margin of the lists below to indicate information that changed with HV1.1 (change-bar = <) and HV2.0 (change-bar = &). There is little difference between HV1.1 and HV1.0: - IHEAD(41) was 'HR' or 'VR' in HV1.0, changed to vertical orientation in degrees in HV1.1. - IHEAD(44) was + or -1 in HV1.0, ignored in HV1.1 Many more header block cells are used in HV2 than were used in HV1 and a few of the cells have a different meaning in HV2 than they did in HV1. The files produced by the AGRAM programs still follow the HV1 conventions (AGRAM programs were insensitive to the difference between HV1.0 and HV1.1); They will eventually be changed to produce HV2 files. Those header cells whose contents have a DIFFERENT meaning in HV2 than they do in HV1 are: - IHEAD( 4), which indicates whether the time series samples are 2-byte integers or 4-byte reals was "undefined" or +1 in the HV1 convention, but are -2 or +4 in the HV2 convention. (IHEAD(4) = IHEAD(HIORR) when using HEADERLOC.INC) - IHEAD(40) was 'FB' or 'VT' in HV1, but is the sensor serial number in HV2 files. (IHEAD(40) = IHEAD(HTTYPE)) - IHEAD(43) was 'AC', 'VL' or 'DP' in HV1, but is a sensor type code in HV2. The type of data identification that the IHEAD(43) cell conveyed in HV1 files is stored (as an integer, not as characters!) in IHEAD(254) in HV2 files. (IHEAD(43) = IHEAD(HAVD); IHEAD(254)= IHEAD(HDDAVD)) - RHEAD(49) is the natural FREQUENCY of the sensor in HV2, not the natural PERIOD as it was in HV1. (RHEAD(49) = RHEAD(HPER)) - RHEAD(98) is the trace mean in HV2, that is, the mean value of the time series contained in the same file as the header in question. In HV1 AGRAM files, this cell contained the mean value of the trace as it was when produced by the SCALE program. This value is (or should be!) subtracted from all the sample values by any program that processes SCALE output files. In HV1 convention, RHEAD(98) did not change when the data was processed beyond SCALE by other programs like HIFRIC or CORAVD. (RHEAD(98) = RHEAD(HVOFFS) for HV1 = RHEAD(HVMEAN) for HV2) The header cells that AGRAM programs will fill in HV2 that are not filled in HV1 are: - IHEAD(5) =2 => header version 2 - IHEAD(6) =0 => header subversion 0 - IHEAD(34-36) = "playback" program information? What shall this be for the AGRAM programs? *** - IHEAD(253) =recording type code, but what will that be for AGRAM files? *** - IHEAD(254) =1,2,3 to indicate acc, vel, or disp Actually, this cell, IHEAD(254), should get set by any AGRAM program that gets modified after march '88. This change needn't wait for the day when ALL the AGRAM programs are changed to conform to HV2 completely. Some changes that may be made to AGRAM HV2 file headers, but that aren't settled yet: - RHEAD(46) May be left undefined in HV2 AGRAM files. In HV1 AGRAM files, this contains the digitizing constant in digitization units/cm (usually = 10000). This is the same cell in which the digitizing constant, as instrument counts per volt, is stored in DRD files. Chuck feels it could lead to confusion if we use the same cell for both quantities. I (April) am quite willing to move it when I convert all the AGRAM programs to HV2, but where to? (RHEAD(46) = RHEAD(HDUNIT)) - RHEAD(47-48) Contains the anti-alias filter characteristics, corner frequency in RHEAD(47) and number of poles in RHEAD (48). In HV1 files, the AGRAM HIFRIC program stored the beginning of transition frequency of its high-cut filter in RHEAD(47) and the transition bandwidth in (48). Since the AGRAM parameters are somewhat different than the digital data parameters that are stored here, Chuck thinks that we may want them stored in different cells. How about moving the AGRAM/HIFRIC filter corner and bandwidth to RHEAD(114) and RHEAD(115), near where the AGRAM/CORAVD filter parameters are stored in HV1? (RHEAD(47) = RHEAD(HAAFC); RHEAD(48) = RHEAD(HAAFR)) - RHEAD(104 - 107): Some of the AGRAM/CORAVD filter info may get moved or duplicated into RHEAD(54-57). This was indicated in Chuck's list. I (April) don't understand yet why this info can't just stay where it is, since the digital data folks don't need to use RHEAD(104-107) for anything else and probably have no need to have the AGRAM/CORAVD filter info in any particular place. Perhaps it is the AGRAM/HIFRIC filter info stored in HV1 RHEAD(47) and (48), not the AGRAM/CORAVD filter info in (104)-(107) that Chuck would like moved to RHEAD(54)-(57) in HV2? If so, there's no need for the Lo-cut info that Chuck's list shows in RHEAD(54) and (55), for HIFRIC only applies a high-cut filter. And the HIFRIC filter is NOT a Butterworth filter, so we want to store a transition bandwith rather than the number of poles Chuck's list shows for RHEAD(57). (HLFFC,HHFFC, etc.) In addition, some conventions used for DRD files that were never noticed by the AGRAM programs also changed when HV2 was established: - IHEAD(10) was a 2-digit year in HV1, a 4-digit year in HV2. - IHEAD(53-58) used for HV1 (GEOS?) trigger info was moved to the real header in HV2. - IHEAD(101-209) used for BUGGER processing is obsolete in HV2. - IHEAD(256) sometimes contained the number of data samples, is obsolete in HV2. - IHEAD(39) sometimes contained a motion type indicator (text) that is obsolete in HV2. A (LT) is shown in the header location lists to indicate that a look-up table may someday be set up to show all the values and corresponding meanings that a given header cell may take. None of these look-up tables exist yet. 8.1 First Integer Header Block =============================== The first header block (like any block containing integer values) contains 256 two-byte integer values. ----- is the cell used by the AGRAM programs? | | | header v location contents - -------- -------- * IHEAD(1) Number of optional integer header blocks that follow this one. * IHEAD(2) Number of optional text header blocks that follow the real header blocks. * IHEAD(3) Integer value that represents "undefined" or "null" (usually = -32768). * IHEAD(4) Data format code. HV2.0: & = -2 if each data block contains 256 2-byte integers & (VAX FORTRAN's INTEGER*2), as they are in most & DRD files; & = +4 if each data block contains 128 4-byte & floating-point values (FORTRAN's REAL), as & they are in the AGRAM files. & HV1.-: . = "undefined" (= IHEAD(3)) if the data samples are 2-byte integers, * = +1 if the data samples are 4-byte reals. * IHEAD(5) Header version number. = "undefined" (for versions 1.0 & and 1.1) or 2 for version 2.0. & * IHEAD(6) Header subversion number. & * IHEAD(7-9): optional header format codes. These will usually be & "undefined". (LT) & * (7) Extra-integer-header format code, & * (8) Text-header format code, & * (9) Extra-real-header format code. & . IHEAD(10-16): "uncorrected" time of first data sample (TFS). For "corrected" time of first sample, add the component sample lag, RHEAD(6), the clock correction, RHEAD(60), and the AGRAM timing adjustment, RHEAD(90). . (10) Year of the event (HV2.0 = 4 digits, as in 1988, & HV1.- = 2 digits, as in 88), . (11) Julian day of year, . (12) Hour of day, . (13) Minute of hour, . (14) Second of minute, . (15) Millisecond of second, . (16) microsecond of second. IHEAD(17-19): information about the time ticks, or "glitches" that are embedded in (some? all?) the DR100 time series. (17) Sample number of the first tick, (18) Amplitude of tick mark (counts), & (19) Number of tick marks detected. & IHEAD(20) Recorder serial number IHEAD(21-22): some info Gary Maxwell and Gary Glassmoyer use with their (GEOS?) data: (21) Sequence number of event on tape, (22) Sequence number of file on tape. & & IHEAD(23-24): File creation time: & (23) year, 4 digits, & (24) julian day. & & IHEAD(27-29): info about the recorder channels: & (27) first active channel, & (28) channel that produced the data in this file, & (29) total number of channels. & + IHEAD(30) Number of components recorded for station ID. * IHEAD(31) Number of data blocks in this file. (header blocks are not included in this count.) * IHEAD(32) Index of the last datum in the last data block. IHEAD(33) Null counter (I think this means the number of "drop-out", or "undefined" values found among the time series samples.) IHEAD(34-36): Playback program info. "Playback" is the process & in which data is read from the tape cartridges written & by a digital recorder onto the mainfraime (PDP/11-70 & or VAX) disk. Some cleanup and rearranging is & performed in the process. & (34) Playback program code (LT) & (35) Playback program version, & (36) Playback program subversion. & & IHEAD(37-39): Recorder info: & (37) Recorder type code (LT), & (38) Recorder version, & (39) Recorder subversion. & & IHEAD(40-43): Sensor info: & (40) HV2.0: Sensor serial number. & . HV1.-: 'FB' or 'VT' to indicate whether the sensor & is a force-balance accelerometer or a velocity & transducer. & * (41) HV2.0 and HV1.1: Vertical orientation, integer degrees < from UP (this will be 90 in data files < representing horizontal motion). < HV1.0: 'HR' or 'VR' to indicate whether the time < series data represents horizontal or vertical < motion. < * (42) Horizontal orientation, integer degrees clockwise from north (This will be 0 in data files representing vertical motion). (43) HV2.0: Sensor type code (LT) & *** really ought to show the commonly used & values here. Linda Seekins has a list *** & * HV1.-: 'AC', 'VL', or 'DP' (acc, vel, or disp) or & 'BU' for BUTTER data, 'IR' for SCALE data. & IHEAD(44) HV2.0 and HV1.1: This item is no longer used. < HV1.0: Before November 1982, this was set to + or - 1 < to indicate polarity of vertical motion. < Vertical motion is now described by IHEAD(41). < IHEAD(50) Recorder location number. & IHEAD(51) Tape number. & IHEAD(52) Trigger algorithm code (LT). & & IHEAD(60-63) AGRAM pad information. These four cells are used by the ADDPAD and REMPAD programs that are sometimes used before and after CORAVD. These cells will also eventually be used by the AVD program that will someday replace CORAVD. They indicate the last sample in the leading pad and the first sample in the trailing pad: (60) number of the block containing the last point in the leading pad; (61) index of that last point within its block; (62) number of the block containing the first point in the trailing pad; (63) index of that first point within its block. IHEAD(208-209) Study information: & (208) Study ID code (LT), & (209) Sub-study code (LT?). & & IHEAD(210-216) file information (for use in case the file is ever & moved or archived somewhere in a manner such that the & original file name and directory is lost) & (210-216) maybe: file name, hollerith ASCII characters. & (217-219) maybe: study name & (220-235) maybe: current filename - extended format & & IHEAD(252) Clock type code (LT) & (i.e., 0 = no clock; 1 = WWVB; 2= external master; & 3 = manual; ...) & IHEAD(253) Recording type code (LT) & (i.e., 0 = continuous; 1 = tirgger; 2= preset; & 3 = generic calibration; & 4 = amplifier calibration; & 5 = sensor calibration; ...) & IHEAD(254) Ground motion unit code (LT) & (i.e., 1 = acceleration in cm/sec/sec; & 2 = velocity in cm/sec; & 3 = displacement in cm; & and maybe others for odd-ball stuff like & the BUTTER files.) & IHEAD(255) Spatial component number. & <1,2,3 instead of the 4,5,6 and 7,8,9 shown in the & file names.> & *IHEAD(200-256) are used differently in (IMPORTed from text to bb) BUTTER output files than in the DRD files and in other AGRAM files. For IMPORTed BUTTER files only: *(200) Number of digitized traces in the file. (There are usually 3 data traces, 1 or 2 reference traces, and 1 time tick trace.) *(201) Type of trace, 1-> time-tick, 2-> reference line, and 3-> data. *(202) Number of the first data block for the trace. *(203) Number of data blocks for the trace. *(204-?) Repeat items (201),(202), and (203) for each trace. 8.2 First Real Header Block ============================ The first real header block is usually the second block on the file. It contains 128 real (4-byte) values. ----- is the cell used by the AGRAM programs? | | | header v location contents - -------- -------- * RHEAD(1) Number of optional real header blocks that follow this one. * RHEAD(2) Real value that represents "undefined" or "null". | On the VAX we originally used = -0.3e-38 for this | value, but when we learned that this value | can't be represented on some computers and some | compilers, we began using +1.7e38. | The PC versions of the AGRAM programs will not | permit any values other than 1.7e38 in RHEAD(2), | except that they will change any -0.3e-38 comming | in from VAX BBF files to 1.7e38. | The PC/AGRAM programs restrict real undefined | to 1.7e38 so they can inspect the value in | RHEAD(2) to determine whether: | a) the file orignated on a VAX, in which | case the PC/AGRAM programs will then change | all the real numbers comming in from the file | from the VAX real-number representation (DEC) | to the PC representation (IEEE); and | b) the file is a BBF-format file or a SMC-format | file. | * RHEAD(5) Sampling rate, samples/second. If undefined, then it's output data from BUTTER or SCALE. . RHEAD(6) Component sample lag (seconds). & This refers to the difference between the time of the first sample in this file and the time of the first sample recorded by the first active channel connected to the same recorder as recorded this data. Samples are taken at a different instant by each channel. For example, a recorder with a .005 second sampling interval and 6 channels would have a component sample lag of 0.0 for the first channel, of 0.0008333 (= .005/6) for the second channel, 0.0016667 for the third channel and so forth. RHEAD(10-19) Source (EQ or explosion) information: . (10) source latitude, degrees . (11) " latitude offset, minutes north of RHEAD(10) . (12) " longitude, degrees . (13) " longitude offset, minutes east of RHEAD(12) (14) " Depth (in kilometers?) (15) " Magnitude (?) (16) " Moment (?) (17) " Weight of explosives (?) (18) " Origin time, (seconds after IHEAD(10).IHEAD(11)?) (19) " -to-station distance? (km) (20) " -to-station azimuth, take-off angle info? (21) " (22) " & (23) " & & RHEAD(24) P-wave arrival time, seconds after FST. & (FST =first sample time) & RHEAD(25) S-wave arrival time (seconds after FST) & RHEAD(40-45) Sensor position info: (40) Sensor latitude, degrees (41) " " offset, minutes north of RHEAD(40) (42) " longitude, degrees (43) " " offset, minutes east of RHEAD(42) (44) " elevation - origin , meters above sea level. (45) HV2.0: Sensor elevation offset, Meters below & RHEAD(44). & HV1.-: Voltage input. & RHEAD(46) Digitizing constant. . This is instrument counts/volt for DRD data (about 200.), and + Digitization units/cm for AGRAM data (usually 10000.). * RHEAD(47-48) Anti-alias filter characteristics. (We may decide to keep only the DRD anti-alias filter characteristics here and move the similar, but not completely equivalent, AGRAM/HIFRIC filter info elsewhere, perhaps to RHEAD(114) and RHEAD(115).) * (47) Anti-alias filter's corner frequency, Hz. (in AGRAM files, this is the freqency used with the combined instrument correction and anti-alias filter in HIFRIC. Other high-cut filters may be applied in CORAVD, but those filter characteristics are described in RHEAD(104 - 113).) * (48) HV2.0: Anti-alias filter poles (roll-off = 6dB/pole) HV1: same as for HV2.0 in DRD files, but in AGRAM files this number represents the anti-alias filter's rolloff bandwidth in Hz. RHEAD(49-51) Sensor characteristics +* (49) HV2.0: Sensor natural frequency, Hz. & HV1 : As for HV2.0 in DRD files, but is the natural & period (NOT frequency), in seconds, in AGRAM & HV1 files. & +* (50) Sensor damping coefficient, fraction of critical & damping. & +* (51) Sensor sensitivity. In DRD files, this is the coil constant in volts/unit (unit=cm/sec/sec or cm/sec). In AGRAM files, this is the transducer sensitivity in cm/g. . RHEAD(52) Digital recorder amplifier gain, dB. (There is no counterpart to this with AGRAM's analog data). RHEAD(53) Pre-amp gain, dB. < what's this?? should it get included when calculating the counts-to-cm/sec/sec conversion factor??> RHEAD(54-57) Analog filter info, HV2.0. This info is stored in & RHEAD(104 -107) in AGRAM HV1 files. & & * (54) HV2.0: Lo-cut filter corner frequency, Hz. & * (55) HV2.0: Lo-cut filter poles (rolloff = 6 dB/octave & per pole) & & * (56) HV2.0: Hi-cut filter corner frequency, Hz. & * (57) HV2.0: Hi-cut filter poles. & & RHEAD(60-61) Clock correction info. . (60) Clock correction, seconds. *** BEWARE: Chuck warns that the clock correction values found in the headers are often (usually?) unreliable. *** . (61) Time since last clock correction (s?) & & RHEAD(62) I don't know what is in here but it was filled in & in some of Mehmet's Whittier Narrows EQ records. & & RHEAD(63-72) HV2.0: Gary Maxwell's trigger info. & RHEAD(70-71) HV1.-: P and S wave picks RHEAD(73-89) Appear to be empty. RHEAD(90-97) min/max, begin/end info. This info has always been kept here (cells #90-97) in & the AGRAM files. Are the DRD folks intending to & fill this space with the same sort of info in the & future? & The times given in this section are in seconds relative to the first recorded sample, as though that first sample occurred at time = 0.0. None of the timing info in RHEAD(60-61) or IHEAD(10-16) is included in these "times". The ordinate values given in this section, for the AGRAM files at least, are in cm/sec/sec, cm/sec, or sec. * (90) Time of first sample in this file relative to the time of the first sample recorded. This is usually = 0.0 or "undefined", but will have some other value in those cases where an AGRAM program has removed or added points to the beginning of a time series. This will occur primarily in files produced by the AVD program (or its temporary predecessor ADDPAD) that include the pre-filter pad in the output file: it will be a negative number representing the length of the leading pad. * (91) Value of the first data point. * (92) Time of the last sample, * (93) Value " , * (94) Time of the maximum value. * (95) Value " * (96) Time of the minimum value. * (97) Value " * RHEAD(98) HV2.0: Trace mean value. This value should be very & close to zero for all but SCALE output files. & *** IMPORTANT: This value must be subtracted & from all the data samples by any program that & processes SCALE output files, for SCALE does & NOT do so itself. The data in files produced & by programs after SCALE in the AGRAM process & is OK, for those programs have subtracted out & the scale offset before any other processing. & * (98) HV1.-: Mean value of the SCALE data. This value is & subtracted from SCALE data by any AGRAM program & that processes SCALE output files (HIFRIC, & TSPLOT, EXPORT) but they leave the SCALE offset & value in RHEAD(98) of their output files. & The following stuff is for AGRAM only, Chuck's list doesn't show anything after RHEAD(98). I'd like Chuck to show these cells as reserved for AGRAM stuff, like he reserved RHEAD(63-72) for Max's trigger stuff. Or maybe we could declare RHEAD(99-128) to be a "scratch" area as HV1 did, so each type of data file could have its own conventions there. We would need to restrain ourselves from storing anything important in there. All this AGRAM trash in 99-128 is used only for reference and/or creating plot labels. * RHEAD(99-102) Info filled in by the AGRAM/CORAVD program: * (99) Beginning time for the least squares fit baseline correction. * (100) Ending time for the least squares fit baseline correction. * (101) Slope of the linear baseline correction. * (102) Intercept of the linear baseline correction. * RHEAD(103) AGRAM source-of-data indicator. Note that the TSPLOT program uses source of data = mod( abs(RHEAD(103)), 20.0) when setting up the plot labels via the "SEB" option. = 1.0 if from SCALE; -1.1 if from ST6PLT; 2.0 if from HIFRIC, with interpolation only; 2.1 if from HIFRIC, with time-domain instrument correction and high-cut filter; 2.2 if from HIFRIC, with frequency-domain instrument correction and high-cut filter; 3.0 if from CORAVD, without long-period filter or linear baseline correction to velocity; 3.1 if from CORAVD, without filter, with linear baseline correction; 3.2 if from CORAVD (or SLOWAVD) with filter and linear baseline correction. 4.x if from BAP. x=> outout from BAP's step # =x. 5.x if from ROTATE. x= whathever number was in RHEAD(103) before the rotating, or =0 if the two files had different values in RHEAD(103). (and maybe someday: 0.0 => this is a BUTTER output file; 20.+=> " COMBINE " ; 40.+=> " ROTATE " ; 60.+=> " IMPORT " . * RHEAD(104-113) Filter info filled in by the AGRAM/CORAVD program: * (104) HV1.-: Low-cut filter roll-off or corner, cps. HV2.0: Shall we move or duplicate this info in & RHEAD(54)? & * (105) HV1.-: High-cut filter roll-off or corner, cps. HV2.0: Shall we move or duplicate this info in & RHEAD(55)? & * (106) HV1.-: Low-cut filter rolloff band width, cps, or integer roll-off parameter (depending on the type of filter used. Note: the roll-off parameter, M, given as input to CORAVD Butterworth filters is 1/2 the "order", N, of the Butterworth filter. And there are 2 poles/order. So number of poles = 2N = 4M. Thus, the rolloff parameter used here to characterize a filter's roll-off is 1/4 the number (= # of poles) that the DRD folks would use to characterize the roll-off in an equivalent filter. See RHEAD(48), RHEAD(55), and RHEAD(57). HV2.0: Chuck wants number of poles in RHEAD(55), & but where will I put transition info if it & isn't a Butterworth filter?? Just keep it & right here, as always, in RHEAD(106)? & * (107) HV1.-: High-cut filter rolloff band with, cps, or integer roll-off parameter. HV2.0: & * (108) Low-cut filter type indicator, * (109) High-cut filter type indicator, =1.,2.,3. or 4. to indicate unidirectional Butterworth filter, bidirectional Butterworth filter, Ormsby filter, or FFT filter. * (110) Low-cut filter padding identifier (1.=> zero fill, 2.=> cosine fill, ... others, too) * (111) High-cut filter padding identifier. * (112) Low-cut Ormsby filter option, * (113) Reserved for high-cut Ormsby filter option, just in case high-cut Ormsbys are ever added to CORAVD. ? (114) Shall we put the HFRIC high-cut filter frequency here that HV1 HFRIC now sets into RHEAD(47)? ? (115) Shall we put the HFRIC high-cut filter transition information here that HV1 HFRIC now sets into RHEAD(48)? ? (114) Shall we put a type of filter indicator here for the HFRIC high-cut filter, similar to the CORAVD filter indicators in RHEAD(108) and (109)? Really isn't necessary, since the present version of HIFRIC always uses the same filter. 9.0 BBFILE and TSPLOT: programs that display the contents of bb files ====================================================================== The BBFILE program can be used to dump all the header blocks and selected data blocks in a data file. BBFILE is an AGRAM program, so you must define all the AGRAM symbols in order to use it. To do so, just: $ @PUB1:[AGRAM]AGRAM.DEF Then, to use BBFILE, try: $ BBFILE !dump will appear on the terminal display $ BBFILE TMP.TMP= ,1,3-5 !the dump will go into the file named TMP.TMP and data blocks #1, 3,4,and 5 will be dumped in addition to the header blocks. or $ HELP BBFILE Another AGRAM program that can be used to show the content of a blocked binary data file is TSPLOT. To get a plot of the time series in a blocked binary data file, type: $ TSPLOT For more information about TSPLOT, type: $ HELP TSPLOT BBFILE and TSPLOT, like most the AGRAM programs, can process DRD files in addition to the AGRAM files.