NAME
deployment2vnd - produce virutal network definition file (VND) from deployment table
SYNOPSIS
deployment2vnd [-v] [-t] [-h] [-s subset_expression] database file
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
deployment2vnd takes information from an input deployment database
table and produces a comma separated virtual network definition file (VND)
for use at the DMC. The deployment table is an extension of the css3.0
schema and is generally filled in using the
dbe editor. A full
description of the deployment table can be found by using
dbhelp on
a css3.0 database, or by reviewing the
Description of a Deployment
Table section below.
Note, the deployment table has more information than a VND file.
Translating multiple times between a deployment table to a VND and back
to a deployment table will not give you the same information.
If you wish to track the VND files that your data center generates,
consider using the mk_dmc_files(1) script which will track the
files generated in a dmcfiles table.
Description of a VND
From the DMC 2006 December Electronic Newsletter:
"A virtual network is group of stations and/or seismic networks,
representing an affiliation that goes beyond the traditional bounds of
seismic networks to represent an umbrella organization or initiative.
Virtual networks associate to recording stations and seismic networks
either indefinitely or for some limited period of time. It is a grouping
system that reflects growing partnerships between seismic institutions
to undertake large projects and act as a single, newly formed entity.
The virtual network naming system allows these traditional networks to
have their data represented under the auspices of one or more of these
initiatives."
The fields in the comma separated version of the file are:
VIRTUAL NET,NETWORK,STATION,INSTALL DATE,CERT DATE,
START DATE,START TIME, END DATE,END TIME,PRIMARY DC,
SECONDARY DC
They are defined as follows:
-
VIRTUAL NET
The current standard is that a virtual network always starts with a leading
underscore "_". Some examples include _US-TA, _US-FA, _US-All, _ANSS, etc.
See http://www.iris.edu/vnets
-
NETWORK
The two character network code. For instance, TA, CI, US, etc.
-
STATION
The three to five character station code.
-
INSTALL DATE
The date the equipment was first installed (note that no time is included).
This is not changed even if all equipment is replaced (i.e. a sensor or
datalogger have been swapped).
-
CERT DATE
The date the data center responsible for data collection verifies that
metadata is available and starts passing it along to secondary data
centers. This field seems open to interpretation...
-
START DATE
The date of the first data available from the given station. Note this
date should not be earlier than the INSTALL DATE, but could be earlier
than the CERT DATE.
-
START TIME
The time of the first data available from the given station.
-
END DATE
The date of the last data available from the given station.
-
END TIME
The time of the last data available from the given station.
-
PRIMARY DC
Name of data center where the majority of endusers get the data. This
field has been open to interpretation. The DMC might have strict requirements
on what can go in here.
-
SECONDARY DC
Name of alternate data center where endusers can get the data. This
field has been open to interpretation. The DMC might have strict requirements
on what can go in here.
Description of a Deployment Table
In an effort to keep track of all information necessary to produce a VND,
an extension table to the css3.0 schema was created (see
dbschema(5)
and
dbhelp(1)). The fields in a deployment table are:
-
net 1.25
In this case, this is the network code that starts with an "_".
-
snet 1.25
The two character SEED network code. For instance, TA, CI, US, etc.
-
station
The three to five character station code.
-
time 1.25
Time of the first data available from the given station that has been
made available for import from external users. Note this
date should not be earlier than the equip_install, but could be earlier
than the cert_time.
-
endtime
Time of last data available to external users from the given station.
-
equip_remove
Time the equipment was removed from the site.
-
cert_time
Time that metadata was made available and/or time that data started
flowing to external users. This field is open to interpretation.
-
decert_time
Time that station was removed from external data import. This could
be the same or later than endtime and could be the same or later than
equip_remove.
-
pdcc 1.25
Primary data center.
-
sdcc 1.25
Secondary data center.
-
lddate
Last update time of the record.
OPTIONS
-
-v
Verbose.
-
-t
Use tabs instead of commas to separate fields in output file.
-
-h
Print headers in the output file.
-
-s subset_expression
Deployment table subset. The subset applied to the deployment table will be
subset_expression. Suggestions might be "vnet=~/_US-TA/" or "snet=~/TA/".
FILES
See Description of a VND for the format of a Virtual Network Definition
file. These format of these files is based on an Excel spreadsheet, and
as such, I expect it to change at some point.
As a "best practice", the network operations specific schema extension
tables might be kept in a directory such as "dbops". Tables such as
site, sitechan, network, calibration, stage, etc. normally end up in a
directory called "dbmaster" in a real-time operations setting. Waveforms,
the wfdisc, arrival, origin, and other event database tables are normally
found in the "db" directory. Maintaining a separate "dbops" directory
allows a data center to segregate these tables that may be essential for
their operations, but not for a generic real-time system.
Consider using the mk_dmc_files(1) program that calls deployment2vnd(1)
and tracks the generated output files in a dmcfiles extension table.
EXAMPLE
Using the deployment table found in the input database, db/usarray, create
a vitual network definition file in the vnd output directory.
% deployment2vnd db/usarray vnd/_US-TA_20070929.csv
Using the deployment table found in the input database, db/usarray, create
a vitual network definition file for all _US-TA records with descriptive
headers.
% deployment2vnd -h -s "vnet=~/_US-TA/" db/usarray vnd/_US-TA.csv
SEE ALSO
vnd2deployment(1)
convert_deployment(1)
dbe(1)
dbhelp(1)
mk_dmc_files(1)
mk_dbops(1)
http://www.iris.edu/vnets
BUGS AND CAVEATS
Prior to February 2009, the deployment table used
net rather than
vnet. The current version of
deployment2vnd uses the newer
schema extension definition with vnet. To convert your older
format deployment table to the newer format, use
convert_deployment
Works with current definition of VND file. The format is not
well documented and subject to change.
The DMC does not seem to care much about specific time: the VND
only has resolution to the date level. I suspect that may change
at some point. However, the deployment table has a full time description
so this script could be modified to output time as needed.
There are no current
dbverify checks to make sure that the
deployment table fields are consistent internally, or to check if
the deployment table fields match what is available in the site, sitechan,
snetsta, etc.
The DMC requires null times of 12/31/2599 23:59:59.0. This is not a
standard css3.0 null time so this script will convert css3.0 nulls to
the time requested by the DMC.
AUTHOR
Jennifer Eakins
IGPP-SIO-UCSD
Antelope User Group Contributed Software