NAME

dbevents_pre - New version of dbevents

SYNOPSIS

dbevents_pre [-pf pfname] dbname

DESCRIPTION

dbevents_pre displays seismic events out of a Datascope relational database, updating the view as the Database changes. The dbevents_pre display is divided into sevaral horizontal sections. After the menubar and clock at the top row, an event banner shows vital statistics for the event being viewed, including magnitude, geographic region, lat/lon/depth, and time since the event (shown as "T + delta" where delta is a string indicating the time elapsed since the event's origin time, as determined from the computer's internal clock). The event banner's information comes from the currently-selected preferred origin for the event. The magnitude shown by the event banner is a "best guess" as described below for the function:bestmag_string capability of the events_spreadsheet_columns parameter. The next panel consists of a "Focus Map" on the left, then an information-panel on the right. The focus map shows the hypocenter and detecting stations for the event currently highlighted. The information panel shows vital statistics for this earthquake as well as a table of data for each hypocentral solution for the earthquake. Contents of this table are specified in the dbevents_pre parameter file. The information panel contains a table in the upper right showing the latest magnitudes announced by each author for the given earthquake. From left to right the magnitudes are listed in order specified by the magnitude_preference_order parameter of the paramter file. If any of the authors for this latest-magnitude table match regular expressions used as keys in the author_translations array of the dbevents_pre parameter file, the short author name is displayed instead of the actual auth field, and magnitudes for all authors matching this regular expression are coalesced into a single row. If a color is specified for this author in the colors array of the parameter file, the row of the latest-magnitudes table is colored accordingly. Below the latest-magnitudes table, the information panel contains a section for the "best" moment tensor. If there is a moment tensor stored in the mt table associated with the current preferred origin, that moment tensor is displayed. Otherwise, the latest moment tensor issued for any hypocenter for this event is displayed. The bottom panel consists of a regional or global overview map, then a spreadsheet of data with one entry per seismic event. The contents of the spreadsheet are customizable via the dbevents_pre parameter file. Below the bottom panel a status bar shows how long it has been since the database changed (as judged by a subset of monitored tables listed in the parameter file), as well as the names of the tables most recently changed.

OPTIONS

• -pf pfname
  Specify a parameter-file other than the default dbevents_pre.pf.

PARAMETER FILE

Parameter-file Parameters

• allow_edits
  If this boolean parameter is enabled, dbevents_pre allows the user to delete origins or reset the preferred origin for each event. When enabled, a warning label appears on the top menubar indicating that database editing is enabled. When allow_edits is set to a false value, no changes to the database are allowed from dbevents_pre.
• author_translations
  Author fields from the database may be translated via this associative array into more readable forms. Each key in the array is a string or regular expression to be used to match database authors. The value is a short, human-readable version of the author name, e.g. Antelope instead of OtDblMb, followed by the full human-readable translation, e.g. Antelope Real-time System.
• bottomheight_pixels
  This is the default height of the bottom map, i.e. the overview map, in pixels
• center_focusmap
  This parameter specifies the center of the focus map in the upper panel. Most commonly this will be set to the special string focusevent, which tells the map to center on each event when chosen. The center may also be specified explicitly in the format lat:lon.
• center_overviewmap
  This parameter specifies the center of the overview map in the lower panel. This may be set either to the special string focusevent, which tells the map to center on each event when chosen; or the center may be specified explicitly in the format lat:lon.
• clock_tick_sec
  This parameter specifies how frequently the current-time clock is updated.
• colors
  This associative array controls the colors used in the dbevents_pre application. As they are numerous, they are not itemized here, though should hopefully be fairly self-explanatory and/or amenable to quick experimentation. See the Parameter-file Example below. Colors may be any accepted by TCL/Tk e.g. X-windows color names such as red or hex specifications such as #ffe0e0. Note that in the parameter file any hash marks must be preceded by a \ escape character. Colors given to the short versions of author names in the author_translations table will be used to color hypocenters by author in various parts of the GUI.
• dbpick_additional
  This parameter gives additional commands to be sent to dbpick(1) when displaying or changing waveforms.
