NAME
db2ims - publish an IMS 2.0 short DMC modified bulletin from a css3.0 database
SYNOPSIS
db2ims [-a] [-v] [-V] [-y] [-p pf] [-s start_origin.time] [-e
end_origin.time] [-l logfile] [-d db]
database
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
db2ims looks at a css3.0
database and summarizes event and phase
information in the DMC short IMS 2.0 bulletin format. The output of the program
is a text file that should be sent to the DMC. Use the
ims2dmc script to
send the output file from
db2ims to the DMC and to track it in a
dmcbull table.
db2ims requires the following database tables: arrival, assoc, origin,
origerr, event, and snetsta. The netmag and stamag tables are use if available.
The input database should pass dbverify origin, assoc
and event checks cleanly.
OPTIONS
-
-p pf
Name of parameter file (default is db2ims.pf)
-
-v
Verbose log messages
-
-V
Overwhelmingly verbose log messages. Useful for debugging purposes only.
-
-y
Only select reviewed origins. This is probably the preferred mode of operations.
Any origins which do not have the review field in the origin changed to "y" are
not included. Note that for a real-time system where you have an analyst
reviewing the database with dbloc2 (changing the review field to "y")
and new external bulletins associated and chosen as prefor
(with dborigin2orb/orb2dbt), you can get an origin that is chosen as
the prefor, but not marked as reviewed. Events that fall into this category
are skipped and not reported in the output file despite having one solution/origin
that is marked as reviewed. ALL solutions must be marked as reviewed for the
event to be included in the output file.
-
-a
Sent all associated origins, not just the prefor and the mag_origin_auth in the pf file.
Beware that this may cause significant heartburn if you are sending data to the IRIS DMC
as they have limited capacity to receive all the origin data.
-
-s start_time
Select origins after this time.
-
-e end_time
Exclude origins after this time.
-
-t lddate
Exclude origins with lddate before this time.
-
-l logfile
Output file. The default format is: $year_$month_$day_$agency_IMS.
The year, month, and day are determined by the first event in the
subsetted database. The agency is determined from the parameter file.
-
-d database
This is the database which contains the dmcbull table. The dmcbull table
tracks the output files created by this program that have been sent to the
IRIS DMC. By choosing this option, the dfile field of the dmcbull table
is checked to make sure there are no duplicate output filenames. If there
are duplicates, the output file is renamed by appending an index (.1, .2, etc.).
See ims2dmc(1) or dmcbull(5) for additional information on the dmcbull table. This
optionally specified database can be the same or different from the database containing
arrival, assoc, origin, and event information.
for input
-
database
Name of input database. The arrival, assoc, origin, event, snetsta
and origerr tables are required. This is required and can be the same name or
different from the database specified with the -d option.
FILES
General format information
The format of the output file is a modification of the IMS1.0 short format. Documentation
of the format for the various blocks is available from pages 163-170 of the ISF/IMS1.0 document pages.
ISF/IMS1.0 documentation:
ftp://ftp.isc.ac.uk/pub/isf/isf.pdf
ISF extensions of IMS1.0 documentation:
ftp://ftp.isc.ac.uk/pub/isf/isf_ext.pdf
ISC's informal summary of IMS1.0:
http://www.isc.ac.uk/doc/code/isf/ims1_0.pdf
DMC specific information
Modifications by the DMC include:
(1) The IRIS/FDSN specific "Formatted Agency Comment" is defined as a Formatted
Comment (see below) with the following key/value pair: AGENCY="xx" describing
the agency submitting the Bulletin. For example:
(IRIS AGENCY="University of Washington")
(2) The "Phase Information Sub-block" is defined in the ISF extensions document
starting on page 16 (link to document below).
(3) The IRIS/FDSN specific "Phase Information Sub-block Formatted Comments" are
defined as Formatted Comments (see below) with the following key/value pairs:
FDSNNETWORKCODE="xx" :: FDSN Network code associated with the picked waveform.
FDSNLOCATIONID="xx" :: FDSN Location ID associated with the picked waveform.
FDSNQUALITYCODE="x" :: FDSN data quality code (D, R, Q, etc.)
The FDSN network code is required, the location id and quality code are assumed
to be unknown if not present.
For example:
(IRIS FDSNNETWORKCODE="II" FDSNLOCATIONID=" ")
or
(IRIS FDSNNETWORKCODE="IU" FDSNLOCATIONID="00" FDSNQUALITYCODE="R")
Formatted Comments:
IRIS specific Formatted Comments using the IMS1.0 comment syntax are formatted
beginning with an open, round bracket "(" at position 2 in the record/line,
followed "IRIS", followed by key and (quoted) value pairs and ending with a
closed, round bracket ")". A comment line should not be longer than 120
characters.
For data submitted to the DMC the station code (Phase Block), channel code
(Phase Information Sub-block), and Formatted Comment keys: FDSNNETWORKCODE,
FDSNLOCATIONID and FDSNQUALITYCODE should all follow the SEED/FDSN naming
nomenclature and uniquely identify the waveform associated with the phase
arrival.
For additional information on the DMC modifications see:
http://www.iris.edu/data/event/isf_format.htm
General information
The output file is divided into three sections (four if a magnitude block is
requested): 1) EVENT HEADER and DATA; 2) MAGNITUDE HEADER AND DATA; 3) PHASE
HEADER and DATA; and 4) PHASE SUB-BLOCK HEADER and DATA.
The first line of the file must be, "DATA_TYPE BULLETIN IMS1.0:short". It is followed
by EVENT HEADER information which describes the event number, and region where the
earthquake occurred. The EVENT DATA block contains the time, location, and depth of
the earthquake as well as error ellipse information. Note that in most circumstances,
no error ellipse information is available for origins that were collected from regional
network operators (i.e. you may only have this information for origins that were produced
with dblocsat or dbgenloc). Please see the /fImatch_origerr_auth/fP parameter in the PARAMETER
FILE section below. An indication of what the analysts chose as the preferred solution is
indicated with a comment of /fI#PRIME/fP.
The second section, optionally included when the -m option is selected, contains
magnitude information. After the header line, the data section contains the magnitude
type, network magnitude value, magnitude error, number of stations used to calculate
the network magnitude, the organization publishing the magnitude ane the origin ID. The
IMS format allows for the inclusion of a "min-max indicator" which would be displayed to
the immediate right of the magnitude value as either a "<" or ">". As the css3.0 schema
does not track this type of parameter, /fBdb2ims/fP hardcodes this to a blank. Only magnitudes
which match the /fImatch_mag_auth/fP and /fImatch_mag_type/fP from the parameter file and
have non-null values are reported.
The third section (second if -m is not selected) contains phase information. It lists
the station code, the distance
from the event, the station to event azimuth, the phase (as picked by the analyst),
arrival time, residual of the pick, azimuthal direction, and if available, the signal-to-noise
ratio, amplitude, and period. Magnitude information is filled in if the preferred origin, indicated
with a ("PRIME") comment in section 1 with the EVENT DATA, matches the /fImatch_mag_auth/fP parameter.
See PARAMETER FILE section below.
The final section contains additional phase information. It lists the SEED net code,
the channel code, phase (as picked by the analyst), the date, error in arrival time
as determined by the analyst, and author of the pick..
Each section also has either an event, origin, or arrival id. These ids should be
considered subject to change and should not be relied upon. ID references for
external bulletins may not be the same as those used by that institution.
PARAMETER FILE
The following is the default parameter file.
#
agency ANF
author_reject .*assoc.*|.*local.*|.*tele.*
match_origerr_auth ANF.* # origins with strike, sdobs, etc.
# normally QED and regional bulletins
# do not have these values filled in
ims_dir IMS # directory for storing output files
# parameters for subsetting reported magnitudes
# magnitudes reported in MAG BLOCK must match
accept_magtype &Arr{
ml
ML
Ml
}
mag_origin_auth ANF.*
mag_netmag_auth evproc
pf_revision_time 1243897200
-
agency
This is the short name for the reporting agency. The output file format requires
this to be 8 characters or less. Check with the DMC so that your agency is recognized.
-
author_reject
This is used to reject certain authors from the output file. The subset
that is performed is "auth!~/$author_reject/". Use this to remove automatic solutions,
or others that you do not want reported.
-
match_origerr_auth
Use this to select which authors from which to attempt to find origerr information. If this
is not used, the Smaj, Smin, Az, etc. may not be filled in properly (or with proper
blanks).
-
ims_dir
This is a directory where the output files are stored. Directory is created if
it does not already exist. This string is used in the 'dir' field of the
dmcbull table when ims2dmc is run.
-
accept_magtype
List of magnitude types to report in magnitude block if the -m option is chosen.
-
mag_origin_auth
List of origin.auth values to report in magnitude block if the -m option is chosen.
-
mag_netmag_auth
List of netmag.auth values to report in magnitude block if the -m option is chosen.
EXAMPLE
-
Create an IMS short file containing only reviewed events for the
month of January 2008. Check the dbops/anf.dmcbull table for any
duplicate file names.
% db2ims_new -s "1/1/2008" -e "2/1/2008" -y \
-d dbops/anf db/anf
-
Create an IMS short file containing only events reviewed
since 7/12/2007 and saved to an output file called MY_events.IMS.
% db2ims_new -t "7/12/2007" -l "MY_events.IMS" \
-y db/anf
DIAGNOSTICS
Any problems with or questions about the output format should be directed
to the DMC.
SEE ALSO
ims2dmc(1)
dmcbull(5)
mk_dmc_files(1)
BUGS AND CAVEATS
This has not been tested outside of the ANF. I suspect that there may
be some modifications needed for translation of other external bulletins.
Any updates to naming conventions or additional external bulletins will
have to be coordinated with the DMC: current contact is Chad
Trebant (chad@iris.washington.edu).
The eTime field in the phase sub-block is currently filled in with the
deltim value. This is probably a bad choice as deltim is an arbitrary value
chosen by the analyst and is filled in with a weighting factor by some
automatic location programs.
Earlier versions of this output format made no distinction as to what the
preferred origin was. As of late April 2008, the DMC has agreed that adding
a comment (#PRIME) after the preferred origin in the ORIGIN block is an
acceptable way to indicate the preferred origin. The preferred origin is
used to calculate values placed in the phase/arrival blocks, so having some
indication is rather important and was a significant drawback for earlier
files. I do not have a way to convert files generated without this indication
to the new format. You could go back to the css tables and attempt to figure
it out. However, re-running with the newer version of this script is
probably the best solution.
I have no control over the requirements of the output format. Any concerns
or questions should be directed elsewhere.
Magnitude values in the phase block are only reported when the preferred
author (#PRIME location) is the
mag_origin_auth.
Tracking what files are created and have been sent to the DMC is critical.
Make sure that you follow up IMS file creation with ims2dmc program in your
processing routines. You will then have a record of the files you create
stored in a dmcbull extension table. The ims2dmc program will also track
files transfered via orbxfer (-o option for ims2dmc) in a dmcfiles table.
AUTHOR
Jennifer Eakins
Univ. of California San Diego
Antelope User Group Contributed Software