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 runs on Linux with Docker installed: on a Linux computer, or in a Linux virtual machine (Hyper-V, VirtualBox, VMware). WSL 2 on Windows and Docker Desktop are not supported, because they don’t expose the hardware ID the license is tied to.

  • 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: a Linux computer, or a Linux virtual machine (Hyper-V, VirtualBox, VMware). WSL 2 on Windows and Docker Desktop do not work: they don’t expose the hardware ID the license is tied to.

  2. Copy the installer that you received from OSOP, osopcal-install.sh, to the machine where osopcal will run

  3. From a command line run

    $ chmod +x osopcal-install.sh
    $ sudo ./osopcal-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). For example:

    ❌ osopcal license: no license file found.
       Send this machine ID to OSOP to obtain a license:
    
       OSOP3-YMEQ-SC2H-MV9F-T87B-2J9X
    
       Save the license file you receive as /opt/osop/license/osopcal.key
    

    The machine-ID belongs to the computer: it stays the same when you reinstall or update osopcal.

    Note

    Updating from an older osopcal version? Its license key does not work with osopcal 2.0. Run sudo osopcal after installing and send the new OSOP3-… machine-ID to OSOP for a new key.

5.1 Note the machine-ID of each computer

5.2 Send all machine-IDs to OSOP

  1. OSOP will generate a license key for each computer and send them to you:

6.1 Save each key on the corresponding computer in 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).