.. _configuration: 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 ------------------------------------------ .. glossary:: 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) ---------------------------------------------- .. glossary:: 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 ---------------------------------------------- .. glossary:: 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 ---------------------------------------------- .. glossary:: 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 ---------------------------------------------- .. glossary:: 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