osopcal

osopcal was developed to replace both the dispcal and tiltcal programs written by Doctor Erhard Wielandt, the methodology of which is described at:

osopcal can be used to verify the gain for accelerometers (sensor only), accelerographs (sensor + digitizer), seismometers (sensor only) and seismographs (sensor + digitizer).

osopcal supports data from short-period and broad-band sensors in miniSEED format.

Dependencies

The program is shipped as a Docker container and will run on any Docker-compatible operating system where Docker is installed.

  • docker
  • a license file from OSOP (osopcal is commercial-grade software and is delivered free-of-charge with the purchase of an OSOP Calibration Table)

Installation

  1. Make sure you have Linux and Docker installed

  2. Download the attachment, install.sh, emailed to you by OSOP to the machine where osopcal will run

  3. From a command line run

    $ chmod +x install.sh
$ sudo ./install.sh

  4. To generate the license machine-ID OSOP needs to create the license keys, start osopcal on each machine where it is expected to run:

    $ sudo osopcal

  5. The license machine-ID will be output to the screen (and the program will quit). E.g., b063a4faa380d0cdf3b395cb09298e0b:

5.1 Copy all machine-IDs to a spreadsheet

5.2 Return the spreadsheet to OSOP

  1. OSOP will generate the license keys for each computer and email them back to you:
6.1 Download each key to the corresponding computer to the directory /opt/osop/license/. Make sure it is named “osopcal.key”
  1. Configure osopcal at /opt/osop/osopcal/config/setup.py. Set the appropriate variables (more on this below), provide the input file with the calibration signal from the calibration table.
  2. Start osopcal as in step 4

Execution

Execute as follows from the command-line

$ sudo osopcal

The program will print some debugging information and the gain restored from the calibration signal.

Best 12 Steps: 1499.2051 +- 0.1502 Vs/m

Here, 1499.2051 is the restored gain, and 0.1502 is uncertainty.

Calibrating just the sensor vs. calibrating the whole chain (sensor + digitizer)

Originally, dispcal and tiltcal were intended to calculate the gain of just the sensor hardware. In the original setup, the hardware chain consists of the sensor and the digitizer with known sensitivity. To make osopcal.py calculate just the sensor’s gain, set the ‘SENS’ variable in /opt/osop/osopcal/config/setup.py to the sensitivity of the digitizer in microvolts per count and output will be V/(m/s) or V/(m/s**2).

With modern sensors, we sometimes cannot split the chain into stages with known gains or we may not know the digitizer’s sensitivity. Still, osopcal.py can calibrate the whole chain at once. To do the whole chain calibration, set the ‘SENS’ variable to 1e6 (in fact, it is dimensionless and can be thought of as microvolts per volt.) Output will be counts/(m/s), or the same units as the “Sensitivity” at the end of a RESP-formatted instrument response file. The output might also be in counts/(m/s**2) if processing accelerometer data.

Input data

The program requires:

  • configuration parameters properly set in /opt/osop/osopcal/config/setup.py, and
  • input waveform data file located at /opt/osop/osopcal/data/ which contains a calibration trace.

Input data can be in miniSEED, ASL or SEIFE format. To convert to miniSEED from SAC, for example, use a converter available at: http://www.orfeus-eu.org/software/waveform_conversions.html.

Note about the input calibration signal

When recording a calibration signal, 3 conditions must be met:

  1. At the beginning and the end of the trace, there must be 10-15 calm seconds, but not much more. This is because the program deconvolves the signal with IIR filters which produce the ground motion signal + some function, and then tries to approximate this function with polynomials and remove it. When calm tails are too long, upper degrees of the Taylor expansion of this trend arise, polynomial approximation of a fixed degree is poor, and to poor precision of the results. We have included new functionality in with osopcal (span.py) that will allow you to cut the waveform data on-the-fly.
  2. The platform must spend approximately 3 seconds in the extreme positions (i.e., ~3s in the upper position and ~3s in the lower position each step).
  3. It is recommended that there be 15-20 pulses in the calibration signal.

Note

if there are discrepancies between these instructions and those contained in the video manual, please follow the instructions written here.

Note on the format of the PAZ dictionary

This is an advanced option. On rare occasions it may be useful to specify the RESP field in /opt/osop/osopcal/config/setup.py as a PAZ dictionary.

Let’s use the example from above:

RESP = { 'zeros': [0j, 0j],
        'poles': [-0.01+0.01j, -0.01-0.01j],
        'gain':  1.0,
        'sensi': 1500.0 }

This dictionary must contain 4 entries: ‘zeros’, ‘poles’, ‘gain’, ‘sensi’.

‘zeros’ and ‘poles’ are just the complex zeros and poles of a response polynomial.

‘gain’ is the same as the A0 normalization factor from the RESP file or from a dataless SEED. It is a factor that makes the complex polynomial evaluate to a complex number of amplitude 1.0 at some predefined frequency. To learn more about the ‘gain’ or A0 coefficient, please consult

