AutoDRM User Guide
AUTODRM USER GUIDE Last updated: 2009-04-07
AutoDRM is an automatic, electronic mail-based message handling system
developed and maintained by the Canadian National Data Centre for Earthquake
Seismology and Nuclear Explosion Monitoring (CNDC) for the exchange of
seismic and other geophysical data. It has been in continuous operation
since April 1994. AutoDRM uses a command language that represents an
amalgam of the command set and structure of the original Swiss autodrm and
the GSE2.0 and IMS1.0 command sets (see below). While every effort has been
made to allow the old commands to function fully, users are encouraged to
adopt the GSE/IMS command set since it is more powerful and flexible and is
an International Standard. More information on GSE/IMS formats and
protocols are available on our Website at:
http://earthquakescanada.nrcan.gc.ca
Anyone with e-mail access to the Internet can request information about the
Canadian National Seismograph Network (CNSN). You may choose to have the
complete autodrm response returned immediately by e-mail, or receive a short
message that the output file is available at the CNDC for retrieval via
anonymous ftp.
To obtain information, simply send an electronic request mail to the
Automatic Data Request Manager (autodrm@seismo.NRCan.gc.ca). To get
started with the latest version of this guide, you may send a message with
"HELP" or "PLEASE HELP" in the subject field, or bracketed by "begin" and
"stop" in the message body as follows:
BEGIN
PLEASE HELP
STOP
For general earthquake information, send e-mail to nrcan.earthquakeinfo-infoseisme.rncan@canada.ca.
For a list of recent Canadian seismicity, finger nrcan.earthquakeinfo-infoseisme.rncan@canada.ca.
Check out our Web page at URL http://www.seismo.NRCan.gc.ca/
The rest of this User's Guide discusses the following topics:
1) Message Format and Rules of Use
2) Naming of seismic (and related) data channels.
3) Description of Commands Understood by the CNDC AutoDRM
4) Examples
5) CNSN Data Citation Policy
6) Calibration Change in SEED Waveform Files
7) Time Corrections in Waveform Files
8) Generation of pseudo-Long Period data
==================================
1) Message Format and Rules of Use
==================================
- Commands may be entered in either upper or lower case, left justified,
starting in column 1. Typically only the minimum number of characters
to uniquely characterize the keyword (>= 3) are required, but all
examples shown follow the international autodrm convention.
- Required and optional arguments may follow the command in free format,
separated by one or more blank spaces or tabs.
- All request messages must start with the BEGIN command, end with the
STOP command, and should include an EMAIL or FTP command specifying a
return address. The only exception is the one-line HELP request.
Blank lines and comment lines beginning with `#' are ignored.
- As of V5.0, multiple requests in the same mail message (i.e., multiple
BEGIN/STOP sequences) are no longer supported.
- If no return e-mail address is given (via EMAIL or FTP), autodrm will
attempt to reply to the mailer-supplied return address. However, this
is notoriously unreliable, especially across different mail systems,
and return messages frequently never reach the requestor.
- Since autodrm commands are executed sequentially as they are encountered,
it is important to set the "context" before initiating an action. For
example, you must specify a date-time range *BEFORE* issuing the
WAVEFORM command. For the EMAIL and FTP commands, while it is not
illegal to put them after a command that elicits a response, they will
have no effect (until possibly later commands are executed). This may
mean your responses go astray (see preceding point).
- Commands specifying a range of values may use either " - " or " TO "
interchangeably as the range separator. DEPTH and MAGNITUDE can also be
used with a single range value, provided the separator is present (see
example 4)
- As of December 2004, all waveform data is retrieved very rapidly from
a magnetic disk-based online archive. To see the oldest available data,
use the AVAIL command. Requests exceeding the limit of on-line access
may return only partial data. The START_TIME (DATE1) must be earlier
than the END_TIME (DATE2).
- There is currently a limit of 1000 solutions that may be retrieved from
the database using the Bulletin and Event commands. This is a
precaution used to prevent nuisance or improperly-formed requests from
spewing reams of useless information and negatively impacting the
performance of our database system. Legitimate users requiring more
output are encouraged to contact us directly so we can screen their
requests and provide guiding advice. Send an e-mail to
nrcan.earthquakeinfo-infoseisme.rncan@canada.ca.
- The response message is copied to our anonymous ftp directory for
retrieval whenever requested via the FTP command, the output file size
exceeds 1MB, or SEED or CA format (binary) waveforms are requested. An
e-mail notification is sent noting the ftp address, location, and
filename.
- To retrieve waveform files via ftp:
- ftp to ftp.seismo.NRCan.gc.ca
- login as user "ftp" or "anonymous" and supply your e-mail address when
prompted for a password
- cd to pub/autodrm
- type "get <filename>" to retrieve the waveform file to your current
working directory
- type "quit" to exit ftp
================================================
2) Naming of seismic (and related) data channels
================================================
The unique naming of seismic (and related) data channels from Canadian
stations follows an extension of the FDSN channel-naming conventions. A
full channel name comprises three fields: a network code of up to 12
characters (eg., CNSN, POLARIS); a site code of up to 5 characters, and
a 3-character channel (band-gain-orientation) code, each separated by a
dot (`.'). These are defined separately by the NET_LIST, STA_LIST, and
CHAN_LIST commands respectively.
If network list is not specified, the list defaults as before to all open
networks/deployments (currently CNSN, POLARIS, FEDNOR and CHASME).
=========================================================
3) Description of Commands Understood by the CNDC AutoDRM
=========================================================
Commands are followed by a number in parentheses (n) interpreted as
follows:
1 - original (Swiss) autodrm command set
2 - GSE2.0 (1995) command set
3 - local extensions not necessarily recognized by other autodrm's
4 - new or changed commmands for IMS1.0
Command Argument(s) Meaning
------- ----------- -------
AIDE Send the French Language version of this
Users Guide as a separate e-mail.
ARRIVAL(2) GSE2.0 Requests a list of phase arrival data
associated with origins (epicentre
solutions) qualified by the specified time
range and station and channel lists.
AVAIL(3) Requests the time of the earliest waveform
data available on-line. Note: this time
changes every half hour as new data is added
and old data dropped from the on-line disk
area.
BEGIN(1/2) GSE2.0 Required to denote the start of a new
request and initiate command processing.
The GSE2.x argument here forces the
interpretation of certain commands and the
output format to use the GSE2.x standard.
BULLETIN(2) GSE2.0 Requests generation of a list containing
ORIGIN (epicentre solution) and phase
ARRIVAL data matching the specified time,
latitude, longitude, depth, and magnitude
ranges.
CHANNEL(2/4) GSE2.0/IMS1.0 Requests a list of channel-related
information (sensor type, emplacement, etc.)
for the specified STA_LIST, CHAN_LIST and
latitude and longitude ranges. Replaces
SLIST(1).
CHAN_LIST(2) channels CNSN channel names comprise a 3-character
channel (band-gain-orientation) code,
following the FDSN channel naming
conventions. Lower case is allowed.
CHAN_LIST replaces the `chan' portion of
the stn-chan list on the old WAVEF
command. Stations are specified separately
using STA_LIST. Default for GSE2.0 is all
vertical components (*Z). See WAVEFORM for
examples.
DATE1(1/3) yyyymmddhhmmss Define date-time of the start of a time
START_TIME(3) interval: (yyyy: year, mm: month, dd: day,
hh: hour, mm: minute, ss: second. Note
that the time portion need only be
specified to the precision desired; the
date portion is required. As a local
extension, punctuation may be used to
separate the time fields for readability.
See also TIME(2) command. Unlike TIME, no
spaces are allowed in the time string.
DATE2(1/3) yyyymmddhhmmss Define date-time of the end of a time
END_TIME(3) interval. Format and caveats same as for
DATE1 above.
DEPTH(2) dep1 - dep2 Sets search range for depth in kilometers
(positive downwards), from shallow to
deep. Defaults to all.
DEPTH_MINUS_ERROR(2) Selects events that have a 90% probability
dep1 - dep2 of being within the depth range specified
(in kilometers, positive downwards).
Defaults to range -999 TO 9999 (all).
DETECTION(2) GSE2.0 Requests generation of a list of
detections. At present, only Yellowknife
Array data are available in GSE2.0 format.
CNSN Requests a list of preliminary detections
from the automatic CNSN event detector. A
time range <= 24 hours and younger than 1
year is required. A station list must be
supplied.
DURATION(3) seconds As an alternative to DATE2, DURATION
specifies an interval of time. It must be
used with DATE1 to fully specify a date-time
range.
EMAIL(1) e-mail_adr Specify preference for e-mail data
E-MAIL(2) transmission and supply a return e-mail
address. Messages longer than 1 Megabyte
will be sent via ftp with a brief e-mail
notice. Must appear before the NET_LIST
command.
END_TIME(3) See DATE2.
EVENT(2) GSE2.0 Requests generation of a list containing
the single preferred ORIGIN (epicentre
solution) data matching the specified time,
latitude, longitude, depth, and magnitude
ranges.
EVENT_STA_DIST dist1 - dist2 Restricts search range for bulletin-type
requests and/or waveform data associated
with specific events to event-station
distances in degrees that lie within the
specified range. Defaults to range 0 - 180
(all).
FORMAT(3) SEED Local command used to specify format for
output waveforms. If SEED format is
requested, a SEED V2.3 format (binary) file
is created and the ftp option is forced.
NOTE: If you use IRIS's RDSEED program to
remove instrument response from CNSN data in
SAC, only RDSEED versions <= 4.12 or >= 4.6
do this correctly.
CSS Return waveforms in CSS format. The
site, w, and wfdisc files are combined into
a single Zip archive for easy download and
the ftp return option is forced.
GSE2.0 Return waveforms in GSE V2.0 format.
Currently only CM6 compressed ASCII format
is supported (see CODECO program returned
by SOURC for decompression routine in
FORTRAN).
IMS1.0 Return waveforms in IMS V1.0 format, with
extra STA2 and OUT2 records as required.
Currently only CM6 compressed ASCII format
is supported (see CODECO program returned
by SOURC for decompression routine in
FORTRAN).
CA Return waveforms in "Canadian Archive" (CA)
format, a compressed binary format
developed by the GSC originally for the
CNSN, and now used more widely as a common
archive format. Contact us for
decompression routines in C.
INT Return waveforms as ASCII integers. Each
channel is saved as a separate ASCII file
comprising a short header containing the
channel name in the format
station.component (i.e. WALA.BHZ), the
start time of the earliest data in the
file, the sample rate and the number of
samples, followed by the integer sample
values, one value per line. All files are
combined into a single Zip archive for easy
download and the ftp option is forced.
FTP(2) e-mail_adr Specify data return via ftp and supply
e-mail address for a brief notice.
Requested data will be stored at
ftp.seismo.NRCan.gc.ca, for access via
anonymous ftp. No EMAIL command is
required.
To avoid disk space problems, users are
strongly advised to delete waveform files
using the remote file DELETE command in ftp
once they have retrieved them. Note that
files in the ftp directory are cleaned up
automatically after a period of time
(currently three days).
FTP_PATH(3) path Used with INTER (below), specifies the path
for anonymous ftp to write the response on the
user's ftp directory (e.g. /imports/user).
HELP(1/2) Send this Users Guide as a separate e-mail.
GUIDE(1) Same as command HELP.
PLEASE HELP(1) Same as command HELP.
INTER(1) IP_number Requests the automatic "push" of the response
by anonymous FTP to the internet-address
given by 'IP_number'. This address should be
specified in numerical form as in the
/etc/hosts file on UNIX-machines, ( e.g.
INTER 129.132.53.4 ). Can be used with
the FTP_PATH and OUT_FILE commands to specify
an output path and filename. Note: proper
permissions must be granted for anonymous
ftp to write to this path.
LAT(2) lat1 - lat2 Sets search range for latitude in degrees,
from lower (south) to higher (north).
Southern latitudes are negative. Defaults
to all.
LONG(2) long1 - long2 Sets search range for longitude in degrees,
from west to east. Western longitudes are
negative. Defaults to all.
MAG(2) mag1 - mag2 Sets magnitude search range, from lower to
higher. Defaults to all.
MAG_TYPE(2) MN, MS, ML... Specifies a list of magnitude types to
qualify a search with the magnitude
environment. Currently the CNDC calculates
MN, MC, MS, ML and mb, but stores magnitude
types from other agencies as well.
Defaults to all.
MSG_ID(2) unique_id Up to 20 char ID used as a convenience for
the sender in tracking messages. Value is
returned in the response message in a
"REF_ID" line. Structured replacement of
TITLE/SUBJEct(1). Third line of a GSE2.x
request message.
source Optional 2nd parameter for source ID up to
eight characters. For GSE2.x, National
Data Centres conventionally use a 3-char
country code followed by "_NDC". Our
responses will contain source "CAN_NDC".
MSG_TYPE(2) request/data Used as the second line of a GSE2.x request
message to specify and distinguish REQUESTs
(what users send to an autodrm) from the
DATA autodrm provides. Necessary for fully
automated systems, where both requests and
responses are machine-generated and
interpreted.
NET_LIST(3) network(s) New for V5, this command allows fine-tuning
requests beyond the default list of open
networks/deployments: CNSN, POLARIS,
FEDNOR and CHASME. Must appear before the
STA_LIST command.
NONOTIFY(3) Used with the INTER command for anonymous
FTP "push", indicates that no informative
e-mail reply is desired. Note: this should
be used only after careful testing to ensure
proper results.
ORIGIN(2) GSE2.0 Request generation of a list containing
Origin (epicentre solution) data matching
the specified time, latitude, longitude,
depth, and magnitude ranges. There may
give more than one solution for the same
event.
OUTAGE(2/4) GSE2.0/IMS1.0 Request a list of data outage by stn_chan.
Short-term (<60s) outages are reported
statistically, and longer-term outages are
reported individually.
OUT_FILE(3) filename Local command to specify a unique filename
for the user's response data for FTP pull
or push. If no filename is given, autodrm
will choose one based on date-time of the
request. Note that files in the CNDC ftp
directory are cleaned up automatically
after a few days.
RESPONSE(2) GSE2.0 Requests response information in the form
of tables of system sensitivity, poles and
zeros and FIR filter coefficients that can
be cascaded to derive the complete response
of the instrument.
Complete response information is also
contained in the station control record
portion of SEED format waveform files.
The CNDC also maintains in the anonymous
ftp directory (ftp/exports) a FORTRAN
subroutine called cnsn_response.f, that can
be used to generate response values for all
CNSN stations.
SLIST(1) Request a list of station-related
information (site, location, dates of
operation, etc.) for the specified STA_LIST
and latitude and longitude ranges.
Replaced by and now synonymous with
STATION(2).
SOURC(1) Request FORTRAN source code of the CODECO
program, that decompresses the GSE formats,
in a separate e-mail.
STATION(2/4) GSE2.0/IMS1.0 Requests a list of station-related
information (site, location, dates of
operation, etc.) for the specified STA_LIST
and latitude and longitude ranges.
Replaces SLIST(1). The GSE2.1 format
includes network code.
STA_FILE(3) filename Specifies a file containing a list of
stations to be used in place of repetitive
and/or lengthy STA_LIST commands. Frequent
users may arrange with CNDC staff to set
up this file.
STA_LIST(2) stations CNSN station codes comprise a site name of
up to 5 characters registered with the NEIC
and the ISC. Lower case is allowed.
STA_LIST replaces the `stn' portion of
stn-chan list of the old WAVEF command.
For GSE2.x, channels must be specified
separately using CHAN_LIST. A list of up
to 40 stations may be supplied, separated
by spaces and /or commas. Present default
for GSE2.x is all stations (*). See
WAVEFORM for examples.
START_TIME(3) See DATE1.
STOP(2) Required to denote the end of the current
END(3) message and the generation of output.
SUBJE(1) your_subject The response mail returned to you will have
TITLE(1) the subject you specify here; if not
specified, a default reference ID will be
supplied.
TIME(2) time1 - time2 Specifies a date-time range. GSE2.x time
format comprises separate date and time
fields, separated by one or more blanks,
with values of the form "yyyy/mm/dd
hh:mm:ss.sss". Leading zeros in all
numeric fields are required.
Replaces DATE1/DATE2. As with DATEx, only
the date portion is required; the time
portion need only be specified to the
precision desired. Defaults to 1970/1/1
00:00:0.000
TIME_STAMP(4) Requests that data messages be time
stamped. Time stamps will appear at the
beginning and end of each data type,
recording the UT time (to the second) that
processing took place.
WAVEFORM(2/4) format Request all waveforms for the station-
channels previously specified with
STA_LIST and CHAN_LIST commands and
specified time range in the specified
format (see FORMAT command above for
options).
WAVEF(1) As of AutodDRM V5 the stn-chan option is
no longer supported. Use STA_LIST and
CHAN_LIST.
The CNDC AutoDRM command set may be modified from time to time. It is
recommended that you re-request this Guide periodically or in case of
problems in order to keep up to date with the latest developments.
===========
4) Examples
===========
1. Request a complete list of current CNSN stations in IMS1.0 format:
BEGIN
EMAIL yourname@abc.efg.hi
NET_LIST CNSN
STATION IMS1.0
CHANNEL IMS1.0
STOP
2. Request a list of all high broad-band channels in the POLARIS
network.
BEGIN
EMAIL yourname@abc.efg.hi
NET_LIST POLARIS
CHAN_LIST HH*
CHANNEL IMS1.0
STOP
3. Request 2 minutes of waveform data for all 3 components of
stations INK, WALA, and RES in the default GSE compressed format, by
return e-mail:
a) original command set (will return V1: GSE)
BEGIN
EMAIL yourname@abc.efg.hi
TITLE test.eg2a
DATE1 200111090000
DATE2 200111090002
WAVEF INK WALA RES
STOP
b) GSE2.0 command set (will return V2: GSE2)
BEGIN GSE2.0
EMAIL yourname@abc.efg.hi
MSG_TYPE REQUEST
MSG_ID test.eg2b
TIME 2001/11/9 00:00 TO 2001/11/9 00:02
STA_LIST INK WALA RES
CHAN_LIST *
WAVEFORM
STOP
4. Request 10 minutes of vertical-component waveform data for station WALA
in SEED format (NB: SEED data is always placed in the anonymous ftp
directory as separate files, with a mail notification):
a) Simplest and most straight-forward, using local DURation and FORMAT
commands
BEGIN
EMAIL yourname@abc.efg.hi
DATE1 20011030.0000
DUR 600
FORMAT SEED
STA_LIST WALA
CHAN_LIST *Z
WAVEFORM
STOP
b) Using strict GSE2.0 command set (NB: CHAN_LIST not required since
vertical-only channel is GSE2.0 default)
BEGIN
EMAIL yourname@abc.efg.hi
TITLE test.eg3a
DATE1 2001/10/30_0000
DATE2 2001-10-30:00:10
FORMAT SEED
WAVEF WALA.*Z
STOP
c) Using strict GSE2.0 command set (NB: CHAN_LIST not required since
vertical-only channel is GSE2.0 default)
BEGIN GSE2.0
E-MAIL yourname@abc.efg.hi
MSG_TYPE REQUEST
MSG_ID test.eg3b
TIME 2001/10/30 00:00 TO 2001/10/30 00:10
STA_LIST WALA
CHAN_LIST *Z
WAVEFORM SEED
STOP
5. Search the National Earthquake Database and return a list of origins
and associated phase arrivals for all events occurring in the northern
hemisphere between June 1, 1993 and August 31, 1994 having magnitude 5
and greater, and a focal depth less than or equal to 20 km, for which
MN and ML magnitudes were calculated, in GSE2.0 format:
BEGIN
EMAIL yourname@abc.efg.hi
MSG_ID test.eg4
TIME 1993/06 - 1994/09
LAT 0 - 90
MAG 5 -
DEPTH - 20
MAG_TYPE MN ML
BULLETIN GSE2.0
STOP
Notes:
1) You must substitute your own e-mail address for "yourname@abc.efg.hi".
============================
5) CNSN Data Citation Policy
============================
AutoDRM makes data from the GSC's Canadian National Seismograph Network
(CNSN) and CHASME experiment, plus data from other cooperating networks
(POLARIS) available FREE to anyone on the Internet. In order for us to
maintain this service, we need to enlist the support of our users. Please
include a citation to "The Geological Survey of Canada" in your work. It
would be helpful if you would send a citable reference for any publications
that use CNSN data to John Cassidy (cassidy@pgc.NRCan.gc.ca), who is
maintaining a database of CNSN data usage. Alternatively, you could send
a paper or electronic reprint to him:
Dr. John Cassidy
Pacific Geoscience Centre
P.O. Box 6000,
9860 West Saanich Road,
Sidney, B.C.
V8L 4B2
============================================
6) Calibration Change in SEED Waveform Files
============================================
On Monday October 3, 1994 at 17:45, the CNSN Data Acquisition software was
modified to remove a scaling factor (transmission gain) of either 2**5 = 32
(most sites) or 2**8 = 256 (BBB, PGC, PNT). Yellowknife Array sites (YK*)
are not affected. This has the effect of dividing each sample value by a
factor of 32 or 256. Correct response information is written into the SEED
file headers.
=====================================
7) Time Corrections in Waveform Files
=====================================
SEED format waveform files created since Sep 12/94 have time correction
information incorporated into the Data Header records. Note - these are
*logged* but not applied.
GSE format files, which have no time correction field, have had these time
corrections *applied*. As a consequence, the data start time for some
stations may be shifted a number of seconds. (NOTE: stations whose timing
is uncertain are flagged with a correction of 999.9 seconds!)
The CNDC maintains an historical record of time corrections in a file in
our ftp/exports directory called cnsn_clock_history_DATE (where the DATE
reflects last update).
========================================
8) Generation of pseudo-Long Period data
========================================
While we do not directly record 1 Hz long-period data, we do have the
capability to generate pseudo-channels of long-period data by filtering
and decimating the 40 Hz BH* and 100 Hz HH* data streams.
To obtain LP data, specify channel names of "LH*".
###########################################################################
