Manuals: BREQ_FAST

NAME

BREQ_FAST – Batch REQuests, FAST

AVAILABILITY

breq_fast@iris.washington.edu

DESCRIPTION

Batch access to the IRIS DMC archive can be obtained by electronically mailing a specially formatted file to the IRIS DMC in Seattle. These are BREQ_FAST files and provide a base level access to the DMC needed by any user. These requests are not interactive in that you simply send the file to the DMC and the DMC will return either full SEED data or a dataless SEED file matching the request depending on where the e-mail was sent. For users that do not have access to electronic mail facilities, the IRIS DMC will process tapes containing images of BREQ_FAST files in simple ASCII format.

FILE FORMAT

The format of the file is as follows:
.NAME
.INST
.MAIL
.EMAIL
.PHONE
.FAX
.MEDIA:
.ALTERNATE MEDIA:
.ALTERNATE MEDIA:
.LABEL
.SOURCE		---
.HYPO		  | optional
.MAGNITUDE	---
.QUALITY
.END
 request line-1
 request line-2
 ...
 ...
 ...
 request line-n

BE SURE TO LEFT JUSTIFY EACH TOKEN LINE OR YOUR REQUEST COULD BE REJECTED!!!

The format of each request line is as follows:

STA NN YYYY MM DD HH MM SS.TTTT YYYY MM DD HH MM SS.TTTT #_CH CH1 CH2 CHn LI

where

STA  is the station
 NN   is the network code or "virtual network" 
 YYYY is the year - 2 digit entries will be rejected!
 MM   is the month
 DD   is the day
 HH   is the hour
 MM   is the minute
 SS.TTTT is the second and ten-thousandths of seconds
 #_CH is the number of channel designators in the immediately following list
 CHn  is a channel designator that can contain wildcards
 LI   is location identifier (optional)

All times should be in Coordinated Universal Time (UTC).

See the DMS Newsletter article Location Identifiers for more information about how these identifiers are used.

Individual lines in the request can not exceed 100 characters.

Valid selections for media at the present time, in the order of preference are:

  • Electronic (FTP)
  • EXABYTE – 2 gigabyte
  • EXABYTE – 5 gigabyte
  • DAT (digital audio tape)
  • DLT
  • DVD-R

(When requesting DVD-R media, there may be a delay in shipment of data)

Please be sure to specify your first, second and third choices for the output media.

The LABEL entry will be used to name the files containing your SEED volumes whenever they are small enough to transfer with ftp. Your SEED volumes will also include this LABEL internally so they can be distinguished regardless of filename. This capability can help you distinguish data you receive for different projects and aids communication with regard to a specific request.

HYPOCENTER OPTION

You must add the three token fields .SOURCE, .HYPO, and .MAGNITUDE to the standard BREQ_FAST file to request hypocenter data. The fields are defined as follows:

Cited Source Info

All referenced entries marked # n below refer to field numbers in blockette 32 of the SEED volume. See the SEED manual for details about blockette 32).

