Binder_ew Configuration File Commands

(last revised July 4, 2011) Page Index:
1. Example configuration file
2. Functional command listing
3. Alphabetic command listing & description

On startup, binder_ew reads the configuration file named on the command-line. Commands in this file set up all parameters used in stacking picks, locating events, and associating phases with events. In the control file, lines may begin with a valid binder_ew command (listed below) or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).
   
@  allows control files to be nested; one control file can be 
   accessed from another with the command "@" followed by 
   a string representing the path name of the next control file 
   (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

1. EXAMPLE CONFIGURATION FILE

# This is binder_ew's parameter file!
#
MyModuleId   MOD_BINDER    # module id for this instance of binder_ew
RingName     PICK_RING     # transport ring for I/O
LogFile      1             # 0 to completely turn off disk log file
HeartbeatInt 30            # Seconds between heartbeats

# List the message logos to grab from transport ring
#              Installation       Module       Message Type
GetPicksFrom   INST_WILDCARD    MOD_WILDCARD    # pick2k

# Set level of output for writing log file
#
log_stack          # comment out to turn of grid-stack logging
hypcode    7

# Load station list
#
maxsite 2000
site_file "calsta.hinv.qa"

# Load Central California crustal model
#
@ncal_model.d

# Define the association grid.  Set stacking parameters.
#
dspace          4.0
grdlat         32.5             43.0
grdlon       -125.0           -114.5
grdz            0.0             20.0
rstack 100.0
tstack 0.65
stack  50
thresh 18
focus  30
grid_wt 0 4
grid_wt 1 3
grid_wt 2 2
grid_wt 3 1

# Set parameters for associating picks with active hypocenters
#
rAvg_Factor 7.0
taper   0.0     1.0
taper   50.0    1.0
taper   200.0   2.5
taper   400.0   4.5
# bfh: 11/5/94: "variable taper" proportional to Origin Time Uncertainty:
# Set both to 0.0 to get Carl's original distance taper only.
taper_OT 2.0 1.0
t_dif   -3.0   120.

# Set parameters for locating events
#
wt 0 1.0
wt 1 0.5
wt 2 0.25
wt 3 0.125
ph P  1.0
ph Pn 0.5
ph Pg 0.5
r_max  400.0
zrange 1.0 30.0
MaxStep 25.0  5.0
MinXYZstep 0.1
MaxIter 4
MaxDeltaRms 1.0001
locate_eq  25   2
locate_eq  50   4
locate_eq  75   8
locate_eq 100  16

# Set parameters for assessing groups of picks
# with Bill Ellsworth's resampling technique:
assess_pk  8  12
maxtrial   500
maxwt      3
v_halfspace  5.0
residual_cut  5.0  10.0
#log_accepted

# Load in the next valid quake sequence number
#
@quake_id.d

# end of parameter file

2. FUNCTIONAL COMMAND LISTING

Below are the commands recognized by binder_ew, grouped by the function they influence. A few of the commands are marked "required"; they describe the Earthworm system setup and network and stacking parameters; these variables have no default values. The required commands must be specified in the control file in order for binder_ew to operate.

	Earthworm system setup:
  		GetPicksFrom	required
 		MyModuleId	required
		RingName	required
		BufferRing	required
			
	Seismic network/model definition:
		lay 		required	
		psratio 	
		site 		\  site list required; specify with
		site_file 	/  either "site" or "site_file"
		maxsite 

	Phase stacking:
		dspace		required
		grdlat    	required 
		grdlon    	required
		grdz		required	
		thresh		required
		define_glitch   
		focus
		grid_wt
		grid_wt_instid
		next_id  (@quake_id.d)	
		EventFileId (to point to quake_id file in case of multiple binder_ew's)
		rstack
		stack
		tstack
		rmsgrid		no longer used

	Event location:
		FixDepth
		locate_eq
		MaxIter
		MaxDeltaRms
		maxpix
		MaxStep
		MinXYZstep
		ph
		r_max
		rmscut
		rmscut_pick
		wt
		zrange

	Phase association:
		rAvg_Factor
		t_dif
		taper
		taper_OT
		no_S_on_Z

	Pick-group assessment:
		assess_pk
		maxwt
		maxtrial
		residual_cut
		v_halfspace

	Output control:
		LogFile		required
		hypcode
		log_accepted    
		log_stack    
		ray
		raytst
		region

3. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and the values used by Calnet are listed after each command description.


command arg1				processed by		function

assess_pk minpk maxpk			assess_com		pick assess

Defines the range for assessing a group of picks using the resampling technique of Bill Ellsworth. When an event has between minpk and maxpk (inclusive) picks associated with it, its pick set will be assessed before the event is relocated. If an event stacks with more than maxpk picks, its picks will be assessed at least once. Pick-assessment is a multiple pass process based on Rex Allen's pick associator. First, the set of picks is examined for glitches. Then the exact, four-station hypocenter solution method of Ingelada and resampling (four picks at a time) are used to determine the station set that is consistent with an earthquake hypocenter. A first pass samples from the earliest (up to 25) P-phase picks which meet the testing criteria; this pass is used to winnow the data to arrivals with median residuals below a cutoff value. A second pass resamples the winnowed data to determine the trial hypocenter. If any picks are rejected as glitches or outliers, they are freed to restack or reassociate. To turn off pick-assessing totally, set minpk and maxpk to zero. Related commands include "define_glitch", "maxtrial", "maxwt", "residual_cut", "v_halfspace".
Default:  assess_pk 6 12                Calnet:  assess_pk 8 12

BufferRing ring				bndr_config		Earthworm setup

Tells binder_ew which shared memory region to use for private ring buffering of picks. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. This rings name must be declared in earthworm.d BUT MOST NOT BE LISTED in startstop.d!!!

Default:  none				Calnet:  BufferRing BINDER_EW_RING

define_glitch npick nsec		grid_com		stack

Sets up the definition of a glitch for filtering arrivals before stacking them. A glitch is defined as at least npick arrivals within nsec seconds. Picks that belong to such a glitch are NOT used in the stacking process. If you want to turn off pre-stack glitch filtering (ie, to make binder_ew stack every pick), set npick to zero (example "define_glitch 0 0.0"). This same glitch definition is used in the pick-assessing process (see command "assess_pk") to recognise glitch-picks that have associated with an event (after it is stacked) and to remove them.
Note: nsec should be set slightly larger than an integer multiple of the pick-timing resolution to avoid missing glitches due to round-off errors in floating point arithmetic (for example, our picks are reported to the nearest 0.01 seconds, so we set nsec to 0.035 sec instead of 0.03 sec).
Default:  define_glitch 4 0.035          Calnet:  define_glitch 4 0.035

dspace dspace				grid_com		stack

Defines the side-length (dspace in km) of a cell in the stacking volume. The same spatial resolution is used for latitude, longitude and depth. Decreasing cell size increases the time required for stacking as the third power, so adjust these values judiciously. The cell size you choose may also depend on your network station spacing; if too many stations fall within the same grid-cell, stacks may often be null- focused.
Default:  none                          Calnet:  dspace  4.0

EventIDFile filename_of_quake_id			bind_com			bind

This allows the operator to run multiple binder_ew instances and have each use a different quake_id file.

Default:  Not SET,  uses quake_id.d by default then

FixDepth dmin trialz			hyp_com			location

Sets the trial depth (km) to use for earthquakes which have no nearby stations. If an earthquake has no picks within dmin km, set its depth to trialz km and locate it with a fixed-depth solution. This prevents events with no depth resolution from flailing.
Default:  FixDepth 50.0 8.0             Calnet:  FixDepth 50.0 8.0

focus nfocus				grid_com		stack

Defines how focused a stack must be to consider declaring a new quake. A stack must have no more than nfocus cells in its maximum-count list and the maximum count value must be greater than or equal to mthresh (see "thresh" command) in order to declare a new event. Since the trial hypocenter is calculated by averaging the center positions of all the cells in the maximum-count list, a larger nfocus will increase the probability of a poor starting location (which has its own attendant problems). A smaller nfocus value, however, will tend to reject distant events. The optimal value for nfocus may also depend on the grid granularity ("dspace" command). Considerable experimentation may be required to determine an optimum value for any specific network.
Default:  focus 5                       Calnet:  focus 30

GetPicksFrom inst mod_id		bndr_config		Earthworm setup

Controls the picks input to binder_ew. Binder_ew will only process picks that come from module mod_id at installation inst. inst and mod_id are character strings (valid strings are listed in earthworm.h/earthworm.d) which are related to single-byte numbers that uniquely identify each installation and module. Up to 2 "GetPicksFrom" commands may be issued; wildcards (INST_WILDCARD and MOD_WILDCARD) will force binder_ew to process all picks, regardless of their place of origin.
Note: both binder_ew and eqproc should be set to listen to the same pick source(s)!
Default:  none
Calnet:   GetPicksFrom  INST_WILDCARD MOD_WILDCARD

grdlat lat1 lat2			grid_com		stack

Defines the latitude range (decimal degrees; positive to the north) of the volume containing all trial stacking hypocenters (set the latitude boundaries of the regional grid). Once an event is stacked, it may relocate outside of this range, and it will continue to associate picks correctly.
Default:  none                          Calnet:  grdlat   32.5   43.0

grdlon lon1 lon2			grid_com		stack

Defines the longitude range (decimal degrees; positive to the east) of the volume containing all trial stacking hypocenters (set the longitude boundaries of the regional grid). Once an event is stacked, it may relocate outside of this range, and it will continue to associate picks correctly.
Default:  none                          Calnet:  grdlon -125.0 -114.5

grdz z1 z2				grid_com		stack

Defines the depth range (km; positive down) of the volume containing all trial stacking hypocenters (set the depth boundaries of the regional grid). The range from z1+(dspace/2) to z2-(dspace/2) must not be greater than the depth range specified in the "zrange" command; otherwise, events may stack outside of the zrange limit and this could cause locator logic errors.
Default:  none                          Calnet:  grdz    0.0   20.0

grid_wt quality increment		grid_com		stack

Allows picks to be weighted in the stacking process based on their quality assigned by the picker. For a pick with a given quality (0 = most reliable, 4 = least reliable), add increment to the count in the cells which meet the stacking criteria. This command is included so that poor quality picks can still contribute to a stack, but with less impact than better quality picks. The increment values set by grid_wt should be reflected in the mthresh value (set by the "thresh" command) used to declare new events (mthresh should be greater than three times the largest grid_wt increment specified). If no "grid_wt" command is issued, only 0-quality picks will be stacked, with an increment of 1. If at least one "grid_wt" command is issued, a pick whose quality was not specified by grid_wt will not used in the stack.
Default:  stack only quality=0 		Calnet:  grid_wt 0 4
          using increment=1			 grid_wt 1 3
					         grid_wt 2 2
					         grid_wt 3 1

grid_wt_instid quality increment instid            grid_com                stack

Allows picks to be weighted in the stacking process based not only on the quality assigned by the picker, but also by the installation id that produced them. For a pick with a given quality (0 = most reliable, 4 = least reliable) from a given instid (character string found in earthworm_global.d), add increment to the count in the cells which meet the stacking criteria. This command is included so that picks from one installation can be weighted differently in a stack than picks from another installation and should only be used by networks that are exchanging pick information. The increment values set by grid_wt_instid and grid_wt should be reflected in the mthresh value (set by the "thresh" command) used to declare new events (mthresh should be greater than three times the largest increment specified). If no "grid_wt_instid" or "grid_wt" command is issued, all 0-quality picks will be stacked, with an increment of 1. If at least one "grid_wt_instid" or "grid_wt" command is issued, a pick whose quality and/or instid was not specified will not used in the stack. grid_wt_instid commands can be used in combination with grid_wt commands; a "grid_wt" command is equivalent to a "grid_wt_instid" command with instid set to INST_WILDCARD.
Default:  stack only quality=0         Example:  grid_wt        0 4 
          from any installation                  grid_wt        1 3
          using increment=1                      grid_wt_instid 2 2 INST_MENLO
                                                 grid_wt_instid 2 0 INST_CIT

hypcode	value				bind_com	 	output

Sets a value to specify how much information should be included in binder_ew's log file after each event relocation. Possible values (0-7) and the corresponding output are a sum of:
0 no output from locator (default)
1 include summary location for each iteration
2 include final phase description for each associated pick
4 include final rms and dmin
Generally, this parameter should only be included during testing and tuning, since significant increases in the size of the log file and a corresponding decrease in associator efficiency is incurred when it is present and non-zero.
Default:  hypcode 0

lay depth velocity			t_com			model

Defines the layered velocity structure to be used for calculating travel times. depth is the distance (km) to the top of the layer, and velocity is the seismic P-wave velocity (km/sec) within that layer. No default velocity structure is defined; therefore, the user must always supply one in the control file. Up to 20 layers can be specified, and they should be listed in order of increasing depth.
Default:  none				Calnet:  lay   0.0  4.0
						 lay   3.5  5.9
						 lay  15.0  6.85
 						 lay  25.0  7.85

locate_eq npick interval		bind_com		location

Allows intermittent relocations of an event; an earthquake with more than npick picks will relocate with every additional interval picks associated. This increases binder_ew's efficiency by skipping cpu- intensive relocations of stable events. Up to 10 "locate_eq" commands can be supplied (in order of increasing npick values) to set multiple npick-break-points and location intervals. An event with fewer picks than the smallest npick value will locate after each additional pick is associated.
Default: locate after every pick	Calnet:  locate_eq  25   2
						 locate_eq  50   4
						 locate_eq  75   8
						 locate_eq 100  16

LogFile switch				bndr_config		output

Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, binder_ew will write a daily log file(s) called binder_ewxx.log_yymmdd where xx is binder_ew's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). The amount of information written to the file(s) can also be controlled with the "log_stack" and "hypcode" commands.
Default:  none

log_accepted				assess_com		output

Tells the pick-assessing function (see "assess_pk" command) to log detailed information for all accepted picks, in addition to info about rejected picks. If this command is ommitted, only information about picks rejected as glitches or outliers will be written to the log file.
Default:  don't log accepted picks	

log_stack				grid_com		output

Tells the program to print a graphical representation of the stack to the log file each time a new hypocenter is declared. Each grid cell in the depth layer containing the hypocenter is represented by a value (0-9,a-z) denoting the number of "hits" in that cell. The trial hypocenter is found by averaging the positions of all the cells which have the maximum number of hits.
Default:  don't log the stack 

MaxDeltaRms factor			hyp_com			location

Sets a factor in the test for divergence of an event's average weighted residual (rms). Solution diverges if rms > previous rms * factor.
Default:  MaxDeltaRms 1.01		Calnet:  MaxDeltaRms 1.0001

MaxIter num				hyp_com			location

Sets the maximum number of iterations to perform on each relocation.
Default:  MaxIter 4			Calnet:  MaxIter 4

maxpix maxpix				hyp_com			location

Defines the maximum size of the problem that can be accommodated by the location algorithm. Sufficient space is allocated to allow the location of an event with maxpix picks. The reason for providing this command is so that space need only be allocated once, preventing considerable overhead in the location process.
Default:  maxpix 256			Calnet:  maxpix 256

maxsite nsite				site_com		model

Allocates memory to store nsite station locations in the site table.
Default:  maxsite 1000			Calnet:  maxsite 1000

MaxStep xystep zstep			hyp_com			location

Sets maximum limits (km) on the horizontal (xystep) and vertical (zstep) distance a hypocenter can move in each iteration. If either value is exceeded, all 4 dimensions (x, y, z and time) of the step- vector are equally damped, preserving the direction of the vector, such that each dimension is within its limit.
Default:  MaxStep 10.0 2.0		Calnet:  MaxStep 25.0  5.0

maxtrial ntrial				assess_com		pick assess

Restricts the pick-assessing process to a maximum of ntrial resamplings. Given n picks sampled 4 at a time, the total number of unique combinations is n!/(4!*(n-4)!). If this number is less than ntrial, all possible combinations will be considered, with no duplication. If the total is greater than ntrial, then ntrial random samples of 4 picks will be considered, and duplication is possible.
Default:  maxtrial 500			Calnet:  maxtrial 500

maxwt wt				assess_com		pick assess

Defines the maximum pick quality wt to consider in the resampling pick-assessing process (see "assess_pk" command). wt must be a character from 0 thru 4. Picks with qualities higher than wt (poorer quality) may be rejected as glitches, but will not be used in resampling to find outliers.
Default:  maxwt 3			Calnet:  maxwt 3

MinXYZstep minstep			hyp_com			location

Defines the step length (km) at which to stop iterating. If the x-y-z step is less than minstep km, the hypocenter is considered stable and no more iterations are done on this call to hyp_l1.
Default:  MinXYZstep 0.1		Calnet:  MinXYZstep 0.1

MyModuleId mod_id			bndr_config		Earthworm setup

Sets the module id for labeling all outgoing messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number.
Default:  none				Calnet:  MyModuleId MOD_BINDER_EW

next_id quakeid				bind_com		stack

Defines the sequence number (quakeid+1) to assign to the next stacked event. Each time an event is created, binder_ew updates a file called "quake_id.d" which contains next available sequence number in the "next_id" command. To ensure sequential, non-duplicated event id's between runs, the parameter file "binder_ew.d" must contain the command "@quake_id.d". If this command is omitted, event sequence numbers will be issued beginning at 1 each time binder_ew is restarted.
Default:  next_id 1 			Calnet:  @quake_id.d	

Don't try and associate a vertical channel pick as an S phase. If horizontal
channels are picked on, there is a possibility that a vertical could be used for a horizontal
S phase (probably not the best idea in most cases). This simple flag, no argument needed, will
prevent any S phases from being associated on a vertical component pick.
Default: off

ph phase weight bind_com location
Allows for differential weighting and
exclusion of
various associated phases in the event location process. The weighting
is based on the phase assigned to the pick by the associator.
phase can be any of
P, S, Pn, Sn, Pg, or Sg

weight can be a number between 0.0 and
1.0, inclusive
If no "ph" commands are supplied, all phases receive a
phase-weight of 1.0. If at least one "ph" command is supplied, other
phases that have not been listed by "ph" are weighted 0.0. The overall
weight of a pick in the location is the product of its phase-weight and
quality-
weight ("wt" command) divided by the taper value ("taper" command)
at the appropriate distance.
Default: all phases/1.0 weight Calnet: ph P 1.0
ph Pn 0.5
ph Pg 0.5

psratio value t_com model
Sets the value of the P/S seismic
velocity ratio.
Default: psratio 1.72 Calnet: psratio 1.72

r_max rmax bind_com location
Sets the maximum epicentral distance (km)
for
weighting picks in the location process. Picks from stations at
distances greater than rmax km are not
weighted.
Default: r_max 150.0 Calnet: r_max 400.0

rAvg_Factor factor bind_com association
Sets a factor (scalar) which
controls the
distance cutoff for associating picks with a given event. If a pick is
from a station at an epicentral distance greater than factor*(average
epicentral distance of all associated picks), binder_ew will not
attempt to assocate that pick with that event.
Default: rAvg_Factor 10.0 Calnet: rAvg_Factor 7.0

ray z r t_com output
Prints the travel time from an event at z km depth to a station on the surface at an
epicentral distance of r km. This command is
used mostly for testing, but might be of some interest in checking
travel
time calculations or plotting travel time curves.

raytst z rmax rdel t_com output
Prints out something dealing with the
velocity model
and travel times.

region z rmax rdel t_com output
Prints out the travel times of all
possible phases
at series of points on the surface from an earthquake at z km depth. Those surface points are at epicentral
distances from rdel km to rmax
km and are spaced rdel km apart. This
command, mostly for testing, is useful for plotting travel-time curves.

residual_cut median mad assess_com pick assess
Sets cutoff thresholds (in
seconds) for
travel-time residuals in the
pick-assessing process. Given a group of picks, up to ntrial
(see "maxtrial" command) hypocenters are determined from various
combinations of four picks. For each pick, the travel-time residual is
calculated with respect to each hypocenter using a uniform-velocity
halfspace. If the absolute value of the median of those residuals is
greater than median sec, the pick is rejected
as an outlier. And if the median of the absolute deviations from the
median residual is greater than mad sec, the
pick is also rejected as an outlier.
Default: residual_cut 3.0 10.0 Calnet: residual_cut 3.0 10.0

RingName ring bndr_config Earthworm setup
Tells binder_ew which shared memory
region to use
for input and output. ring is a character
string (valid strings are listed in earthworm.d) that relates (in
earthworm.d) to a unique number for the key to the
shared memory region.
Default: none Calnet: RingName PICK_RING

rmscut value bind_com location
Sets a maximum value (seconds) for the
average absolute residual (rms) for a successful location. If this value is exceeded as a result of
culling, scavenging, or associating a new phase, the event is marked as
destroyed and all of its phases are deassigned.
Default: rmscut 1.0 Calnet: rmscut 1.0