• dbpick_filter
  This parameter gives an optional filter string to be used when dbpick(1) displays waveforms. If set to 0, no filter is used.
• dbpick_nchannels
  This parameter gives the default number of channels of waveform data to display when dbpick(1) is being used.
• dbpick_phases
  The dbpick_phases parameter lists the seismic phases to be displayed in dbpick(1) for each event.
• dbpick_tstart_sec
  This parameter gives the start time of the waveforms to be displayed by dbpick(1), relative to the time of the hypocenter being displayed.
• dbpick_twin_sec
  This parameter gives the time length of the waveforms to be displayed by dbpick(1).
• dbpickgeom
  This X-windows geometry string gives the window size and location of dbpick(1) when launched.
• dbpicktypeingeom
  This X-windows geometry string gives the window size and location of the dbpick(1) type-in window when dbpick(1) is launched.
• dist_deg_focusmap
  This parameter gives the distance in radial great-circle degrees from the center of the focus map to the outside edge.
• dist_deg_overviewmap
  This parameter gives the distance in radial great-circle degrees from the center of the overview map to the outside edge.
• events_spreadsheet_columns
  The events_spreadsheet_columns parameter contains a table to be given directly to the columns keyword argument of DbTable, as documented in pythonguis(3y). Each entry in this table is an associative array of values specifying the content and characteristics of the column. For further details, see the documentation for DbTable in pythonguis(3y). events_spreadsheet_columns controls the contents of the table of hypocenters shown in the lower panel of dbevents_pre. The displayfield entry for each column may in addition to standard values take on several values that invoke specific functions within dbevents_pre. The displayfield value function:short_author will fill in the author name as translated through the author_translations table of the parameter file. The displayfield value function:mag_string searches the origin and netmag tables for a magnitude associated with the given hypocenter, choosing the first non-null magnitude in order of the magnitude_preference_order parameter. The displayfield value function:mags_string will fill in a semicolon-separated list of magnitudes for the given hypocenter, including those that appear in the origin and netmag tables. The displayfield value function:bestmag_string will fill in a best-guess magnitude for the event. This function begins by looking for a magnitude associated with the preferred origin, choosing the highest-preference as given by the magnitude_preference_order parameter. If no magnitude is present for the preferred origin, the function:bestmag_string begins looking backwards from the most recent hypocenter (judging by lddate in the database) until it finds a hypocenter with a magnitude, again looking in both origin and netmag tables and ranking what it finds according to magnitude_preference_order. The displayfield value function:beachball inserts a thumbnail-sized beachball glyph if there is a row in the mt table corresponding to the origin in question.
• focus_event_bb_size
  This is the size in pixels of the focus event on both the overview and focus maps when the focus_event_symbol is a beachball.
• focus_event_size
  This is the size in pixels of the focus event on both the overview and focus maps. This is overridden by focus_event_bb_size when the symbol is a beachball.
• focus_event_symbol
  This specifies the symbol to be used to plot the highlighted event on both the focus and overview maps. It can be point, cross, x, triangle, square, circle, star, diamond, or beachball. If the latter, a stereographic projection of moment-tensor information will be plotted for any event that has moment-tensor information in the mt database table. If beachball is specified, the value may optionally be followed with an | character and another symbol name to be used when no moment-tensor information is present.
• focus_station_size
  This is the size in pixels of the stations on the focus map.
• fonts
  This array specifies various fonts used in the dbevents_pre application. See the Parameter-file Example below for examples of current font names, which should hopefully be self-explanatory in context of the DESCRIPTION section above.
• magnitude_precision
  This is a floating-point number, defaulting to .1, specifying the print precision for event magnitudes.
• magnitude_preference_order
  This table lists different magnitude types in descending order of preference. All should be listed in lowercase. Any magnitudes encountered that are not listed in this table will be considered to be of lower preference than the ones listed.
• monitor_tables
  This table lists the names of the database tables to monitor. If any of these tables change, the dbevents_pre view is updated.
