seed2db [-lsize logical_size] [-v[v[v]]] [-respdir respdir]
[-stagedir stagedir] [-chansift pffile]
[-tstart tstart] [-tend tend]
[-nodata] [-nodataless] [-nofirerrs]
seedfile [dbname]
Note that seed2db was designed to work in a fundamentally different manner than sd2db. seed2db is designed to produce wfdisc tables that point directly into the SEED files, whereas sd2db reformats the waveform data into new files. For this reason, seed2db does not currently support all of the possible data types that are present in older SEED data. seed2db uses the msd(3) Antelope miniSEED toolbox and will therefore ONLY work with SEED data that contains type 1000 data blockettes. Generally, seed2db should work with any Steim compressed data that contains the 1000 blockettes. Regardless of the data blockettes, seed2db should work on just about any dataless SEED files, to the extent that the SEED blockette types are supported within the CSS3.0 schema (e.g. there is currently no support within the CSS3.0 schema for Generic Response Blockettes (B56), or Response Polynomial Blockettes (B62)).
accept &Tbl{
II_.*_BH.*
IU_.*_BH.*
}
reject &Tbl{
II_PFO_.*
}
This would match all stations in the II and IU networks and
channels with chan starting with "BH" and all location codes,
except for all channels from station "II_PFO" which would be rejected.
units_translations &Arr{
A i amperes 1.0
B - boolean 1.0
C t deg_C 1.0
COUNTS c counts 1.0
COUNTS/M/S - sec/nm 1.e-9
COUNTS/V - 1/volt 1.0
D - degrees 1.0
M D nm 1.e9
M/M S nm/m 1.e9
M**3/M**3 - m**3/m**3 1.0
M/S V nm/sec 1.e9
M/S**2 A nm/sec**2 1.e9
MS T sec 1.e-3
NULL - null 1.0
MB P millibars 1.0
PA I pascals 1.0
PERCENT p precent 1.0
T - teslas 1.0
V v volts 1.0
W/M2 W watts/m**2 1.0
W/M**2 W watts/m**2 1.0
V/M - volts/m 1.0
MPH s meters/sec 0.44704
1 - - 1.0
}
nonresponse_channels &Tbl{
LOG
ACE
OCF
LCE
}
input_reversed no
There needs to be an array for units name translations (units_translations). The key string value corresponds to the SEED units name as it appears in the units abbreviation blockettes (B34). The values of each array consist of three fields; the first is used to fill in the segtype field in the wfdisc and calibration tables (this specifies the natural units of the waveform), the second is used to fill in the units field of the calibration table and the third is used to convert from the SEED units to the appropriate Datascope units according to units.
If an appropriate SEED units translation is missing from the parameter file, then seed2db will die with a fatal error message. This situation will require the user to add the missing units translations into the parameter file and rerun seed2db.
The nonresponse_channels table contains a list of SEED channel codes that define channels for which responses can be missing. These are typically non-seismic and non-waveform channels that contain log messages, "opaque" data and other information that is not characterized by normal SEED instrument responses.
The default order of FIR coefficients in the input SEED blockettes is specified by input_reversed. If input_reversed is no, then the default order is in the forward direction. If input_reversed is yes, then the default order is in the reverse direction.
SEEDERROR - Non-digit character in integer field '_328' - replacing with '0'. - These are basic parsing errors in the SEED file and will also be detected by verseed. seed2db always parses all fields of all blockettes, whether or not seed2db needs the fields for processing. If an integer field contains non-integer characters, then this error will be printed and seed2db will automatically replace each of the offending characters with '0' characters and continue processing. If the field is one of the many fields that seed2db does not use, then these patches will have no effect on the output database. Note that for all integer processing, seed2db always trims leading and trailing blank characters before processing.
SEEDERROR - 1 pole complex conjugate problems in PAZ filter. - These errors represent situations where a complex pole or zero in a Blockette 53 (Poles & Zeros Response Blockette) does not have a corresponding complex conjugate and will also be detected by verseed. When this error is detected, seed2db will look for another complex pole or zero that exactly matches and automatically reverse the sign of the imaginary component. This may or may not be the right thing to do, but in most cases where we see this error it is due to a simple sign error in the specification of the complex conjugate imaginary component.
SEEDERROR - 4 unstable poles in PAZ stage 1 for CI_VCS_BHE 1998:295:04:00:00.000 -> NULL. - These represent situations where one or more complex poles in a Blockette 53 (Poles & Zeros Response Blockette) have positive values for their real components which is indicative of an unstable filter. There are no real-world filters used in seismic instrumentation that are unstable, so when this is seen in the SEED data it is almost certainly in error. Note that sign errors in the real parts of the complex poles can often yield apparently correct amplitude spectra, but completely incorrect phase spectra. We have seen cases where there are poles like this with exactly matching zeros, which completely cancel each other.
SEEDERROR - Improbable value for FIR delay. - These are the most numerous of the SEED errors that seed2db will flag. This error means that the "estimated delay" field in the "Decimation Blockettes" (Blockettes 57 and 47) does not appear to be specified properly. For any FIR anti-alias/decimation filter, in order to properly compute the stage phase response, it is very important to know the location of the zero-time offset point within the FIR coefficient time window. This normally is applied as a correction to the data time stamps within the digitizer firmware (the actual correction is specified in the "correction applied" field). However, regardless of whether or not this is applied properly within the digitizer firmware, the FIR delay should be a known quantity by the filter designers and it MUST be included in the FIR stage filter response function computations. For situations where the timing correction was not applied properly within the datalogger firmware, it would be more appropriate to consider these as constant data timing errors instead of pure-time phase transport delays in the instrument response function; something that would be very confusing to most researchers. Note that the erroneous specification of a zero FIR offset, or any other value that is not accurate, will result in garbled instrument phase responses that will be difficult to use for research purposes.
seed2db checks the validity of all FIR offsets in the following manner. Time symmetric filters are designed as zero-phase filters. Therefore, for symmetric filters, the FIR offset should be exactly the mid-point of the complete coefficient time window. Filter symmetry is determined by 1) the "symmetry code" field in blockettes 61 and 41, or 2) seed2db observes that the coefficients are in fact symmetric for complete coefficient list specifications. When a FIR stage is determined to be symmetric, then the offset will always be set to the mid-point regardless of the SEED "estimated delay" field. For asymmetric filters the situation is more complicated. Most asymmetric filters are designed as causal, minimum phase filters that are intended to preserve first arrival times. In the time domain these filters look like typical low-pass filtered causal impulse functions, i.e. in the forward time direction they look like impulsive signals with no time precursors (unlike the Gibb's ringing in zero-phase filters) where the peak signal energy is close to the beginning of the coefficient sequence. For these types of filters the FIR offset should point to the beginning of the impulse response which should be close to the beginning of the coefficient sequence. Note that the time ordering convention is very important for asymmetric filters. We have observed that the great majority of asymmetric FIR filters in SEED files are specified in REVERSE time order although we have been told that the SEED "standard" for specification of FIR coefficients is forward time order. The assumption seed2db makes about the default order of SEED FIR coefficients is controlled by the input_reversed parameter in the seed2db parameter file. In the CSS3.0 schema, the standard for FIR filters is in forward time order, so seed2db automatically reverses the coefficients before further processing or not depending on the input_reversed parameter. seed2db then makes an estimate of what the FIR offset should be, based upon the assumption that the FIR filter is low-pass, using a frequency-domain technique for the offset estimation. If the specified offset from the SEED file is somewhere around the estimated value, then the SEED offset is used. If the offset from the SEED file is grossly different from the estimate, then the estimate is used. The estimation technique we use only depends on the low-pass assumption and not on any phase design assumption (i.e. zero phase vs. minimum phase), so it should work on all of the decimation FIR filters.
SEEDERROR - Asymmetric FIR coefficients in wrong order. - These represent situations where FIR anti-alias/decimation stage coefficients appear to be in the wrong time order. This check is only done with asymmetric FIR filters. We assume a default SEED order depending on the input_reversed parameter. The error is detected by a peak FIR coefficient value in an asymmetric filter that is somewhere in the last third of the coefficient sequence in the original SEED representation of the coefficients, if input_reversed is set to no, or the first third of the coefficient sequence in the original SEED representation of the coefficients, if input_reversed is set to yes. When this error is detected, seed2db automatically reverses the coefficients before the delay processing described above.
SEEDERROR - Sensor stage input units, 'M/S', do not match the B0052 (Channel Blockette) signal units, 'V' - These represent inconsistencies in the signal units specifications between those in the "Channel Identifier Blockettes" (blockettes 52) and the input units in the first sensor stage in the response sequence, usually a "Poles & Zeros Response Blockettes" (blockettes 53 and 43). These errors cause confusion for seed2db in determining the waveform signal units and the total instrument sensitivities. In the real-world example above, the first response stage input units are meters per second but the blockette 52 signal units are volts. Whenever seed2db sees this condition it takes the blockette 52 value as the definitive value. Therefore, with this example, the CSS3.0 segtype attribute in the calibration and wfdisc tables would be set to 'v', for volts, and the overall calib attribute in the calibration and wfdisc tables would be set to the inverse of the SEED final sensitivity value from the blockette 58 stage 0 value, with unit scaling. In this case if the true units should instead be meters per second, i.e. the data is in fact seismic velocity data, then the calib values will be grossly wrong (in fact wrong by 10**9) since data with SEED signal units of 'M/S' are normally converted into the CSS3.0 standard of nanometers per second by applying a 10**9 scale factor. We have observed in existing dataless SEED volumes both conditions where we 1) think the blockette 52 value is correct and 2) think that the first sensor stage value is correct. This makes it diffcult for seed2db to always do the right thing automatically. It is therefore very important that the blockette 52 signal units be specified properly in the SEED volumes.
SEEDERROR - Final response samprate of 0.2000 does not match the B0052 (Channel Blockette) samprate of 20.0000 - These represent inconsistencies in the sample rate specifications between those in the "Channel Identifier Blockettes" (blockettes 52) and the final sample rate, computed from the last stage "Decimation Blockettes" (Blockettes 57 and 47), by dividing the "Input sample rate" field by the "Decimation factor" field. Needless to say, these errors cause confusion in the generation of the instrument response function. As with the units errors, we use the blockette 52 values as definitive. When this error occurs, seed2db resets all of the response stage input and output sample rates for each of the FIR and digitizer stages by working backward from the final sample rate, as specified in the blockette 52, back to the original digitizer. The only exception is when the blockette 52 sample rate is exactly zero, in which case the channel output sample rate is set from the last stage decimation blockette sample rate. As with the units errors, we have found both situations where we believe that the blockette 52 sample rate is correct and the last stage sample rate is correct.
SEEDERROR - Calib frequency of 50.0000 greater than Nyquist frequency of 10.0000 for BK_YBIB_BP1 1996:180:23:25:00.000 -> 1998:039:19:07:00.000 - These are serious errors and indicate that the frequency for the final total sensitivity value, in the stage 0 Channel Sensitivity/Gain Blockette (B0058), or the first sensor stage 1 value when the stage 0 value is missing, is greater than the Nyquist frequency for the channel. We consider the error to be serious because the specification of a channel sensitivity at a frequency that is beyond the Nyquist is nonsensical and almost certainly indicates an error in the SEED parameters that could affect both the overall channel sensitivity as well as the response function.
Within the SEED standard, all of the stage response functions should be normalized at a particular frequency and the stage gains are effective only at this normalization frequency. These response normalization frequencies and the stage gain effective frequencies are contained in the Channel Sensitivity/Gain Blockettes (B0058s). Note that gain and sensitivity values, as well as the normalized response functions, will usually change as a function of the normalization frequency (the exception would be for a completely flat response function). Using a normalization frequency that is outside of the usable frequency band of the instrument will result in sensitivity values and response functions that will be confusing and probably wrong. In the CSS Database world, we always normalize all stages of a response at a fixed frequency. According to the SEED manual, "Different stages may be at different frequencies. However, it is strongly recommended that the same frequency be used in all stages of a cascade, if possible." However we have found many cases where this recommendation is not followed. seed2db always uses fixed normalization frequencies, regardless of the SEED stage specifications, by 1) using a single frequency from the stage 0 B0058 and 2) recomputing all of the stage response functions and gains based upon this fixed normalization frequency. However, this can result in "normalized" response functions with huge values in the normal usable passband of the instrument whenever the stage 0 B0058 normalization frequency is way out on the sideband of the instrument.
Note that seed2db does NOT take any remedial action when these errors are detected. We think that when these errors occur, the only acceptable remediation is for the original authors of the SEED data to properly specify the sensitivities/gains, the normalization frequencies and the response function parameters.
SEEDERROR - Product of stage gains (621096176.6280) does not equal final sensitivity (632470000.0000) for BK_ARC_BHZ 2001:152:00:00:00.000 -> 2001:214:00:36:00.000 - These are situations where the product of each of the single stage gains, as specified in the stage Channel Sensitivity/Gain Blockettes (B0058s), is more than 1% different than the final total sensitivity value, in the stage 0 Channel Sensitivity/Gain Blockette (B0058). Because, in practise, there are many channels in SEED volumes whose single stage normalization frequencies are not constant across the stages or equal to the normalization frequency as specified in the final total sensitivity stage 0 B0058, we always first renormalize all of the stage gains to the normalization frequency in the stage 0 B0058 and then do the comparison. When these two gains are not equal, then either there is an error in one or more of the single stage parameters or in the final total sensitivty parameters. Note that seed2db always uses the final total sensitivity parameters regardless of the single stage parameters (unless there are no final sensitivity parameters).
SEEDERROR - Channel Blk. (B0052) and Station Blk. (B0050) lat-lon difference (40.8604,-73.8852 != 41.0056,-73.9079 -> 16.2 km) - These are large inconsistencies (greater than 1 km) between the Station Blockette values for latitutde-longitude and the Channel Blockette values. We assume that when the distance between these coordinates is more than one km, that there is very likely an error in the coordinates in one of the blockettes. When this error is detected, seed2db always uses the Station Blockette coordinates as the coordinates for the channel.
SEEDERROR - No response stages for US_AHID_BHN 1998:261:00:00:00.000 -> NULL. - These errors indicate that for a particular SEED channel over some time range there were no instrument response blockettes. This will cause the output database to contain NULL entries for all of the fields relating to instrument response for that channel.
Following is a list of the SEED control blockettes that seed2db will currently recognize and parse correctly with notes describing how or if they contribute toward the population of the CSS3.0 output database.
Blockettes 5, 8, 10, 11, 12 (Volume Index Control Headers) - The Logical record length field is read and automatically used to set the SEED logical record length from blockettes 5, 8 and 10. All other fields are ignored in these blockettes. Blockettes 11 and 12 are parsed and ignored.
Blockettes 30, 31, 32, 33, 34, 35, 41, 42, 43, 44, 45, 46, 47, 48 (Abbreviation Dictionary Control Headers) - All of these blockettes are parsed and cached for reference by subsequent blockettes. However, only the blockettes 30, 33, 34, 41, 42, 43, 44, 45, 46, 47 and 48 are actually used in the subsequent blockettes that reference them. The other blockettes are ignored.
Blockette 50 - Station Identifier Blockette - These blockettes are used as the primary indication
of new station parameters. seed2db makes the following assumptions about how blockettes 50 appear
and are interleaved with the other station control headers.
1 - One or more blockettes 50 appear at the beginning of a sequence of the other station
control headers (blockettes 52, 53, etc.) that specify the channel and response stage
parameters.
2 - If more than one blockette 50 are together contiguously before the other station control headers,
then they must all have the same station and network codes and their time ranges must not overlap.
3 - After all of the blockettes 50, there may be one or more blockettes 51 and then all of the
other station control headers to define the channels and responses. The blockettes 51 are parsed and ignored.
Blockette 51 - Station Comment Blockette - These blockettes are parsed and ignored.
Blockette 52 - Channel Identifier Blockette - These blockettes are used as the primary indication
of new channel parameters. These blockettes appear after a set of blockettes 50 and take on the station
parameters from the most recent blockettes 50. Note that in the CSS3.0 schema, there are no tables that
have only channel identifiers as primary keys. In any CSS3.0 tables with channel primary keys there are
always also station keys, so it is necessary to join the SEED blockettes 50 and blockettes 52, along
with all of the other response blockettes.
seed2db makes the following assumptions about how blockettes 52 appear
and are interleaved with the other response blockettes (blockettes 53-62).
1 - One and only one blockette 52 must appear at the beginning of a sequence of the other station
response blockettes (blockettes 53-62) that specify the channel and response stage
parameters for that particular channel and time range.
2 - Multiple sequences of blockette 52 and blockettes 53-62 may appear either for the same
channel for different time ranges, or for different channels. When the same channel appears
for different time ranges the time ranges may not overlap.
Blockette 53 - Response (Poles & Zeros) Blockette - These blockettes are used to represent analog or digital response stages expressed as a product of complex poles and zeros. When the B0053 "Transfer function type" field is 'A' or 'B', these complex poles are assumed to be S-domain Laplace transform poles and zeros and are mapped into 'paz' response stages in the CSS3.0 external response file specification (see response(5)). When the B0053 "Transfer function type" field is 'D', these complex poles are assumed to be Z-domain Z-transform poles and zeros and are mapped into 'iir' response stages in the CSS3.0 external response file specification (see response(5)).
Blockette 54 - Response (Coefficients) Blockette - These blockettes are used to represent analog or digital response stages expressed as numerator and denominator coefficients in Laplace or Z-transform polynomial series. When the B0054 "Transfer function type" field is 'D', these coefficients are assumed to be used in a Z-transform series and are mapped into 'fir' response stages in the CSS3.0 external response file specification (see response(5)). Note that currently there are no CSS3.0 external response file specifications that support series-based Laplace transform responses and, therefore, seed2db does not support B0054 "Transfer function type" values of 'A' or 'B'.
Blockette 55 - Response List Blockette - These blockettes are used to represent response stages as tables of frequency-amplitude-phase values and are mapped into 'fap' response stages in the CSS3.0 external response file specification (see response(5)). Note that seed2db does not attempt to re-normalize these types of responses.
Blockette 56 - Generic Response Blockette - These blockettes are used to represent response stages as a list of corner frequencies and associated response slopes (in db/decade). Note that currently there are no CSS3.0 external response file specifications that support responses specified in this manner and, therefore, seed2db parses but does not support B0056 Blockettes. However,seed2db will parse these blockettes, use the input and output units properly and deposit a NULL CSS3.0 response stage.
Blockette 57 - Decimation Blockette - These blockettes are used to represent decimation parameters in stages where digital decimation is taking place, such as anti-alias FIR filtering. seed2db parses and uses these parameters as previously described.
Blockette 58 - Channel Sensitivity/Gain Blockette - These blockettes are used to represent gain and sensitivity parameters for all stages as well as a total final value when the stage number is 0. seed2db parses and uses these parameters as previously described.
Blockette 59 - Channel Comment Blockette - These blockettes are parsed and ignored.
Blockette 60 - Response reference Blockette - These blockettes are used as references to various stage response blockettes that are specified in the Abbreviation Dictionary Control Header Blockettes 41 (like 61), 42 (like 62), 43 (like 53), 44 (like 54), 45 (like 55), 46 (like 56), 47 (like 57), and 48 (like 58). seed2db parses and de-references these blockettes. See the descriptions of their direct analogs.
Blockette 61 - FIR Response Blockette - These blockettes are an alternate to B0054 blockettes specifically for FIR (Finite Impule Response) digital filters only. seed2db parses and uses these parameters as described in the Blockette 54 section.
Blockette 62 - Response (Polynomial) Blockette - These blockettes are used to represent response stages as non-linear polynomial series of the data sample values. Note that currently there are no CSS3.0 external response file specifications that support responses specified in this manner and, therefore, seed2db parses but does not support B0062 Blockettes. However,seed2db will parse these blockettes, use the input and output units properly and deposit a NULL CSS3.0 response stage.
seeddump(1), msd(3)