dbloc2 - interactive hypocenter location
dbloc2 [-r] [-p pf] db
dbloc2 is a collection of several programs
which run together under the control of a perl script, dbloc2.
It facilitates the location of hypocenters from previously
picked trace data, while allowing interaction with the location program
and the ability to edit arrival picks. It can also
attempt to associate groups of arrivals with other catalogs, for instance
the PDE or REB catalogs.
You must begin with a database db which contains at least site and arrival. If
you wish to display waveforms and add picks, you must also have wfdisc,
sensor, sitechan, and instrument. The arrival, origin, assoc, event
and lastid tables must be writable. Generally, you run dbloc2
from the directory containing the database
or in a directory with a database descriptor file which references the database.
Note that if
more than one person is running dbloc2
simultaneously on a database, they should agree among themselves on
how to split up the events, so that everyone is working on different
events.
It's important that the database itself be self consistent:
run dbcheck(1) and dbverify(1) on the database before starting dbloc2
if you have any question or are just beginning to use dbloc2.
Start the program with:
dbloc2 your-database
The main window should be fairly easy to understand. From top to bottom,
there are several different panels, corresponding to the sequence of
operations to locate events.
dbloc2 first groups arrivals together using a time window.
Directly under the menu bar are a set of buttons and sliders which control
this grouping operation. Basically, you can control the time window
size and the start time. When you're reviewing a catalog, you can
choose to search for unassociated arrivals; associated arrivals may still
appear, but the grouping skips past arrivals which are already associated.
Arrivals are displayed graphically in the next lower panel. The station
name is displayed along the left edge, along with a distance in degrees.
The names appear on buttons which bring up menus to
display some additional information. In the main body of this window,
each arrival appears as a button. Arrivals here have three states:
selected, ignored, residual only. Selected arrivals are fed to the
location program; ignored arrivals are not. Finally, some arrivals may not
participate in the determination of the location, but the location
program does calculate a residual.
You may toggle between selected and ignored with the left mouse button on
an arrival button, or set to residual only with the middle mouse button.
The buttons visually indicate the current state.
Pressing the right mouse button on an arrival brings up a menu showing
more information about the arrival and allowing you to select or
ignore azimuth and slowness associated with that arrival (if these
were measured).
You may also select a collection of arrivals by dragging the mouse
around them. This is faster for a large collection than individually
selecting each. Shift drag zooms in on a smaller portion of the
time window, sometimes making it easier to select arrivals.
(Beware: the motion is subtly different from the corresponding dbpick
zoom. It's not a shift-click-release, shift-click-release, but rather
shift,click,drag,release-button,release-shift. Occasionally, you may
click multiple times by mistake and the screen may then take a long time
to recover).
There is a row of buttons along the bottom of the arrival panel which
may help select certain arrivals. The "Show map with reporting stations"
button brings
up a new window showing the arrival locations and origin locations.
The origin panel shows the current "working set" of origins. This
includes
-
origins previously in the database and associated with one or more of the
arrivals.
-
prospective associated origins copied from a catalog (like the pde or reb
catalog)
-
origins generated by running a location program.
By default, after origins are displayed and when the analyst goes on
to the next event or quits, the review field in origin is set to y.
This behavior may be modified using the radio buttons
Mark reviewed, Leave as-is, and Mark NOT reviewed
dbloc2 accumulates a set of origins and associations in a temporary
database: tmp/trial. It's up to the user to select the origins from
this which should be saved back to the main database
(or kept in the case of origins already
in the database). This is done with the second column of buttons in the
origin panel, which toggle between Keep/Delete/Reassoc/Chop for
previous origins,
and Drop/Save for new origins.
When an arrival associated with a previous origin is moved or deleted,
the database has been compromised. dbloc2 detects this situation (by
running dbloc_verify to compare
lddate in the origin, assoc and arrival tables).
In this situation, you have the following choices:
-
Delete
delete the offending origin;
you might also relocate the event with the new arrivals.
-
Reassoc
recalculate the associations by adding the difference between
the original arrival time and new arrival time to the residual time in the
assoc record. This only works if the arrival was moved in this session,
as dbloc2 caches the original arrival times when they're first displayed.
-
Chop
keep the origin, but delete the corresponding assoc records.
You must also select a preferred origin if there is
more than one origin per event, using the third column radio button.
If there are multiple events in the time window, it may be necessary
to explicitly set the event id (evid) using menus under the the
leftmost column of buttons.
You may set the etype field in origin by using the menu under the Etype
column. The default set of selections is qb, eq, me,
ex or - (null), but you may change this by using the
etype parameter in the parameter file.
The menus under the left column also allow rearranging the arrivals
display to a) select only the associated arrivals, and b) show
the residuals graphically using arrows and by removing the moveout
(predicted travel time) for each arrival.
The latter operation makes the time
scale in the window relatively useless, but tends to put all the
P and S arrivals in straight vertical line.
The next panel down runs location programs. You can choose a program
and a travel time model.
You can fix the depth and try different starting locations; many
programs are sensitive to the starting location.
Generally, dbloc2 sets the location of the first station
as the starting location.
You can also start the location from any already existing origin, using
an option under the menu for that orid.
By experimenting with starting conditions, fixing the depth, choosing
other models, selecting
different arrivals and perhaps adding or adjusting arrivals,
you may be able to find locations for grouped arrivals.
There are also situations where a location is elusive; this
may arise due to model problems, due to overlapping events,
due to timing errors, inadequate data, or even problems in
the database. (If you suspect the last, run dbverify(1) on the
data).
dbloc2 coordinates with dbpick(1) to display waveforms if they're available.
The controls are a bit confusing, however. Generally, you should use
the Show waveforms button to bring the dbpick(1) display to the front,
or Hide waveforms to iconicize dpbick.
Other controls
in this panel affect whether predicted arrivals are shown, how many channels
appear in the dbpick window, and what channels (all, only z, only channels
with arrivals).
If the arrival panel is showing a modified time scale with moveout
removed, the dbpick window does also.
It's possible to bring up a single station to inspect an arrival
pick using a menu option under the right mouse button on an arrival in the
arrival panel.
dbloc2 prints short messages into a scrolling one-line window just above the
button bar at the bottom of the screen. The window can be scrolled using the
arrows on the right. The View->error_log menu brings up a window with all
these messages and errors which is sometimes more convenient.
Along the bottom of the dbloc2 window are a number of buttons, which
correspond to the usual sequence of actions: Next (group of arrivals),
Locate (using selected arrivals), and Associate (using selected arrivals).
Each Next action saves any origins which have been marked to save.
Under the right mouse button, there are additional menus for Next and
Associate. The Next menus allow associate and next to be called after
each next action. The Associate->Controls option allows adjusting the
association controls a bit.
The waveforms, map and database buttons bring up dbpick, a location
map, and dbe respectively. There are options under the right mousebutton
for these buttons also.
-
-r
Remove the tmp directory before starting. It's sometimes useful to
delete the tmp directory during restarts, when the program seems to
be very confused.
-
-p pf
Select a parameter file name different from the default dbloc2.pf.
dbloc2 stores many intermediate files into a new directory tmp in the
current directory. This directory should not be modified by the user.
see antelopeenv(5)
You may copy the dbloc2 parameter file into the directory where you
are running dbloc2. This file has a number of sections; you should
probably only modify the User section. Here are the parameters from that
section:
-
Institution
This (short) code shows up as part of the origin author field.
-
travel_time_models
Should be the list of models which are installed in
$ANTELOPE/data/tables/dblocsat and $ANTELOPE/data/tables/tttaup.
-
location_programs
dblocsat2(2) and/or dbgenloc(1)
-
reference_db
one or more catalogs (in the form of CSS 3.0 origin tables)
-
depth_list
The list of starting depths in the Location panel Depth menu.
-
starting_depth
The default starting depth
-
Presidual_max
-
Sresidual_max
The residual errors change color from blue to orange when the
residual exceeds the spec.
-
dbpick_time_window
Default dbpick time window when displaying waveforms
-
dbpick_max_channels
Default number of channels to display at once on the dbpick window
-
dbpick_waveform_lead_time
Default number of seconds to lead the first arrival by in the dbpick
window.
-
save_programs
When the save button is pressed, dbloc2 copies selected origins from the trial
database in tmp to the main database, and may delete some origins from
the main database, or recalculate assoc residuals, or delete assoc records
for selected origins. With more complex location programs, it may
be necessary to update other tables also. This entry provides a method
for that. Each entry in this list is run with the name of a parameter
file which contains the names of the main and trial databases, and lists
of the orids for origins to be saved, removed, reassociated or recalculated.
(The parameter file is named tmp/origin_save.pf; here's an example:
database demo2
trial tmp/trial
save 1967 1968
delete 1938
reassoc 1940
chop 1941
-
magnitude_calculators
Whenever a new location is found, programs from this list
are run to calculate a magnitude for that event. Antelope provides
one standard program dbml(1) for calculating Ml; users may
add others. The program should expect to be run with an
execution line like:
dbml tmp/trial orid
The parameter file for dbml contains some
station dependent information. To point the dbml program to
a parameter file other than the default, modify the dbml line in
this list to specify the correct file, eg "dbml -p knet".
Magnitude calculators should determine from the database whether
they are appropriate for a particular origin, and only add to the
database when they are. Any output the program makes to stderr
appears in the scrolling one line status near the bottom of the screen.
-
run_magnitudes_automatically
It may be desirable to run magnitude programs on demand rather
than automatically for every location, if the time required to
run the magnitude program is long. This can be accomplished by
setting this parameter to no, causing a button to appear
next to the locate button. Pressing the new button will run
the magnitude programs against the current orid.
-
allow_direct_magnitude_calculations
-
override_previous_magnitude_authors
The user may wish to recalculate a magnitude (or calculate a different
magnitude) for some automatically located event. This can be done
from dbloc2, but involves immediate modification of the main database
instead of the trial database. In this case, the Save or Next
button has no effect on the results, which are written directly into
the database.
To set this up, first set allow_direct_magnitude_calculations
to yes.
Then list the different authors for which these calculations are allowed.
You might not wish to allow the recalculation for magnitudes from
other catalogs, for instance.
-
crunch_at_quit
dbloc2 generates null rows in the database when it deletes old origins.
When this parameter is set to yes (the default is no), these marked rows
are automatically deleted (crunched) out of the database. This operation
is not safe for a live database attached to a real time system.
-
arrival_menu_items
-
origin_menu_items
-
station_menu_items
You may choose to add your own commands to the arrival buttons or
station buttons (in the arrival panel) or the origin buttons (in the
origin panel), by adding to these (by default empty) lists. Each
additional line in one of these lists adds a new option to the
corresponding menus. The name for the new option is the leading
(blank-delimited) word on the line; the remainder of the line is the
(command-line) command which is to be executed. The pathname for the
corresponding table and the record number for the corresponding record
are appended as additional arguments to this command. For example,
the following line in the arrival_menu_items list: The pathname for
the corresponding table and the record number for the corresponding
record are appended as additional arguments to this command. For
example, the following line in the arrival_menu_items list:
Repick repick
would result in a new option Repick in each arrival button menu.
Selecting this option would cause the command repick to be
executed, with the arrival table name and arrival record number
appended, something like this:
repick /d/example/demo2.arrival 185
Similarly, adding lines to the origin_menu_items or station_menu_items
lists causes new menu options to be added to the origin and station
buttons.
-
etype
This parameter is a blank separated list of options for the origin
etype field, which may be set using the menu under Etype in the origin panel.
antelopeenv(5)
dbpick(1), dbe(1), dblocsat2(1), dbgenloc(1)
warp(1)
dbloc2_location_if(3)
-
The most convenient way to run dbloc2 is with two screens,
one for displaying waveforms, the other for the dbloc2 controls.
-
Sometimes, the program seems to get all bollixed up, perhaps
even freezing. In this case, the best thing to do may be
to kill the window, and then kill dbloc2 (the script), and all
its children, which should all be named dbloc_*.
Sometimes, it's also desirable to delete the tmp directory altogether;
the -r option makes this a bit easier.
-
If the program gets into a state where the first set of
arrivals never appears, you may want to try logging out and
logging back in.
-
For security reasons, tcl/tk restricts (does not allow)
communication with the "send"
command if any host is enabled with the xhost(1) command.
Because dbloc2 uses send extensively, this means dbloc2 does NOT
work at all if you enable any hosts with the xhost command.
When you run xhost with no arguments, you must see no hosts
enabled for dbloc2 to run.
-
dblocsat2 and dbpick compute travel times differently: dbpick
uses a tau-p computation with no elevation (station) corrections.
dblocsat interpolates from tables, and applies an elevation (station)
correction.
This means that the predicted arrivals displayed by dbpick do not necessarily
match the residuals computed by dblocsat2.
-
If you move an arrival, previous origin associations are invalidated,
dbloc2 usually catches this situation by comparing the modification
times for the arrival, assoc and origin records (running dbloc_verify(1)).
However, this can be mystifying and frustrating. See above for the
options in this situation.
-
A lot of debugging information
is saved in the file tmp/log. When reporting bugs, please use the
program dbloc_report_bug(1), or run dbloc_snapshot(1) directly to package
up some useful information about the program state and the database.
You can run dbloc_report_bug directly from dbloc2 under the File menu.
-
dbloc2 requires that the event table in an existing database be properly
filled out; origins without a corresponding event row are not displayed.
-
dbloc2 and dbpick (the trace display) can get out of sync, so that
the arrivals shown in the dbloc2 window don't correspond to the time
window in the dbpick window.
-
Only one instance of dbloc2 can be run per display, because the underlying
interprocess communication uses fixed names: dbloc_buttons and dbpick.
Daniel Quinlan
Table of Contents
Antelope Release 4.8 Darwin 8.7.0 2006-09-26
Boulder Real Time Technologies, Inc
For more information, contact support@brtt.com