.SOURCE ~NEIC PDE~Jan 1990 PDE~National Earthquake Information Center-USGS DOI~
  |         |           |                            |
  |         |           |                            Publisher Name (# 6)
  |         |           Date Published/Cataloged (# 5)
  |         Name of Publication - Author (# 4)
Token name

Event Info

All referenced entries marked # n below refer to field numbers in blockette 71 of the SEED volume.

.HYPO ~1990 01 02 20 21 32.62~13.408~144.439~135.0~18~216~Mariana Islands~
  |               |             |      |      |     |  |        |
  |               |             |      |      |     |  |  Region Name (# 14)
  |               |             |      |      |     | Seismic Loc (# 13)
  |               |             |      |      |   Seismic region (# 12)
  |               |             |      |      Depth (# 7)
  |               |             |      Longitude  (# 6)
  |               |             Latitude (# 5)
  |               Origin Time (# 3)
  Token name

Magnitudes

.MAGNITUDE ~5.7~mb~
    |       |   |
    |       |   Magnitude Type (Blk 71 - field 10)
    |       Magnitude  (blk 71 - field 9)
    Token name

You can have as many MAGNITUDE entries as you need, just repeat the token. Also note, you can have optional source entries for each magnitude. If the cited source is different than the SOURCE line entered above, just add the references here, i.e:

.MAGNITUDE ~5.7~mb~Publication/Author~Date Published~Publisher Name~
    |       |   |           |             |                 |
    |       |   |           |             |                 Blk 32 - field 6
    |       |   |           |             Blk 32 - field 5
    |       |   |           Blk 32 - field 4
    |       |   Same as above
    |       Same as above
  Token name

Note: The ~ works as a field delimeter and must appear at the beginning of each line (after the token) and after each field as shown in the above examples.

QUALITY OPTION

Data can be of varying qualities. This field allows requesters to specify the quality of the data they want to receive. The default value is B (for best available). The values the Quality Field can assume are:

Quality Field Field Description
B Best Data (Q, if not Q then D, if not Q or D then R)
E Everything (Q & D & R)
Q Data tagged as QC’d
D Data of indeterminate quality
(Before June 2002 all miniSEED data was labeled D and as such some had been quality controlled and some had not.)
R Raw Data
(For example, data reaching the IRIS DMC via real-time telemetric methods does not have QC applied and is labeled R beginning with data in the year 2002.)

EXAMPLE

An example of a valid short BREQ_FAST file:

.NAME Joe Seismologist
.INST Podunk University
.MAIL 101 Fast Lane, Middletown, KS  89432
.EMAIL joe@podunk.edu
.PHONE 555 555-1212
.FAX   555 555-1213
.MEDIA DVD
.ALTERNATE MEDIA 1/2" tape - 6250
.ALTERNATE MEDIA EXABYTE
.LABEL Joe's FIRST Request
.SOURCE ~NEIC PDE~Jan 1990 PDE~National Earthquake Information Center - USGS DOI~
.HYPO ~1999 01 02 20 21 32.62~ 13.408~ 144.439~135.0~18~216~Mariana Islands~
.MAGNITUDE ~5.7~mb~
.QUALITY B
.END
GRFO IU 1999 01 02 00 18 10.4 1999 01 02 00 20 10.4  1 SHZ
ANTO IU 1999 01 02 02 10 36.6 1999 01 02 02 12 36.6  1 SH? 
AFI  IU 1999 01 02 02 10 37.1 1999 01 02 02 12 37.1  1 BH? 00 
SEE  CD 1999 01 02 14 45 08.9 1999 01 02 14 47 08.9  1 SHZ 
CASY IU 1999 01 04 02 42 13.4 1999 01 04 02 44 13.4  1 BHZ 10 
NNA  II 1999 01 04 02 41 57.5 1999 01 04 02 43 57.5  1 BHZ 
PFO  TS 1999 01 04 02 41 57.5 1999 01 04 02 43 57.5  1 BHZ 
PFO  II 1999 01 04 02 41 57.5 1999 01 04 02 43 57.5  1 BHZ 
KMI  CD 1999 01 04 02 41 57.5 1999 01 04 02 43 57.5  1 BHZ 
SSE  CD 1999 01 04 02 18 25.4 1999 01 04 02 20 25.4  2 B?? SHZ
PAS  TS 1999  1  4  2 10 49   1999  1  4  2 12 49    3 BH? SHZ L??

WILDCARDING

The Channel list in the batch file supports limited wild carding. It is similar to but not the equivalent of UNIX filename wild carding. Only the “?” wild card character is supported. It means match any single character. For instance “BH?” means match any Broad band High Gain Channel when entered into the Channel field. The Channel list can contain multiple entries such as

3 LHZ BH? S??
As an example a #_ch of 1 and a channel list of L?? (1 L??) would result in three characters in each of the channel names in the DMC archive being compared to L??. Since the ? means match any character it should be clear that L?? is the same as entering L. The channel names are matched for the same number of characters as the number in the input channel designator field. Also, if you are wanting to wildcard for more than one character you must use a ? for ALL character positions (ie. if you want all L channels you must type L??).

The DMC archive stores data for channels using the SEED channel naming convention documented in the SEED Reference Manual, appendix A.

Briefly, the channel names are three characters in length. The first character is the Band Code, the second the Source Code and the third the Orientation Code. Refer to the SEED reference manual for a more complete description of the SEED channel naming convention.

You can also wilcard for networks and stations. However, it is not suggested that you wildcard for network AND station at the same time or your request may be too big. A single ? is sufficient to wildcard for stations.

If you do not include a location identifier (not all stations use them), you will receive data for all locations that exsist at that station. (See the DMS Newsletter article Location Identifiers for more information about how these identifiers are used.)

One of the major benefits of the BREQ_FAST method is that you can specify time windows for various stations that have travel time corrections applied to the windows.

SUBMITTING YOUR REQUESTS

Once you have generated your BREQ_FAST file you can simply send it via email to either:

Address Returned
breq_fast@iris.washington.edu Full SEED
DATALESS@iris.washington.edu Dataless SEED
miniseed@iris.washington.edu miniSEED
sync@iris.washington.edu Sync file

When the IRIS DMC receives your request, programs will be run that will compare what you requested with what data are actually in the IRIS archive, recover the data from the mass storage system, generate the output SEED volume, and send it to you in the manner you requested. The only exception to this is that if you request electronic transfer and the file is too large, an alternate media will be used.

Notes

  • A dataless SEED volume contains the metadata for a request only, including instrument responses, instrument coordinates, compression type, etc., which can be used in combination with a miniSEED volume (as extracted from the BUD filesystem) with rdseed. A dataless, by definition, contains no “data”, in the sense that no waveform data are included, only headers.
  • Submitting breq_fast files via a Mac e-mail client: Under the Mac Mail preferences there is a Message Format under the Composing tab that should be in Plain Text rather than Rich Text.

SEE ALSO

  • SeismiQuery
  • NetDC
  • rdseed

DIAGNOSTICS

Your request will be echoed back via email. Another message is sent when your SEED format data is available for pickup via FTP.

BUGS AND LIMITATIONS

  • Not able to guess correct values for out of range data, such as minutes>59.
  • Each line expected to begin at the left margin.
  • Wildcarding convention for CHANNEL names is not UNIX standard.

See Also

Release date:     Modified date: