====================================================================== U. S. Department of the Interior, U. S. Geological Survey pick_xwell: A Program for Interactive Picking of Crosswell Seismic and Radar Data Karl J. Ellefsen Open File Report 99-534 URL: http://greenwood.cr.usgs.gov/pub/open-file-reports/ofr-99-0534/ ====================================================================== 1. Overview Program 'pick_xwell' is used to interactively pick travel times in crosswell seismic and radar data. In addition, the traces and the travel times can be plotted on the computer screen or printed to a file in postscript format. The program is written in the IDL programming language, and it is executed, in command-line mode, within the IDL program. The IDL program must be run from an X-window terminal that is connected to a computer with the Unix operating system. The data must be in the SU format. This file 'README.TXT' describes (a) The contents and organization of the tape archive file (section 2). (b) Program 'pick_xwell', its installation, its execution, and the SU data format (section 3). (c) A crosswell data set and the results of processing it (section 4). (d) The address of Reseach Systems, Inc., which distributes IDL (section 5). (e) Information about obtaining the SU software package (section 6). If you find any errors or if you have any suggestions for improving the program, please contact: Karl J. Ellefsen U. S. Geological Survey MS 964, Box 25046 Denver, CO 80225 telephone: 303-236-7032 email: ellefsen@usgs.gov ====================================================================== 2. Contents and Organization of the Tape Archive File The name of the tape archive file (tar file) is 'pick_xwell.TAR', and its contents can be viewed with the Unix command: 'tar tvf pick_xwell.TAR'. In the top level of the tar file is 'README.TXT' --- a copy of this text file. The tar file also contains two directories. In directory 'pick_xwell' are 15 files needed to execute the program and to install the software. All 15 files are described in section 3.1. In directory 'test_data' are four files: one file contains crosswell seismic data; the other three files were generated by program 'pick_xwell' from the crosswell data. All four files are described in section 4. ====================================================================== 3. Program 'pick_xwell' 3.1 Program files In the directory 'pick_xwell' are 15 different files. Of these, 14 files contain the computer code needed to run program 'pick_xwell': File Name Short Description ---------------- ----------------------------------------------- pick_xwell.pro Controls the main menu. read_su_file.pro Reads seismic (or radar) data and travel time picks. The data must be in the SU format. extract_name.pro Extracts the file name from the path plus the file name. For example, if the path plus the file name is '/user/john_doe/data/143.su', the extracted file name is '143.su'. savepicks.pro Saves the travel time picks. pick_wid.pro Controls the menu for picking the travel times and the weights. trace_wid.pro Controls the plotting of the traces. plot_traces.pro Plots the traces to the computer screen or prints the traces to a file. trace_scale.pro Controls the selection of a scaling factor that is applied to the traces when they are plotted or printed. tt_wid.pro Controls the plotting of the travel times. plot_tt.pro Plots the travel times to the computer screen or prints the times to a file. resize_win.pro Resizes the graphics (drawing) window. Help Contains information about the various options in program 'pick_xwell'. This file is ascii text, and so it can be readily printed. (Sometimes, users find that a printed copy of program instructions and other 'help' information is better than reading the same information on the computer screen.) fnc_pick_xwell.c File containing all (c language) functions called by 'read_su_file.pro'. su_head.h File with the (c language) structure of the trace header. This file is an 'include file', which is incorporated into fnc_pick_xwell.c when it is compiled. This structure is for the SU format. There is one more file that may be helpful during the installation of the program: shell.compile. This is a shell program that compiles 'fnc_pick_xwell.c' and then converts it to a shareable object. This program was written for a Sun SPARC operating system; for other operating systems, 'shell.compile' must be modified. ---------------------------------------------------------------------- 3.2 Installation The installation requires four steps: 1. Copy the tar file to a suitable directory on the Unix computer. Extract the contents of the tar file using the command: 'tar xf pick_xwell.TAR'. Make the current directory 'pick_xwell'. 2. Load procedure 'pick_xwell.pro' into an editor and go to line 152. Line 152 and the next seven lines are: ; Initialization of variables that are used in all procedures. ; These four variables may require modification for different ; data sets and different installations of the code. FILENAME_MAX = 80L N_TRACE_MAX = 200L N_SAMP_MAX = 4096L pgm_dir = '/musette/d1/ellefsen/seismic/pick_xwell/' Variable 'FILENAME_MAX' is the maximum length of a file name; variable 'N_TRACE_MAX' is the maximum number of traces in a data file; and variable 'N_SAMP_MAX' is the maximum number of samples in a trace. The values shown above are large enough for most data sets encountered in practice. In some rare cases, however, even larger values might needed. If the values are changed, be sure to append an 'L' to the number. (The 'L' indicates that the number is a long integer.) Variable 'pgm_dir' is the directory with the files needed to run program 'pick_xwell'. This variable is used, during execution,to set the path and to locate the shareable object. When changing this variable, be sure to include the slashes '/' at the beginning and the end. 3. If any of the variables 'FILENAME_MAX', 'N_TRACE_MAX' or 'N_SAMP_MAX' were changed, then load function 'fnc_pick_xwell.c' into an editor and go to line 32. Line 32 and the next two lines are: #define N_TRACE_MAX 200 #define FILENAME_MAX 80 #define N_SAMP_MAX 4096 These c macros correspond to the IDL variables described above. If the IDL variables were changed, then change these macros accordingly. 4. Compile function fnc_pick_xwell.c and load it as a shareable object. If the operating system is a Sun SPARC with an ANSI C compiler, then this step can be done using the shell program 'shell.compile'. For other operating systems, consult p. 106-112 of 'The External Development Guide', version 5.1, (1998). ---------------------------------------------------------------------- 3.3 Input Data The seismic (or radar) data must be in the SU format. This format is used because it is the standard for the SU software package (section 6). For the SU format, the data are stored in a binary file; this file consists of records, one record for each trace. Each record has two parts: the header and the trace itself. Details about this format can be gleaned from studying functions 'read_su_header' and 'idl_read_su_traces', both of which are in 'fnc_pick_xwell.c'. Also study the trace header itself, whose structure is in file 'su_header.h'. (To read data in another format, modify functions 'idl_read_su_header', 'read_su_header', and 'idl_read_su_traces', which are all in 'fnc_pick_xwell.c'.) Program 'pick_xwell' will execute properly if two conditions on the data are met. First, the file name for the data must have the suffix '.su'. For example, a suitable file name is '143.su'. Second, the following items should be set in each trace header: Item Description ---- ----------- ns Number of samples in trace dt Sample rate in micro-seconds cdpt Source number, used for identification cdp Receiver number, used for identification If travel times have been picked from the crosswell data using program 'pick_xwell', then a file containing the travel times will be in the directory used for the crosswell data. Frequently, re-examining the picks of travel times is important. For this reason, program 'pick_xwell' always looks for a travel time file. If the file exists, then it is read. (The name of the travel time file and its format must conform to the conventions described in section 4.2.) ---------------------------------------------------------------------- 3.4 Execution To begin execution of the program, there are four steps: 1. Make the current directory that in which the seismic (or radar) data are stored. Check the shell environment to be sure that the display argument is set to the current X-window terminal. 2. Type 'idl', to load the IDL program. 3. At the prompt 'IDL>', type '.compile XXX/pick_xwell' where XXX is the directory in which 'pick_xwell.pro' is located. 4. At the prompt 'IDL>', type 'pick_xwell' to begin execution. The look and feel of the program is similar to that of most windows programs, and so most users will readily figure-out how the progam works. If a question arises, users can get an answer in the 'Help' documentation, which is loaded when the 'Help' button is pressed. Each option within program 'pick_xwell' causes one or more windows to appear on the X-windows terminal. The locations at which these windows appear is determined by the software controlling the terminal. Thus, these locations vary. When two or more windows appear, one window may be partially obscured by another. This problem can be easily fixed by moving the windows. 5. To exit from program 'pick_xwell', select on the main menu the button 'File' and then select on the submenu the button 'Exit'. At the prompt 'IDL>', type 'exit'. ====================================================================== 4. Test Data In directory 'test_data' are four files, which may be used to test whether program 'pick_xwell' is properly installed. The four files are described in sections 4.1 through 4.4. ---------------------------------------------------------------------- 4.1 File '143.su': Crosswell Seismic Data The crosswell seismic data were collected by the U. S. Geological Survey and are published in Ellefsen and others (1998). The data are in the SU format (section 3.3). The data file contains 54 traces; each trace consists of 1970 samples; the sample rate is 20 micro-seconds. These data were collected between two wells separated approximately by 25 m. (The wells are FSE well 9 and 8; see Ellefsen and others (1998)). Both wells are in bedrock, which consists mostly of schist and granite. Thsee data are a common receiver gather. ---------------------------------------------------------------------- 4.2 File '143.pik': Travel Times and Weights Using program 'pick_xwell', travel times and weights were picked for the crosswell seismic data (section 4.1) and were written in file '143.pik'. This file has four columns: 22 143 6.200e-03 0.000e+00 23 143 6.100e-03 1.000e+00 24 143 6.000e-03 1.000e+00 25 143 5.840e-03 1.000e+00 ... In the first and the second columns are the source and the receiver numbers, respectively. (These number are extraced from the trace header; see section 3.3.) In the third column is the travel time, and in the fourth column is the weight. (A weight of 1 indicates that the travel time is reliable. In contrast, a weight of 0 indicates that the travel time is unreliable and should not be used in any additional processing.) The file name is chosen by program 'pick_xwell'. For example, if the file name for the data is '143.su', then the file name for the travel times is '143.pik'. This file name should not be changed because, if program 'pick_xwell' is run to re-examine the picks of travel times, the program will look for file '143.pik'. ---------------------------------------------------------------------- 4.3 File '143_tt.ps': Plot of the Travel Times In the plot, the ordinate is the travel time, and the abscissa is the trace number. (Trace 1 refers to the first trace in the data file; trace 2 to the second trace; etc.) Travel times with a weight of zero are in red. The file is in postscript format. ---------------------------------------------------------------------- 4.4 File '143_tr.ps': Plot of the Traces The traces are plotted horizontally --- the horizonal axis corresponds to time. The first trace is at the bottom, and the last trace is at the top. ('First' and 'last' refer to the first and the last traces from the data file.) The plot may include the travel times; those travel times with a weight of zero are in red. The file is in postscript format. ====================================================================== 5. IDL IDL (Interactive Data Language) is designed especially for interactive visualization of scientific and technical data. To execute program 'pick_xwell', IDL (version 5.0 or higher for Unix operating systems) must be installed. IDL is not supplied in this tar file; it may be purchased from Research Systems, Inc. 4990 East Pearl Circle Boulder, Colorado 80301 Telephone: 303.786.9900 Email: info@rsinc.com Internet: http://www.rsinc.com ====================================================================== 7. SU 'SU' mean Seismic Unix --- it is a software package for processing and displaying seismic reflection data, and it runs on computers with the Unix operating system and X-windows. These programs also can be used for crosswell seismic and radar data. The package is free and can be obtained from the anonymous ftp site at the Colorado School of Mines, which is ftp.cwp.mines.edu (138.67.12.4). Questions about the software package should be addressed to John Stockwell Center for Wave Phenomena Colorado School of Mines Golden, CO 80401 Telephone: 303-273-3049 Email: john@dix.mines.edu ====================================================================== 7. Disclaimer This open-file report was prepared by an agency of the United States Government. Neither the United States Government nor any agency thereof nor any of their employees makes any warranty, expressed or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed in this report or represents that its use would not infringe privately owned rights. Reference therein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof. Although all data and software in this open-file report have been used by the USGS, no warranty, expressed or implied, is made by the USGS as to the accuracy of the data and related materials and (or) the functioning of the software. The act of distribution shall not constitute any such warranty, and no responsibility is assumed by the USGS in the use of these data, software, or related materials. ====================================================================== 8. Acknowledgements This work was supported by the Toxic Substances Hydrology Program of the U. S. Geological Survey. ====================================================================== 9. References Cohen, J. K., and Stockwell, Jr., J. W., 1999, CWP/SU: Seismic Unix release 33: a free package for seismic reseach and processing, Center for Wave Phenomenon, Colorado School of Mines. Ellefsen, K. J., Kibler, J. E., Hsieh, P. A., and Shapiro, A. M., 1998, Crosswell seismic tomography at the USGS Fractured Rock Research Site: Data collection, data processing and tomograms: U. S. Geological Survey Open-File Report 98-510. External Development Guide, IDL Version 5.1, 1998, Boulder, Colorado: Research Systems, Inc., 324 p. ======================================================================