Configuration parameters explained

respGen is configured via setup.py in the project directory. Copy setup.py.example to setup.py and edit it to match your data and desired parameters. This file is imported by all processing stages at runtime.

Parameters common to more than one stage

UFILE

Default value: ‘DATA/10_LHZ.512.seed’

Description: The miniSEED-formatted waveform binary file from the sensor with the unknown response.

Stages: Used in view_cohe, stages 0 & 1

Required?: Yes

Comments: If UFILE and KFILE have different start and end times, they will be cut to match. If UFILE or KFILE have gaps, the program will exit.

KFILE

Default value: ‘DATA/00_LHZ.512.seed’

Description: The miniSEED-formatted waveform binary file from the sensor with the known response.

Stages: Used in view_cohe, stages 0 & 1

Required?: Yes

Comments: See UFILE (above)

URESP

Default value: ‘DATA/RESP.IU.KIP.10.LHZ’

Description: The RESP-formatted text file of the unknown sensor response

Stages: Used in stages 0 & 4

Required?: No

Comments: The RESP-formatted instrument response text file for the sensor with the unknown response. Used in Stage 0 and Stage 4 for visual comparison only.

KRESP

Default value: ‘DATA/RESP.PA.BRU2..EHZ’

Description: The RESP-formatted text file of the known sensor response

Stages: Used in stages 0 & 2

Required?: Yes

Comments: The RESP-formatted instrument response text file for the sensor with the known response. Used in Stage 0 for visual comparion and in Stage 2 to restore the response of the unknown instrument.

OVERLAP_FRACTION

Default value: 0.8

Description: Consequent time windows overlap by this amount of their length

Stages: Used in view_cohe and stage 1

Required?: Yes

NUM_OF_WINDOWS

Default value: 100

Description: Approximately this amount of time windows will be used (and the longest period/lowest frequency automatically calculated) according to the ‘100x’ rule.

Stages: Used in view_cohe and stage 1

Required?: Yes

Comments: This determines the window length and hence, the lowest frequency resolved. According to the Adam Ringler’s recommendations, if you want to resolve a frequency, you have to robustly average ~100 coefficients for that frequency which are independent, that is, coming from different time windows (100x rule). As we are interested most in the lower part of the response, the window length should be made as big as possible. The algorithm chooses the maximum power of 2 so that approximately NUM_OF_WINDOWS windows of that length, overlapped by OVERLAP_FRACTION, will fit into the waveform

LOWFRQ

Default value: 0.0001

Description: The lowest frequency of interest plotted

Stages: Used in stages 0 & 4

Required?: Yes

Comments: Choose this around a decade or so past what you suspect is the low corner frequency or the unknown sensor. Recommended values for: [B,H,L]HZ, Broad band: 0.0001; [E,S]HZ, Short period: 0.01.

LP_FILTER_HZ

Default value: None

Description: Cutoff frequency (Hz) for a zero-phase low-pass filter applied to both input traces before transfer function estimation. Set to None to disable.

Stages: Used in stages 1 and 1e

Required?: No

Comments: Sensors are typically flat to approximately 0.7–0.8 × Nyquist — the high-frequency corner is controlled by the decimation routine and is already accounted for. Applying a low-pass filter to both traces before the FFT removes aliased energy near Nyquist that can contaminate coherence estimates at lower frequencies. Because the same zero-phase Butterworth filter (filtfilt) is applied identically to both traces, it cancels exactly in the transfer function ratio (U_filt / K_filt = U / K in the passband) and introduces no phase distortion in the frequency band of interest.

Recommended: set to 0.7–0.8 × Nyquist. Examples: 40.0 for 100 sps data (Nyquist = 50 Hz); 0.35 for 1 sps data (Nyquist = 0.5 Hz). Set to None to skip filtering entirely.

