NAME
BUEventView - BRTT utility for earthquake event view formation
SYNOPSIS
-lbuplotqt
#include "BUEventView.h"
DESCRIPTION
BUEventView objects are complete views of earthquake event information
from underlying databases. They are intended to be dynamic in response to
changing databases. Information from events, origins, origin errors, associations, arrivals, detections, stations, magnitudes,
waveform measurements and moment tensors are joined in a set of views that are returned as special
structures. ALl of the joins are accomplished using
dbmatches(3).
CONSTRUCTORS
BUEventView(Pf *params=NULL);
BUEventView(...);
With the following constructor arguments:
-
params
An Antelope parameter file object pointer that contains the BUEventView object
parameters. The parameters are described below.
-
...
A variable argument list composed entirely of character string key-value pairs with
a single NULL terminating argument. This is an alternate method for specifying
the BUEventView object parameters. The parameters are described below.
METHODS
-
void numbers (long *events, long *origins, long *detections, long *arrivals, long *assocs, long *mts, long *magnitudes);
Returns total numbers of events from the event table, origins from the origin table, detections
from the detection table, arrivals from the arrival table, assocs from the assoc table, mts
from the mt table and magnitudes, from the netmag table.
-
int reset ();
This causes all internal matches to be deleted, the database to be closed and then re-opened. Note that existing views returned by the various refresh...
methods may no longer be valid.
-
Returns 0 if there are no errors or -1 if there are errors.
-
int checkChanges (Arr **changes);
This will check to see if tables have grown or shrunk or been modified since the last refresh... method calls. The results are returned in
an associative array, *changes, which is allocated by this method (it is first freed if *changes is non-NULL). The returned associative
array will have keys corresponding to each database table name which has changed and the values will be long ints
of BUEVENTVIEW_TABLE_SMALLER, BUEVENTVIEW_TABLE_BIGGER or BUEVENTVIEW_TABLE_MODIFIED, according to how the table has changed. If tables have changed,
then the various database pointers in the various view Tbls may be stale and should be updated with appropriate calls to the various refresh... methods.
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshEvents (Tbl **events);
This reads all of the events from the underlying database and joins these with
the appropriate origins. In addition, the refreshOrigin method (see below) is used on
each of the origins which causes the related origin errors, network magnitudes and moment tensors
to be joined for each origin. Preferred values for origin, magnitude and moment tensor are also set.
Note that the associations, arrivals, stations, waveform measurements
and station magnitudes are not refreshed with this method.
if *events is non-NULL on entry, then the events are first freed with a call to freeEvents (see below).
The event views are returned in *events as a set of BUEVEvent structures.
typedef struct BUEVEvent {
long evid; /* event evid */
Dbptr dbevent; /* event row from event table */
Tbl *origins; /* table of BUEVOrigins */
BUEVOrigin *pref_origin; /* preferred origin for this event */
BUEVMagnitude *pref_magnitude; /* preferred magnitude for this event */
BUEVMoment *pref_moment; /* preferred moment tensor for this event */
} BUEVEvent;
-
Returns 0 if there are no errors or -1 if there are errors.
-
int sortEvents (Tbl *events, long sort_type);
This will sort event in Tbl events according to sort_type which must be set to
one of BUEVENTVIEW_SORT_EVENTS_LDDATE, meaning to sort according to decreasing event table lddate field,
or BUEVENTVIEW_SORT_EVENTS_LDDATE_VIEW, meaning to sort according to decreasing lddate of the largest origin table lddate for
each event within this event view.
-
int refreshOrigin (long dborigin_recno, BUEVOrigin *origin);
This reads an origin row from the underlying database, as specified by dborigin_recno, the record number in the database origin table, and
fills in a BUEVOrigin structure, as specified by *origin. The associated origin error (origerr table), network magnitudes (netmag table),
and moment tensors (mt table) are read. Also, preferred magnitude and moment tensor are determined. Note that associations,
arrivals, detections, waveform measurements, stations and station magnitudes are not read. This method is typically called automatically by refreshEvents
but it can be called manually.
typedef struct BUEVOrigin {
long orid; /* origin orid */
long ndef; /* origin number of defining associations */
long nass; /* origin number of all associations */
double time; /* origin time */
double lat; /* origin latitude */
double lon; /* origin longitude */
double depth; /* origin depth */
double lddate; /* origin load date */
int preferred; /* if set then this is the preferred origin */
Dbptr dborigin; /* corresponding origin row from origin table */
Dbptr dborigerr; /* corresponding origin error row from origerr table */
Arr *stations; /* array of BUEVOriginStations index by sta code */
Tbl *associations; /* table of BUEVAssociations */
Tbl *detections; /* table of BUEVDetections */
Tbl *magnitudes; /* table of BUEVMagnitudes */
Tbl *moments; /* table of BUEVMoments */
BUEVMagnitude *pref_magnitude; /* preferred magnitude for this origin */
BUEVMoment *pref_moment; /* preferred momdent tensor for this origin */
} BUEVOrigin;
typedef struct BUEVMagnitude {
long magid; /* netmag magid */
char magtype[8]; /* network magnitude type */
double magnitude; /* network magnitude value */
Dbptr dbnetmag; /* corresponding netmag row from netmag table */
Tbl *stamags; /* table ofBUEVStamags */
} BUEVMagnitude;
typedef struct BUEVMoment {
long mtid; /* mt mtid */
double lddate; /* moment tensor load date */
double m[6]; /* moment tensor components as per bumoment(3) */
Dbptr dbmt; /* corresponding mt row from mt table */
} BUEVMoment;
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshAssociations (BUEVOrigin *origin);
This reads association rows from the underlying database for a previously refreshed BUEVOrigin structure specified by origin
and then calls refreshAssociation for each association which causes arrival and station information to be read and joined.
Note that station magnitudes, detections and waveformmeasurements, are not read. The associations are returned in the associations and stations members of the origin structure.
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshAssociation (BUEVOrigin *origin, BUEVAssociation *association);
This reads an assoc row from the underlying database, as specified by dbassoc_recno, the record number in the database assoc table,
for a previously refreshed BUEVOrigin structure specified by origin, and reads and joins the arrival and station information.
This method is typically called automatically by refreshAssociations but can be called manually.
typedef struct BUEVAssociation {
long arid; /* assoc and arrival arid */
Dbptr dbassoc; /* corresponding assoc row from assoc table */
Dbptr dbarrival; /* corresponding arrival row from arrival table */
BUEVOriginStation *station; /* corresponding BUEVOriginStation structure */
} BUEVAssociation;
typedef struct BUEVOriginStation {
BUEVOrigin *origin; /* corresponding origin */
char sta[16]; /* station code */
double lat; /* station latitude */
double lon; /* station longitude */
double elev; /* station elevation */
double distance; /* station distance from origin */
double predicted_P_time; /* station predicted P time */
double predicted_S_time; /* station predicted S time */
Dbptr dbsite; /* corresponding site row from site table */
} BUEVOriginStation;
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshDetections (BUEVOrigin *origin, int all=0);
This reads and makes a join of detection rows from the underlying database for a previously refreshed BUEVOrigin structure specified by origin.
If all is set to non-0, then join captures any detections that are within 5 minutes before the origin time up to 2 hours after the
origin time on all stations and channels. If all is set to 0, then the detection times are compared to the predicted P arrival
times at each station and only the detections with the smallest residuals for each station are captured.
The detections are put into the origin structure's detections table.
typedef struct BUEVDetectionStachan {
char sta[16]; /* corresponding station */
char chan[16]; /* corresponding channel */
double lat; /* station latitude */
double lon; /* station longitude */
double elev; /* station elevation */
double distance; /* distance to selected origin */
double predicted_P_time; /* predicted P arrival time to selected origin */
double predicted_S_time; /* predicted S arrival time to selected origin */
Dbptr dbsite; /* corresponding site row from site table */
} BUEVDetectionStachan;
typedef struct BUEVDetection {
double time; /* detection time */
double residual; /* time residual relative to predicted P arrival */
double lddate; /* detection load time */
char phase[16]; /* detection phase */
Dbptr dbdetection; /* corresponding detection row from detection table */
BUEVDetectionStachan station; /* corresponding site parameters */
} BUEVDetection;
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshDetections (Tbl **detections, double to, double t1);
This reads and subsets detection rows from the underlying database according to a time range, t0 to t1. A table of
BUEVDetection values are returned for each detection within the time range.
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshStamags (BUEVMagnitude *magnitude);
This reads stamag rows from the underlying database for a previously refreshed BUEVMagnitude structure specified by magnitude
and then calls refreshStamag for each stamag which causes waveform measurement information to be read and joined.
The station magnitudes are returned in the associations and stations members of the magnitude structure.
This is typically used with the magnitudes table elements in the BUEVOrigin structure.
-
Returns 0 if there are no errors or -1 if there are errors.
-
int refreshStamag (long dbstamag_record, BUEVStamag *stamag);
This reads a stamag row from the underlying database, as specified by dbstamag_recno, the record number in the database stamag table, and
fills in a BUEVStamag structure, as specified by *stamag. The coresponding waveform measurement (wfmeas table) is read and joined.
This method is typically called automatically by refreshStamags but can be called manually.
typedef struct BUEVStamag {
long magid; /* stamag magid */
double magnitude; /* station agnitude value */
Dbptr dbstamag; /* corresponding stamag row from stamag table */
Dbptr dbwfmeas; /* corresponding wfmeas row from wfmeas table */
} BUEVStamag;
-
Returns 0 if there are no errors or -1 if there are errors.
-
BUEVEvent *findEvid (Tbl *events, long evid);
This will find and return the BUEVEvent structure pointer corresponsing
to evid in the table returned by refreshEVents(). A NULL return
indicates that the evid could not be found, or an error.
-
BUEVEvent *findEvid (long evid);
This will find and return the BUEVEvent structure pointer corresponsing
to evid in entire database. Note that this structure must be freed with a call to freeEvent. A NULL return
indicates that the evid could not be found, or an error.
-
BUEVOrigin *findOrid (BUEVEvent *event, long orid);
This will find and return the BUEVOrigin structure pointer corresponsing
to orid in the BUEVEvent struicture.
indicates that the orid could not be found, or an error.
-
BUEVOrigin *findEvid (long orid);
This will find and return the BUEVOrigin structure pointer corresponsing
to orid in entire database. Note that this structure must be freed with a call to freeOrigin. A NULL return
indicates that the evid could not be found, or an error.
-
void freeEvents (Tbl *events);
This frees all BUEVEvent structures in an events table.
-
void freeEvent (BUEVEvent *event);
This frees a single BUEVEvent structure.
-
void freeOrigins (Tbl *origins);
This frees all BUEVOrigin structures in an origins table.
-
void freeOrigin (BUEVOrigin *origin);
This frees a single BUEVOrigin structure.
-
void freeAssociations (Tbl *associations);
This frees all BUEVAssociation structures in an associations table.
-
void freeStations (Arr *stations);
This frees all BUEVOriginStation structures in a stations array.
-
void freeDetections (Tbl *detections);
This frees all BUEVDetection structures in a detections table.
-
void freeMagnitudes (Tbl *magnitudes);
This frees all BUEVMagnitude structures in a magnitudes table.
-
void freeMoments (Tbl *moments);
This frees all BUEVMoment structures in a moments table.
-
void freeStamags (Tbl *stamags);
This frees all BUEVStamag structures in a stamags table.
This frees all BUEVAssociation structures in an associations table.
OBJECT CONFIGURATION PARAMETERS
-
dbname dbname
Name of underlying database.
SEE ALSO
dbmatches(3)
AUTHOR
Danny Harvey, BRTT