https://www.fdsn.org/seed_manual/SEEDManual_V2.4.pdf,

section ‘Appendix C: Specifying and Using Channel Response Information’.

‘sensi’ has the meaning of the ‘Sensitivity’ field in the RESP file. The value of ‘sensi’ is not used in calibration, it is nominal and is not used for anything but reporting. In fact, osopcal calculates the true sensitivity of a sensor based on a calibration signal. When it has access to the nominal sensitivity (from the RESP file or from the ‘sensi’ field of a PAZ dictionary), then, along with the usual debugging and output information, it reports the relative difference of the calculated and the nominal sensitivity in percent.

Configuration

See: /opt/osop/osopcal/config/setup.py

VERT

Description: flag to indicate if we are calibrating the vertical or horizontal components. True implies Z, False implies E or N

Type: Bool

MODE
Description: one of: ‘VEL’, ‘ACC’. ‘VEL’ means that the input signal comes from a velocity sensor and contains a velocity trace. ‘ACC’ means that the input signal comes from an accelerometer.
NAME

Description: input file. Can be miniSEED, ASL, or SEIFE formatted

Type: string

RESP

Description: sensor’s response used for deconvolution. Can be:

  1. None or not set, which means no deconvolution,
  2. name of the RESP file,
  3. PAZ dictionary,
  4. free period (in seconds) and damping.

Example of 2) the name of the RESP file:

RESP = ‘data/RESP.SS.S181..EHE’

Example of 3) the PAZ dictionary:

RESP = { 'zeros': [0j, 0j],
        'poles': [-0.01+0.01j, -0.01-0.01j],
        'gain':  1.0,
        'sensi': 1500.0 }

Example of 4) the free period and damping:

RESP = 120.0, 0.707
SENSE

Description: sensitivity of the digitizer. If we calibrate just the seismometer, should be set to the actual sensitivity of the digitizer. If we calibrate the whole sensor/digitizer/filters chain, must be 1e6.

Type: float

Units: microvolts per 1 volt

STEP

Description: calibration step, displacement. This is what you read off the dial/ electronic indicator.

Type: float

Units: mm

DIST

Description: safety distance from pulse flanks in seconds, should be 0.5s or similar.

Type: float

Units: seconds

FILT

Description: corner period of the low-pass filter. No filtering applied if 0.0

Type: float

Units: seconds

CORR
Description: correction factor, (RR+RS)/RR, where RS is the sensor impedance, and RR is the digitizer impedance. Should be 1.0 or slightly above, like 1.014. In general, 1.0 works fine.
PLOT

optional, for development purposes

Description: Plots some data from inside the processing stages. It is useful only for debugging, and usually can be safely omitted.

Type: boolean

ORIG

optional, for development purposes

Description: Useful only for horizontal calibration debugging. Should be used only with the original horizontal data from the authors of Tiltcal, should be never used with the data from OSOP tables.

Type: boolean

BPAR

optional, not for OSOP Calibration Table users

Description: Length of the horizontal table extension; useful only for horizontal experiments (VERT = False). For vertical experiments (VERT = True), it is ignored. Defaults to 484 mm (length of the OSOP Calibration Table extension bridge/ platform).

Type: float

Units: mm

Test data

We have included some test data to help you familiarize yourself with the program. See /opt/osop/osopcal/config/setup.py for full details. Test data sets are bounded by ‘’’ symbols. In order to activate a test data set, comment out the first ‘’’ using #. For example,

#'''
VERT = True
MODE = 'VEL'
NAME = '/opt/osop/osopcal/example-data/vertical-table1-finaltest-131um.mseed'
RESP = '/opt/osop/osopcal/example-data/RESP.SS.ICETC..HHZ'
SENS = 1e6
STEP = 0.131
DIST = 0.2
FILT = 0.0
CORR = 1.0
PLOT = True
#'''

Plots

X-axis: time (seconds)

Y-axis: amplitudes (counts)

Legend:

  • Input data: raw data from miniSEED file. See: osopcal/config/setup.py:NAME
  • Detrended: Input data detrended
  • Difference: Detrended minus Input data
  • Ground acceleration (scaled and shifted): the ground acceleration computed, then scaled and shifted
  • Calm regions or “battlements” (scaled and shifted) - the regions used to restore instrument Sensitivity (the overall gain of the system)

What to look for: See Interpretation below.

Interpretation

The Sensitivity calculated by the osopcal program is only as good as the input data. Make sure that 1) the input data has 10-15 seconds of calm before and after the displacements from the calibration table; 2) the displacements are large and unambiguous; and 3) the battlements are large and clear before using the results.

Note

The calibration table does not produce enough displacement to produce significant signal-to-noise ratios for good results with 14-bit sensors (like kinds of MEMs accelerometers you would find in your phone).