NAME
relocate - locates all events in a css3.0 database with genloc
SYNOPSIS
relocate dbin dbout [-pf pffile -useold -sift expression]
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
relocate is a Datascope db interface program to a css3.0 database designed for relocating
a complete catalog of events using the genloc package of location routines. The program
will attempt to join all of the following css3.0 tables: arrival, assoc, event, origin, origerr,
site. The program will exit immediately if these tables cannot be joined.
The program uses the generic Gauss-Newton algorithm (ggnloc(3)) of the genloc family
of location programs. Normal procedures for relocation would be to set the -useold
flag (see below) but this is currently the default. The whole suite of initial location
methods of genloc are available through the input parameter file if one choses to use
that approach.
relocate utilizes the automated S-P feature of genloc. That is, if the extension table
called timing is present the program will enable an automated switch to differential times
for time periods when a station has a timing accuracy below a prescribed threshold
(set by the clock_error_cutoff parameter which must be defined in the parameter file
if the timing table is present).
Stations can also be marked as always having bad times through
the bad_clocks parameter.
Note that the phase description parameters, which dbgenloc hides from the normal
user, are required to be inline in the parameter file for this program. To get a start
simply insert the contents of one of the parameter files found in
the directory $ANTELOPE/data/tables/genloc/TT where TT varies for you choice of
travel time calculator.
ARGUMENTS.
dbin is the input css3.0 database with the required tables noted above.
dbout is an
output database. It should probably normally be empty when the program is started. When
the program completes the following tables should be found in the output database: assoc,
event, origin, and origerr. The ones written to the output database are updated for this location
run. Note that a number of static fields in these tables (e.g. comments and phase definitions)
are copied from the input db to the output with no change.
pffile is the parameter file used as control input for the genloc routines. This routine
uses only the standard parameters described in genloc_intro(3). Note also the file searching
features of parameter files described in pf(3).
The -useold flag controls a special property useful in relocation. When this flag appears
on the input line initial locations from the original database are always used as input.
Otherwise the method specified in the parameter file will be used on all data.
The -sift flag compiles the associated expression and uses it to subset the database. For
instance, it is is commonly useful to use an expression like the following:
distance(site.lat, site.lon, origin.lat, origin.lon)<5.0
to remove teleseismic associations from a local network catalog.
DIAGNOSTICS
All the routines here use the error logging routines developed by Dan Quinlan (elog_notify,
complain, register_error, etc.). Many possible diagnostics can be found in this log that
theoretically will help identify the problem. Most errors will only generate one or more
diagnostics being written to the error log. The program should die only if memory allocs fail
or you hit a programming bug.
SEE ALSO
orbgenloc(1), sgnloc(1), dbloc2(1), genloc_intro(3), genloc(3), ggnloc(3), pfread(3), elog(3)
BUGS AND CAVEATS
-
(1)
This program should probably handle events from teleseismic associations more cleanly by
keying off particular fields in the database that are commonly used to indicate this. I felt,
however, that this was hardwiring too many specific features in a code intended to be
relatively general. This can be done by later merging the complementary data with a perl or
tcl script procedure.
-
(2)
Be warned that if a solution blows up in relocation (signalled by ggnloc marking
the solution as bad) it will not be saved in the output database. This means the output
database event count may not match the input. Check the log file for diagnostics about
which events caused problems in this situation.
-
(3)
The program should be improved to allow the input and output database to be the
same and simply change the prefor. This version will cause big problems if
you try this.
-
(4)
Stations using minus phases due to timing problems will not have entries saved
in the predarr table. A valid assoc table will be produced for these arrivals
but the residual saved in the database will be set equal for each arrival
associated with the pair of phases (e.g. P and S in S-P).
-
(5)
There is no way to provide for fixing any coordinate other than depth even though
the genloc library allows this. This is a limit of css3.0 not easily avoided.
AUTHOR
Gary L. Pavlis
Antelope User Group Contributed Software