Building a stage information file with different filters

Conceptually, stages are each of an electronic block diagram “boxes”. An instrument component has an ordered list of stages. Each stage has certain signal treatment characteristics.

It is important to note that, since stages are chained:

  • The output units of a stage must match the input units of the next stage.

  • In digital stages, the output sample rate of a stage must match the input sample rate of the next stage.

  • The declared sample rate of the instrument as a whole must match the calculated sample rate of the list of stages.

To allow flexible use of stages, as exemplified in the datalogger information file above, it is a good idea to ONLY specify the input sample rate

for the first stage (output sample rates cannot be specified, they are calculated). For example, the FIR2 stages in the datalogger example above only specify the decimation factor. This means that, their output sample rate will be their input sample rate divided by their decimation factor. If the next stage’s input sample rate is not specified, it will be set to the previous stages output sample rate. If it’s input sample rate IS specified, it will be compared to the previous stag’s output sample rate and an error will be generated if it is not the same.

All stages have one associated filter. This may seem illogical, as some stages are not properly filters, but rather analog or digital amplifiers (they only apply a gain) or analog-to-digital converters. StationXML requires that these stages be implemented as filters with specific filter paramters. obsinfo_ provides special “filters” for these cases, which saves the user having to remember what these parameters are.

Below is is a stage for a preamplifier. It is analog and only has a gain. with no other processing. We specify the input_units and output_units and a gain, composed of a value and a frequency at which the gain value was measured. The associated filter is of type ANALOG. All these are required fields. There is also an optional, but recommended, description and an optional polarity.

---
stage_base:
   description : "PREAMPLIFIER: BBOBS 0.225x"
   input_units : {name: "V", description: "VOLTS"}
   output_units : {name: "V", description: "VOLTS"}
   gain : {value : 0.225, frequency: 0}
   filter : {type : "ANALOG"}
  polarity: "+"

Next is another pseudo-filter, an analog to digital converter used in the first stage of a datalogger:

---
notes:
   - "From CS5321-22_F3.pdf"
stage_base:
   description : "DIGITIZER - CS5321 Delta-Sigma A/D converter" #  optional
   input_units : {name : "V", description: "Volts"}
   output_units : {name : "counts", description: "Digital Counts"}
   input_sample_rate : 256000
   decimation_factor : 8
   gain :
       frequency: 0
       value: 1165084   # output_units/input_units
   filter:
       type : "AD_CONVERSION"
       input_full_scale : 9 #  9 V pp
       output_full_scale : 10485760 #  4FFFFF@Vref and B00000@-Vref

Although the input is analog, we specify an input_sample_rate in agreement with StationXML specifications. The output rate, as mentioned above, is calculated from the input_sample_rate and the decimation_factor. In this example, the output sample rate will be 32000 sps. The other filter fields will be discussed in the next section.

The notes element will not be put into the output StationXML file. Other optional attributes can be consulted in the corresponding Stage, but three elements bear further explanation: delay, offset and correction.

delay, offset and correction attributes

Digital filters have a delay.samples element, which specifies by how many samples the peak of an impulse will be offset by the filter.

The stage level also has an element called delay, which corresponds to the StationXML Stage:Delay field, expressed in seconds. In general, we recommend that you provide the filter:delay.samples value rather than the stage:delay value because the prior is independent of the sampling rate. If you provide filter:delay.samples, obsinfo_ will calculate the stage:delay value at runtime. If you provide both, obsinfo_ will calculate this value, compare it to the stage:delay value, and set an error if the two are not the same.

Correction is a StationXML Stage attribute which obsinfo calculates, as mentioned in the previous section, from the datalogger:correction field.

Polarity

Each stage can have a polarity. If omitted it is assumed to be “+”. A “+” polarity means:

  • For a seismometer, a postitive voltage corresponds to a movement UP.

  • For a hydrophone, a positive voltage corresponds to an INCREASE in pressure

  • For a non-sensor stage, the passband output has the SAME polarity as the passband input

A “-” polarity means:
  • For a seismometer, a postitive voltage corresponds to a movement DOWN.

  • For a hydrophone, a positive voltage corresponds to a DECREASE in pressure

  • For a non-sensor stage, the passband output has the OPPOSITE polarity as the passband input

The channel’s polarity is obtained by by multiplying the polarities in all of a channel’s stages (where “+”=+1 and “-“=-1). For seismometer and hydrophone channels, a positive polarity corresponds to dip = -90º and a negative polarity to dip = 90º