• origin_spreadsheet_columns
  The origin_spreadsheet_columns parameter contains a table to be given directly to the columns keyword argument of DbTable, as documented in pythonguis(3y). Each entry in this table is an associative array of values specifying the content and characteristics of the column. For further details, see the documentation for DbTable in pythonguis(3y). origin_spreadsheet_columns controls the contents of the table of hypocenters shown in the upper panel of dbevents_pre. The displayfield entry for each column may in addition to standard values take on several values that invoke specific functions within dbevents_pre. For details, see the entry for the events_spreadsheet_columns parameter.
• overview_event_bb_size
  This is the size in pixels of the event on the overview map when the overview_event_symbol is a beachball.
• overview_event_size
  This is the size in pixels of the events on the overview map. This is overridden by overview_event_bb_size when the symbol is a beachball.
• overview_event_symbol
  This specifies the symbol to be used to plot events on the overview map. The options are the same as for the focus_event_symbol as described above.
• overview_station_size
  This is the size in pixels of the stations on the overview map.
• show_waveforms
  If show_waveforms is set to a true value, dbpick(1) is started at launch of dbevents_pre. By default the waveforms are not set to be displayed.
• station_symbol
  This specifies the symbol to use for plotting stations. It may take any of the values specified for focus_event_symbol above, with the exception of beachball.
• time_format
  This parameter takes an escape-string interpretable by epoch2str(3) to translate event origin times into human-readable strings. This string is also used to format the current time for the clock in the upper right of the display. Note that time_format does not control the format of times listed in the spreadsheets, which are separately configured.
• timezone
  This parameter specifies the timezone for display of time strings, e.g. GMT or US/Mountain. If not specified, this defaults to UTC. If left blank or set to the string local, the local time zone of the machine is used. The timezone parameter does not affect times displayed in the spreadsheets, which are separately configured.
• topheight_pixels
  This is the default height of the top map, i.e. the focus map, in pixels
• update_interval_sec
  This parameter specifies the number of seconds between each check of the database for changes.

Parameter-file Example

allow_edits              yes

time_format              %Y-%j (%d %b)  %H:%M:%S %Z
timezone                 GMT

topheight_pixels         600
bottomheight_pixels      400

center_focusmap          focusevent
center_overviewmap       40:-115

dist_deg_focusmap        60
dist_deg_overviewmap     180

update_interval_sec      5
clock_tick_sec           1

show_waveforms           0
dbpickgeom               480x662-100+100
dbpicktypeingeom         100x20-0-0
dbpick_nchannels         33
dbpick_phases            P,pP,S
dbpick_filter            0
dbpick_twin_sec          4000
dbpick_tstart_sec        -800.0
dbpick_additional        swa

station_symbol           triangle

focus_event_symbol       beachball | star
overview_event_symbol    beachball | square

focus_station_size       8
focus_event_size         16
focus_event_bb_size      16

overview_station_size    4
overview_event_size      2
overview_event_bb_size   8

magnitude_precision      .1

magnitude_preference_order &Tbl{
        mw
        mww
        mwb
        mwp
        mwr
        me
        mi
        mn
        ml
        ms
        mb
        md
        mlg
        mblg
}

monitor_tables &Tbl{
        event
        origin
        origerr
        netmag
        mt
}

author_translations &Arr{
#       Regex           Short-name      Long-name
        Ot.*                Antelope        Antelope Real-time System
        USGS.*                USGS                U.S. Geological Survey
        SCSN.*                SCSN                Southern California Seismic Network
        NCSN.*                NCSN                Northern California Seismic Network
        CERI.*                CERI                Center for Earthquake Research and Information
        GSC.*                 GSC                 Geological Survey of Canada
        NBE.*                 NBE                 Nevada Seismological Laboratory
        LCSN.*                LCSN                Lamont-Doherty Cooperative Seismographic Network
        MTECH.*               MTECH               Montana Tech
        UUSS.*                UUSS                University of Utah
}

