SHAPE (SEED Header Assembly
and Preparation Engine)
A Dataless SEED Building Tool
SHAPE is a tool for easily building Dataless SEED volumes. What
differentiates SHAPE from other Dataless SEED building tools, is that
the input to SHAPE is also the normal human readable representation of
the Dataless volumes themselves. In other words, the input and the
output are (essentially) the same format, making it easy to correct
mistakes in the final product with a simple text editor.
The inputs to SHAPE are response text files in RESP format, where RESP
format is the format used by the IRIS programs for response evaluation
(evalresp, jevalresp, and jplotresp), and are typically generated from
SEED volumes via the IRIS rdseed program. So if a user wants to correct
a field in a dataless volumes (say location of a single station), one
only needs to convert the dataless into RESP files using rdseed, edit
the location in a text editor, and recreate the dataless from the
modified RESP files using SHAPE.
Purpose
The purpose of SHAPE is to provide a user friendly/human readable
method
for people to build Dataless SEED volumes from RESP files, the
traditional
response information text output format of Dataless SEED volumes.
In a dataless SEED volume, one stores station response information.
Multiple
stations may be defined in a dataless volume. For each station, several
channels
may be defined. For each Channel, multiple time periods may be defined.
It
is the goal of SHAPE to allow a user to build a single Dataless SEED
volume
from a number of RESP files. Each RESP file traditionally defines 1 to
N
time periods of a single channel for a single station.
A single master command file (HAT - Header Assemble Template) defines
how
SHAPE builds a single Dataless volume from many RESP files.
A dataless SEED volume holds more information than exists in a RESP
file,
so the RESP input files to SHAPE must be augmented with additional
information.
(required information is listed below). There are 2 ways to augment
this
RESP info. The user may either add this missing information to the RESP
files,
or the user may insert this missing information direction into the HAT
file.
Using either method the user may arbitrarily add or modify any field in
the
Response Blockettes (See the SEED reference manual (v 2.3) for
definitions
of the Station/Channel/Response blockettes
(http://www.iris.washington.edu/manuals/acrobat/T_SEED.pdf))
RESP file modifications versus HAT
file usage.
Adding information to RESP files is easiest, as new fields follow the
same formatting paradigm as the rest of the RESP file, but to change a
location for a single station, one must hand edit each RESP file (one
for each channel) for that station. Adding information to a HAT file
requires more understanding of SHAPE, but allows the user to specify
new defaults for certain fields. i.e. it is easy in a HAT file to
change the location information for an entire station in a single place.
RESP files
While we discuss RESP files often in this document, the reality is that
SHAPE
can work with either complete RESP files, or with small out takes
(SNIPPETS)
of RESP files. The allowable content of a Snippet is identical to the
allowable
content of a RESP file. The only difference is how SHAPE works with
Snippets
and RESP files. SHAPE assumes that SNIPPETs are meant to be
assembled
and manipulated. SHAPE assumes that RESP files are complete unto
themselves.
SHAPE will allow for overriding values within a RESP file by the HAT
file
values, but in general specifying a RESP file in a HAT file is simpler
than many Snippet. There are fewer items that need to be
checked/correlated.
The HAT File
The Header Assembly Template file (HAT) is used to glue together
snippets
of RESP files.
Sections within the HAT file.
As the HAT file is XML based, the overall content is defined within the
following
root element
<SHAPEFILE>
</SHAPEFILE>
Station
The Child elements of a "SHAPEFILE" are the individual station
definitions.
The stations are defines by the "Station" element.
<SHAPEFILE>
<station name="DAV">
</station>
</SHAPEFILE>
note - the "name" attributes
are
ignored by SHAPE, they are included here to make the examples clearer.
Only
elements are important in the HAT file.
Channels
<SHAPEFILE>
<station name="DAV">
<channel name="dav_BHZ">
</channel>
<channel name="dav_BHN">
</channel>
<channel name="dav_BHE">
</channel>
</station>
</SHAPEFILE>
Specifying Snippet information within
a
HAT file
We use RESP files or Snippets of RESP files to properly
initialize
the Blockettes that will ultimately be places within a Dataless SEED
volume.
The RESP/Snippet information is placed within the Channel Elements.
Blockette
50 information found within a Snippet/RESP file will be used to augment
the
Station information. (time spans, etc.)
Using a complete RESP file in the HAT
file.
- This will create a Dataless SEED volume containing only the
station/channel
held in the file mytest.RESP. Because Attributes are not used by SHAPE,
the
names "DAV" and "dav_BHZ" are ignored at run time. They are here to
help
user only. The values for Station
and Channel
in mytest.RESP are the values that will really be used in the final
Dataless
SEED volume.
<SHAPEFILE>
<station name="DAV">
<channel name="dav_BHZ">
<respfile>mytest.RESP</respfile>
</channel>
</station>
</SHAPEFILE>
Time Window filtering.
If we want to filter out unwanted time windows from within
RESP
file, we can specify our time region of interest within the HAT file.
All
blockettes that do not correspond to times within our region of
interest
will be ignored.
<SHAPEFILE>
<station name="DAV">
<channel name="dav_BHZ">
<respfile>mytest.RESP</respfile>
<starttimefilter>1990,001</starttimefilter>
<endtimefilter>2001,011</endtimefilter>
</channel>
</station>
</SHAPEFILE>
Overriding a value in the RESP file.
If the user wishes to override a value in the RESP file, this
may
be done directly in the RESP file, or in the HAT file. The way to do
this
in a HAT file is via the "init" element which holds 2 elements, one
defining
which Blockette/Field to override, and the other defining its new
value.
If a value is changed in the RESP file and via an INIT element, the
init
element will override the RESP element. Also, if the same field is
modified
in 2 INIT elements, the second will override the first.
This will override all the Blockette 52, field 17 values in the RESP
file
with the new value of 8.
<channel name="dav_BHZ">
<respfile>mytest.RESP</respfile>
<init>
<field>B52F17</field>
<val> 8 </val>
</init>
</channel>
As Attributes are ignored, this has the exact same effect within SHAPE,
but
is easier to read.
<channel name="dav_BHZ">
<respfile>mytest.RESP</respfile>
<init name = "Data Record Length">
<field>B52F17</field>
<val> 8 </val>
</init>
</channel>
This is useful for reusing a single RESP file for multiple channels.
<station>
<channel name="dav_BHZ">
<respfile>mytest.RESP</respfile>
<init>
<field>B52F4</field>
<val> BHZ</val>
</init>
<init
name="azimuth">
<field>B52F14</field>
<val> 0.0 </val>
</init>
<init
name="dip">
<field>B52F15</field>
<val> -90.0</val>
</init>
</channel>
<channel name="dav_BHN">
<respfile>mytest.RESP</respfile>
<init>
<field>B52F4</field>
<val> BHN</val>
</init>
<init
name
="azimuth">
<field>B52F14</field>
<val> 0.0 </val>
</init>
<init
name="dip">
<field>B52F15</field>
<val> 0.0</val>
</init>
</channel>
</station>
Correlating INIT elements against
multiple
items in a RESP file.
In the above example, if there are multiple Blockette 52s in the
RESP
file (i.e. multiple times) that INIT element that specifies. B52F4 will
override
all blockette B52, field 4's that we find in the resp file. If one
wants
to limit the application of an Init element, or glue parts of RESP
files
together, then the snippet elements
must be used instead.
Snippets
Snippets are pieces of RESP files that are assembled into a single
Station/Channel/Response
chain. A snippet can be a complete response file. The assumption of
Snippet
handling is that a single snippet may be cut up and glued back together
again.
A snippet file has a number of elements, which are separate stages. A
stage is the smallest element from a snippet file that may be used by
SHAPE.
Each <stage> of a snippet has it's own snipfile definition and
starting
and final stage number. If no end stage is specified, than all stages
from
the starting stage to the last stage (stage 0 in most cases) are used.
If
no starting stage is specified, than all stages in the snippet file are
used.
The following example uses stages 1-4 from the first snip file, and
stage
0 (summary) from the second snip file.
<channel name="dav_BHN">
<snipfile>BHN.snip</snipfile>
<!-- this snip file is used for the B50 and B52
information
only, even if more blockettes are contained in this snip file -->
<stage>
<first>1</first>
<last>6</last>
<snipfile>num1.snip</snipfile>
</stage>
<stage>
<first>0</first>
<last>0</last>
<snipfile>num2.snip</snipfile>
</stage>
</channel>
The example below usea the same snipfile for both stage ranges.
However,
in the second usage we override B58F4 with a new value that should only
be
assigned to "stage 0".
<channel name="dav_BHN">
<snipfile>BHN.snip</snipfile>
<!-- this snip file is used for the B50 and B52
information only, even if more blockettes are contained in this snip
file -->
<stage>
<first>1</first>
<last>6</last>
<snipfile>num1.snip</snipfile>
<!-- We will get the first 6 stages from this file -->
</stage>
<stage>
<first>0</first>
<last>0</last>
<snipfile>num1.snip</snipfile>
<!-- We will get the final stage from this
file
-->
<init name="overall sensitivity">
<field> B58F4 </field>
<val> 1.11111E+09 </val>
</init>
</stage>
</channel>
Putting it all together
In the following example we define a Single
Station/Channel
for 2 time ranges. We override
some
values, filter by snippet stage number, and add together two response
sections
covering 2 different time ranges for a single Station/Channel.
<station name="DAV">
<init name="latitude">
<field> B50F4</field>
<val> 30.2 </val>
</init>
<init>
<field> B50F10</field>
<val> this is a station comment B50F10
</val>
</init>
<init name="longitude">
<field> B50F5</field>
<val> 40.5 </val>
</init>
<channel name="dav_BHZ">
<snipfile>hill4_BHZ.snip</snipfile>
<starttimefilter>1995,001</starttimefilter>
<endtimefilter>1997,001</endtimefilter>
<!-- These time filters will apply to the stage listed below -->
<stage>
<first>1</first>
<!-- For this snipfile, we use all snippets from stage 1 to
the
end.
-->
<snipfile>snip0.snip</snipfile>
</stage>
</channel>
<channel name="dav_BHZ">
<snipfile>hill4_BHZ.snip</snipfile>
<starttimefilter>1998,001</starttimefilter>
<endtimefilter>2001,001</endtimefilter>
<!-- These time filters
will
apply to the stage listed below -->
<stage>
<first>1</first>
<last>5</last>
<snipfile>snip1.snip</snipfile>
</stage>
<stage>
<first>6</first>
<snipfile>snip2.snip</snipfile>
</stage>
</channel>
</station>
Specifying
missing
fields in the RESP file.
When adding missing fields to the RESP files, we have followed the
example
of rdseed and how it structures the RESP information when the -R output
is
used. This format is the traditional format used by EvalResp. Below we
illustrate
the difference between the original RESP file, and how it has been
augmented
for use by SHAPE.
Original RESP file
section
for Blockettes 50 and 52
#
<< IRIS SEED Reader, Release 4.18 >>
#
#
======== CHANNEL RESPONSE DATA ========
B050F03 Station: DAV
B050F16 Network: IU
B052F03 Location: 01
B052F04 Channel: BHN
B052F22 Start date: 1994,352,00:00:00.0000
B052F23 End date:
1997,318,00:00:00.0000
#
=======================================
New RESP file
section
for Blockettes 50 and 52
# << IRIS SEED
Reader,
Release 4.18 >>
#
# ======== CHANNEL RESPONSE DATA
========
B050F03 Station: DAV
B050F16 Network: IU
B052F03 Location:
01
B052F04 Channel: BHN
B052F06 Instrument: TEST
B052F08 Units of signal response: M/S -
Velocity
in Meters Per Second
B052F09 Units of Calibration Input: V - Volts
B052F14 Azimuth: 0.0 Degrees
B052F15 Dip: 0.0 Degrees
B052F16 Steim 2 50
B052F16 keys F1 P4 W4 D C2 R1 P8 W4 D C2
B052F16 keys P0 W4 N15 S2, 0,1
B052F16 keys T0 X W4
B052F16 keys T1 Y4 W1 D C2
B052F16 keys T2 W4 I D2
B052F16 keys K0 X D30
B052F16 keys K1 N0 D30 C2
B052F16 keys K2 Y2 D15 C2
B052F16 keys K3 Y3 D10 C2
B052F16 keys T3 W4 I D2
B052F16 keys K0 Y5 D6 C2
B052F16 keys K1 Y6 D5 C2
B052F16 keys K2 X D2 Y7 D4 C2
B052F16 keys K3 X D30
B052F17 Data Record
Length:
11 (power of 2)
B052F22 Start date: 1994,352,00:00:00
B052F23 End date:
1997,318,00:00:00
Please note that since the information reference by B52F16 can be quite
complex,
this info must be entered in a specific order, with the first line
containing
the "short name" (Blockette 30, Field 3) and then the followed by
the
Data Format Identifier Code (Blockette 30, Field 5). The following
lines
contain the key word "keys" followed by a single key. if there are 5
keys,
then their will be 5 lines that start with the following text
"B052F16
keys ". This is the only field that requires multiple lines.
Example HAT files.
Here are some links
to
example HAT files.
Single RESP file for a HATfile
1 Channel, 2 time ranges
2 stations
Downloads
Linux
executable
Solaris Executable
Mac executable
Usage
shape HAT.XML new.dataless
This will read in the HAT.XML file and create a dataless called
new.dataless.
Author.
For information, contact
Sid Hellman - info@isti.com
This Software make use of the JavaSEED objects written by Rob Casey of
the
IRIS/DMC.