NAME
dbevents - Graphical event display for seismic events in Datascope database
SYNOPSIS
dbevents [-allow_remote_fs] [-nfsok] [-pf pffile] [-pftraceview traceview_pffile]
[-show_traces] dbname
DESCRIPTION
dbevents displays seismic events out of a Datascope relational
database, updating the view as the Database changes. Three panels
show, from left to right: first an overview map of the entire
database; second a detail map highlighting the currently selected
event; and third an origins map showing the hypocenters (
origin
table entries) for the currently selected event. Two spreadsheets
are provided with the maps. The first spreadsheet lies just below
the overview map, listing distinct events in the database, with
metadata from their preferred-origin. The second spreadsheet lies
under the selected-event and origin maps, listing metadata for each
origin for the selected event. The dividers separating the three
maps and the spreadsheets may be moved, optionally hiding entire
sections from display.
The
dbevents display will update based on changes in the
database
dbname, unless the
update_interval value in
the parameter-file is set to
0.0.
A right-click with the mouse on an event or origin glyph will launch
the command specified in the parameter-file
external_commands
array. See the PARAMETER FILE section for details.
OPTIONS
-
-allow_remote_fs
Normally, only locally mounted database files are allowed. This option allows all database files
to be used.
-
-nfsok
Same as specifying -allow_remote_fs.
-
-pf pffile
This is the name of the dbevents parameter file. It defaults to dbevents.
-
-pftraceview traceviewpffile
This is the name of the parameter file used to configure the traceview display. It defaults to dbevents_traceview.
-
-show_traces
This will cause the traceview display to be shown at startup.
-
dbname
This is the name of the database and must be specified.
Color Codes
Extensive information about events in a database is directly visible
through the symbol characteristics used in the
dbevents
display. Symbols vary by size, shape, color, and opacity. These
symbols update dynamically as the database changes, providing a
powerful diagnostic for database health and real-time-process tuning.
Some of the most useful codes are as follows:
-
circles, red-outline: selected event and preferred origin
Red outlines are used around the currently selected event on event
maps, and around the preferred origin on origin maps. When the
update_interval parameter in the dbevents parameter-file
is non-zero, dbevents automatically selects the most recently
updated event [Note that this might not be the event with the most
recent origin time] whenever the database changes.
-
circles, fill color:
The fill colors for event symbols are governed by the settings in
the map toolbar and may be constant, coded by earthquake size, or
coded by depth. As also controlled by the map toolbar, circles for
events may be replaced with beachball diagrams for those events
that have moment-tensor solutions (entries in the mt table)
listed in the database.
-
circles, opacity:
As controlled by a map toolbar button, circle symbols for earthquakes
may be shown either without fading, or with opacity fading at progressive ages
of 1 hour old, 1 day, 1 week, 1 month, and 1 year.
-
circles, size:
As controlled by a map toolbar button, circle symbols for earthquakes
may be shown all at the same size, or at sizes that depend on earthquake magnitude.
Currently, the circle-sizes are binned into earthake magnitudes of
4 and below, 4 to 7, and 7 and above. When earthquake symbols are set to
display at constant (non-magnitude-dependent) size, the selected earthquake is
enlarged for clarity.
-
ovals, translucent:
For hypocenters in the database that have error-ellipse information
in the origerr table, dbevents shows translucent ovals
around the origin in the origins-map panel (far right, if shown).
-
triangles, cyan outline: station detections
Station symbols are outlined in cyan for stations that have detections
for the event, where the detection was entered into the database
before the corresponding origin (detection lddate less than origin lddate).
-
triangles, magenta fill: defining station arrivals
Station symbols and are filled in magenta for stations that have
defining arrivals for the event.
-
triangles, orange fill: non-defining station arrivals
Station symbols are filled in orange for stations that have
non-defining arrivals for the event.
-
triangles, cyan fill: station detection only
Stations that have a detection only, with no accompanying arrival in the
arrival table, will be shown filled cyan.
-
triangles, yellow fill: late station detection only
Stations that have a late detection only (detection lddate after origin lddate),
with no accompanying arrival in the arrival table, will be shown filled yellow.
-
travel-paths, color:
Great-circle travel paths from station to event are shown in the arrival color (magenta or
orange) if a station has an arrival for the corresponding
event. The travel paths are shown in the detection color (cyan or
yellow) if a station has only a detection (no arrival table entry) for the corresponding
event.
PARAMETER FILE
Parameter-file Parameters
-
width
This parameter specifies in pixels the width of the entire dbevents window. If can
be either in pixels or if it ends with a s character, then it is a fraction of the
screen width.
-
height
This parameter specifies in pixels the height of the entire dbevents window. If can
be either in pixels or if it ends with a s character, then it is a fraction of the
screen height.
-
mapevents_width
This parameter is the fraction of the total dbevents width of the events panel of the dbevents window.
-
mapevents_height
This parameter is the fraction of the total dbevents height of the events panel of the dbevents window.
-
mapevents_range
This parameter specifies the range in degrees shown in the events panel of the dbevents window.
-
mapevent_width
This parameter is the fraction of the total dbevents width of the event panel of the dbevents window.
-
mapevent_height
This parameter is the fraction of the total dbevents height of the event panel of the dbevents window.
-
maporigins_width
This parameter is the fraction of the total dbevents width of the origins panel of the dbevents window.
-
traces_width
This parameter is the fraction of the total dbevents width of the traces panel of the dbevents window.
-
update_interval
This parameter specifies the interval in seconds at which dbevents is updated. If this
is zero, the map will not be updated.
-
auto_select_event
This controls whether or not an event is automatically selected
when a database change has been detected. If set to mostrecent, then
the most recent event is automatically selected when it changes.
If set to lastmodified, then
the last modified event is automatically selected when it changes.
If set to no, then events are not automatically selected.
-
mapevents_taskbar_states
This is a table that specifies initial taskbar states for the main events display window.
The basemap definitions can be found in bqmap_defaults.pf.
-
mapevent_taskbar_states
This is a table that specifies initial taskbar states for the selected event display window.
The basemap definitions can be found in bqmap_defaults.pf.
-
traceview_taskbar_states
This is a table that specifies initial taskbar states for the waveform display.
-
traceview_sift
This parameter specifies a station-channel sifter for the traceview display
-
traceview_commands
This is a table that specifies the traceview commands executed when the display is created.
-
events_tableview
This is an associatove array that must contain column_definitions associative array and column_names
table for specifying the events tableview display. See BQEVEventsTableview(3).
-
origins_tableview
This is an associatove array that must contain column_definitions associative array and column_names
table for specifying the origins tableview display. See BQEVOriginsTableview(3).
-
map_area_features
This array allows the user to specify additional area features to draw on the maps, such as areas of responsibility etc.
Each area feature must have a unique nickname, used as the key in the map_area_features array. This key in turn has a
value which is a sub-array giving the details for the area feature being described.
-
map_area_features{maps}
This parameter should be a table itemizing which maps in dbevents should display the requested feature. The entries should
be one or more of the strings dbevents_events, dbevents_event, and dbevents_origins, for the corresponding maps as described above.
-
map_area_features{color_outline}
This parameter must be a string name for a color, acceptable to the pythonbqplot(3) library calls. This color will be used
to draw the outline of the area feature.
-
map_area_features{color_fill}
This parameter must be a string name for a color, acceptable to the pythonbqplot(3) library calls. This color will be used
to fill the area feature. Transparency may be specified via alpha-channel color codes.
-
map_area_features{linewidth}
This parameter must be an integer width in pixels for the line representing the outline of the area feature.
-
map_area_features{lonlat_points_sequence}
The lonlat_points_sequence table gives a sequential list of geographic points that trace out the area feature.
Each line of text in the lonlat_points_sequence table should specify a single geographic point of the area feature's boundary, stating first the longitude and then the latitude
of the point, with longitude and latitude values separated by one or more space characters.
The first point in the list should be repeated at the end of the list to force closure of the area boundary.
-
external_commands
When a glyph representing an event or origin is right-clicked in the dbevents map, this array is used to present
any configured external-command options.
If the glyph represents an event, the command(s) in the event sub-array are shown in a pop-up list of buttons.
If the glyph represents an origin, the command(s) in the origin sub-array are shown in a pop-up list of buttons.
-
external_commands{event}
Each row of this table should contain a button-name followed by a command to execute when the button is pushed. If the user
right-clicks on an event glyph in dbevents, a pop-up menu is displayed with the button names from this table. When one of these
buttons is clicked, the corresponding external command is executed.
Command substitution is performed prior to execution.
The token %dbname is substituded with the dbname string from the command line.
The token %evid is substituded with the current evid value.
The token %orid is substituded with the current orid value.
-
external_commands{origin}
Each row of this table should contain a button-name followed by a command to execute when the button is pushed. If the user
right-clicks on an origin glyph in dbevents, a pop-up menu is displayed with the button names from this table. When one of these
buttons is clicked, the corresponding external command is executed.
Command substitution is performed prior to execution.
The token %dbname is substituded with the dbname string from the command line.
The token %evid is substituded with the current evid value.
The token %orid is substituded with the current orid value.
-
map_linear_features
This array allows the user to specify additional linear features to draw on the maps, such as bounding areas, fault lines, etc.
Each linear feature must have a unique nickname, used as the key in the map_linear_features array. This key in turn has a
value which is a sub-array giving the details for the linear feature being described.
-
map_linear_features{maps}
This parameter should be a table itemizing which maps in dbevents should display the requested feature. The entries should
be one or more of the strings dbevents_events, dbevents_event, and dbevents_origins, for the corresponding maps as described above.
-
map_linear_features{color_outline}
This parameter must be a string name for a color, acceptable to the pythonbqplot(3) library calls. This color will be used
to draw the linear feature.
-
map_linear_features{linewidth}
This parameter must be an integer width in pixels for the line representing the linear feature.
-
map_linear_features{lonlat_points_sequence}
The lonlat_points_sequence table gives a sequential list of geographic points that trace out the linear feature.
Each line of text in the lonlat_points_sequence table should specify a single geographic point of the linear feature, stating first the longitude and then the latitude
of the point, with longitude and latitude values separated by one or more space characters. For linear features that show a boundary line that
closes on itself, the first point in the list should be repeated at the end of the list to force rendering of the last line segment in the
feature.
Parameter-file Example
update_interval 1.0
width 0.9s
height 0.8s
mapevents_width 0.333
mapevent_width 0.333
maporigins_width 0.0
traces_width 0.333
mapevents_height 0.6
mapevents_range 140.0
mapevent_height 0.75
auto_select_event mostrecent
mapevents_taskbar_states &Tbl{
basemap:demw
projection:globe
boundaries:on
urban:on
parks:on
roads:on
rivers:on
}
mapevent_taskbar_states &Tbl{
basemap:bluemarble
projection:merc
boundaries:on
rivers:on
}
traceview_taskbar_states &Tbl{
pal:on
spa:on
stad:on
filter:0.01HP
}
external_commands &Arr{
event &Tbl{
echo echo Event dbname,evid are %dbname,%evid
}
origin &Tbl{
echo echo Origin dbname,orid are %dbname,%orid
}
}
traceview_scsift .* .* # station-channel sifter for the traceview display
traceview_commands &Tbl{ # these traceview commands will be executed when the display is created
traces maximum 33
traces configure predicted_phases P,S
traces auto_distance_sort yes
display time_window 1800
display palign yes
traces filter BW 0.8 4 3.0 4 \#0.8-3 BP
}
events_tableview &Arr{ # specifications for events spreadsheet
column_definitions &Arr{
event_row &Arr{
label event_row
text_template XXXXXXXXXXX
source events[%index].recno_event
sort recno_event
alignment e
format %9d
}
origin_row &Arr{
label origin_row
text_template XXXXXXXXXXX
source events[%index].recno_event
sort recno_event
source events[%index].origins[pref_origin].recno_origin
sort origins[pref_origin].recno_origin
alignment e
format %9d
}
time &Arr{
label time
text_template XXXXXXX XX/XX XX:XX:XX.XXX
source events[%index].origins[pref_origin].record_origin{epoch2str(time, "%Y%j %m/%d %T")}
sort origins[pref_origin].time
alignment e
}
lat &Arr{
label latitude
text_template XXX.XXXX
source events[%index].origins[pref_origin].record_origin{lat}
sort origins[pref_origin].record_origin{lat}
format %8.4f
alignment e
}
lon &Arr{
label longitude
text_template XXXX.XXXX
source events[%index].origins[pref_origin].record_origin{lon}
sort origins[pref_origin].record_origin{lon}
format %9.4f
alignment e
}
depth &Arr{
label depth
text_template XXX.XX
source events[%index].origins[pref_origin].record_origin{depth}
sort origins[pref_origin].record_origin{depth}
format %6.2f
alignment e
}
evid &Arr{
label evid
text_template XXXXXXXXX
source events[%index].evid
sort evid
format %9d
alignment e
}
orid &Arr{
label orid
text_template XXXXXXXXX
source events[%index].prefor
sort prefor
format %9d
alignment e
}
ndef &Arr{
label ndef
text_template XXXX
source events[%index].origins[pref_origin].record_origin{ndef}
sort origins[pref_origin].record_origin{ndef}
format %4d
alignment e
}
nass &Arr{
label nass
text_template XXXX
source events[%index].origins[pref_origin].record_origin{nass}
sort origins[pref_origin].record_origin{nass}
format %4d
alignment e
}
auth &Arr{
label auth
text_template XXXXXXXXXXXX
source events[%index].origins[pref_origin].record_origin{auth}
sort origins[pref_origin].record_origin{auth}
alignment e
}
region &Arr{
label region
text_template XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
source events[%index].origins[pref_origin].record_origin{grname(lat,lon)}
sort origins[pref_origin].record_origin{grname(lat,lon)}
alignment e
}
magnitude &Arr{
label magnitude
text_template XXXXXXXXXX
source events[%index].magnitude;events[%index].magtype
sort magnitude;magtype
format %4.2f;(%s)
alignment e
null -999.00()
}
}
column_names &Tbl{
evid
magnitude
auth
time
region
lat
lon
depth
ndef
nass
event_row
origin_row
}
}
origins_tableview &Arr{ # specifications for origins spreadsheet
column_definitions &Arr{
origin_row &Arr{
label origin_row
text_template XXXXXXXXXXX
source origins[%index].recno_origin
sort recno_origin
format %9d
}
time &Arr{
label time
text_template XXXXXXX XX/XX XX:XX:XX.XXX
source origins[%index].record_origin{epoch2str(time, "%Y%j %m/%d %T")}
sort time
alignment e
}
latency &Arr{
label latency
text_template XXX:XX:XX:XX.XXX
source origins[%index].record_origin{strtdelta(lddate-time)}
sort record_origin{lddate-time}
alignment e
}
lat &Arr{
label latitude
text_template XXX.XXXX
source origins[%index].record_origin{lat}
sort record_origin{lat}
format %8.4f
alignment e
}
lon &Arr{
label longitude
text_template XXXX.XXXX
source origins[%index].record_origin{lon}
sort record_origin{lon}
format %9.4f
alignment e
}
depth &Arr{
label depth
text_template XXX.XX
source origins[%index].record_origin{depth}
source+sort record_origin{depth}
format %6.2f
alignment e
}
orid &Arr{
label orid
text_template XXXXXXXXX
source origins[%index].orid
sort orid
format %9d
alignment e
}
ndef &Arr{
label ndef
text_template XXXX
source origins[%index].record_origin{ndef}
sort record_origin{ndef}
format %4d
alignment e
}
nass &Arr{
label nass
text_template XXXX
source origins[%index].record_origin{nass}
sort record_origin{nass}
format %4d
alignment e
}
auth &Arr{
label auth
text_template XXXXXXXXXXXX
source origins[%index].record_origin{auth}
sort record_origin{auth}
alignment e
}
magnitude &Arr{
label magnitude
text_template XXXXXXXXXX
source origins[%index].magnitude;origins[%index].magtype
sort magnitude;magtype
format %4.2f;(%s)
alignment e
null -999.00()
}
}
column_names &Tbl{
orid
latency
auth
magnitude
depth
time
lat
lon
ndef
nass
origin_row
}
}
EXAMPLE
% dbevents db/gsn
SEE ALSO
dbevents_dep(1), dbevents_dep2(1), install_mapdata(1), traceview(1), BQMapLayer(3)
AUTHOR
Danny Harvey
Kent Lindquist