colors &Arr{
        activebackground           darkgray
        activeforeground           red
        default                    #e0e0e0
        background_evenrows        #f0f0ff
        background_eventbanner     chartreuse
        background_infopanel_focus white
        background_oddrows         white
        background_selected        chartreuse
        background_statusbar       #ffe0e0
        background_scrollbar       lightblue
        boundaries_national        red
        boundaries_minor           #ff00ff
        boundaries_provincial      #00a000
        fill_land                  #fff2e5
        fill_water                 #e0e0ff
        focus_event_bb_fill        yellow
        focus_event_fill           chartreuse
        focus_event_outline        black
        overview_event_bb_fill     yellow
        overview_event_fill        blue
        overview_event_outline     black
        rowedit_warning            red
        station_assoc_fill         lightgreen
        station_defining_fill      blue
        station_fill               gray
        station_outline            black
        USGS                       wheat
        Antelope                   alice blue
        SCSN                       seashell
        NCSN                       honeydew
        CERI                       ivory
        GSC                        pink
        NBE                        light yellow
        LCSN                       mint cream
        MTECH                      light coral
        UUSS                       light salmon
        warning_editable           orange1
}

fonts &Arr{
        spreadsheet                helvetica 10
        statusbar                  helvetica 16
        eventbanner                helvetica 16
        infopanel                  helvetica 12
        infopanel_titles           helvetica 10 bold
}

origins_spreadsheet_columns &Tbl{
        &Arr{
                name                pref
                displayfield        orid == prefor ? "*" : ""
        }
        &Arr{
                name                author
                displayfield        function:short_author
                anchor              w
                width               15
        }
        &Arr{
                name                orid
        }
        &Arr{
                name                depth
                formatter           lambda val: "%.0f km" % val
                width               8
        }
        &Arr{
                name                ndef
        }
        &Arr{
                name                mt
                displayfield        function:beachball
                width               4
        }
        &Arr{
                name                mags
                displayfield        function:mags_string
                anchor              w
                width               21
        }
        &Arr{
                name                latency
                displayfield        strtdelta(origin.lddate-origin.time)
                width               20
        }
        &Arr{
                name                auth
                displayfield        origin.auth
                anchor              w
                width               15
        }
        &Arr{
                name                lat
                formatter           lambda val: "%.4f" % val
        }
        &Arr{
                name                lon
                formatter           lambda val: "%.4f" % val
        }
        &Arr{
                name                time
                formatter           lambda val: stock.epoch2str( val, "%H:%M:%S.%s %Z" )
        }
        &Arr{
                name                nass
        }
        &Arr{
                name                smajax
                formatter           lambda val: "%.1f km" % val
        }
        &Arr{
                name                sdepth
                formatter           lambda val: "%.1f km" % val
        }
        &Arr{
                name                stime
                formatter           lambda val: "%.1f sec" % val
        }
        &Arr{
                name                algorithm
        }
}

events_spreadsheet_columns &Tbl{
        &Arr{
                name                time
                title               origin time
                formatter           lambda val: stock.epoch2str( val, "%Y-%j (%d %b) %H:%M:%S %Z" )
                anchor              w
        }
        &Arr{
                name                evid
        }
        &Arr{
                name                ndef
        }
        &Arr{
                name                reviewed
                title               R
                displayfield        review == 'M' ? '*' : ( review == 'y' ? 'r' : '' )
        }
        &Arr{
                name                prefauth
                displayfield        function:short_author
                anchor              w
                width               15
        }
        &Arr{
                name                mag
                displayfield        function:bestmag_string
                anchor              w
                width               8
        }
        &Arr{
                name                region
                displayfield        grname(lat,lon)
        }
}

EXAMPLE

% dbevents_pre db/gsn

SEE ALSO

dbevents(1)

BUGS AND CAVEATS

The "best magnitude' shown in the event banner and possibly in the events spreadsheet may not show up in the "Latest Magnitudes" table of the information panel, if multiple magnitude-bearing hypocenters for a given author are present and the preferred origin is not the latest-released origin for this author. More sophisticated algorithms would in principle be possible for selection of the "best" moment-tensor for a given event. Often, multiple moment-tensors are releaseed for a single event and it is not always clear which one to give primacy.

AUTHOR

Kent Lindquist