Interplay with COHE_LIMIT: The practical effect of LP_FILTER_HZ depends on COHE_LIMIT. If coherence near Nyquist is already poor (as is typical for sensors on a shake table, where the sensor response rolls off before Nyquist), those high-frequency points will be excluded by the coherence mask in Stage 3 regardless of whether the filter is active. In that case LP_FILTER_HZ has little effect on the final poles and zeros. The filter is most valuable when COHE_LIMIT is relaxed (e.g. 0.75) or when the data contains broadband noise that leaks aliased energy into lower frequencies — situations where near-Nyquist contamination might otherwise survive the coherence mask and bias the rational function fit.

stage 1(e)

NUM_OF_POINTS

Default value: 1500

Description: Number of ‘deputy’ frequencies which survive after exponential culling

Required?: Yes

Comments: If you set this to a value greater than the total number of frequencies participating in the FFT, it has no effect; in that case, all the original frequencies are used. The NUM_OF_POINTS is the number of frequencies participating in transfer function. The frequencies for the transfer function are generated using exponential range (i.e., the spacing between the consecutive frequencies increases exponentially).

stage 2

MEDIAN_LEN

Default value: 7

Description: Median filter length. Must be an odd value. Must be odd.

Required?: Yes

Comments: A value of 7 seems to nicely remove peaks and gaps of 1 or 2 points.

stage 3

COHE_LIMIT

Default value: 0.99

Description: Coherence threshold. Frequency points with coherence below this value are excluded from the poles-and-zeros fit in Stage 3.

Required?: Yes

Comments: Higher values produce a cleaner fit by discarding noisy frequency bins, but require high-quality, well-coherent data. Recommended values: 0.99 for good shake-table data (Raspberry Shake + known reference); 0.75 for noisier or more difficult datasets (e.g. Geopulse). If Stage 3 finds no valid M/N configuration, try lowering COHE_LIMIT before switching to fixed degrees (DETERMINE_DEGREE = False).

Interplay with LP_FILTER_HZ: LP_FILTER_HZ attenuates near-Nyquist energy in both traces before the FFT, which tends to lower coherence at those frequencies and cause more points to be excluded by COHE_LIMIT. When COHE_LIMIT is already strict (e.g. 0.99) and the sensor response naturally rolls off near Nyquist, near-Nyquist points are typically excluded by coherence alone — making LP_FILTER_HZ redundant for clean datasets. The filter provides the most benefit when COHE_LIMIT is relaxed, where aliased near-Nyquist energy might otherwise survive into the fit.

DETERMINE_DEGREE

Default value: True

Description: Stage 3 can either select the best degree of the polynomials participating in the rational function, or the degrees can be given below. True is the default, while False is useful for development. If this is True, we must provide the maximum degree NMAX below which is used in the search. If this is False, we must provide the degrees of the polynomials MM and NN below. When True, stage 3 automatically finds the best configuration of MM and NN.

Required?: Yes

NMAX

Default value: 6

Description: If above is True, provide the maximum number of poles used for search

Required?: Only if DETERMINE_DEGREE is True

NN

Default value: 4

Description: Number of poles

Required?: Only if DETERMINE_DEGREE is False

MM

Default value: 3

Description: Number of zeros

Required?: Only if DETERMINE_DEGREE is False

Note: Stage 4 will add an additional zero is the units are in velocity. So, when NN = MM = X, the result might be X+1 zeros in total.

stage 4

NORMFREQ

Default value: 0.1

Units: Hertz (Hz)

Description: Frequency of sensitivity for RESP encoding. Used both in RESP field B053 as ‘Normalization frequency’ and in RESP field B058 as ‘Frequency of sensitivity’. Choose a frequency in the flat portion of the instrument response curve (e.g., 0.1 for LH channels and 5 for BH or HH channels).

Required?: Yes

Comments: Recommended values for: LHZ (0.1); BHZ (5); SHZ (5); EHZ (5); HHZ (5)

ZERO_LIMIT

Default value: 0.0015

Description: zeros which are closer than this to the origin are set to pure 0+0j

Required?: Yes