.. _interpretation: Interpreting the results ========================= view_cohe ----------- **Be sure to check the coherency before interpreting the results!** We recommend studying the coherence plots carefully before moving on the stage 0. These plots allow the end-user to estimate how robust the final solution will be and at which frequencies it will be most reliable. The more coherent the signals, the better/ more meaningful the results. Ground noise must be "of sufficiently high amplitude to guarantee that one is recording above the" instrument noise "across the entire frequency band of interest". - Pavlis and Vernon, 1994 "Coherence estimates are essential to appraise the validity of results." - Pavlis and Vernon, 1994 "...when signals are highly incoherent, estimates of amplitude will tend to be underestimated, and phase estimates will become poorly determined under these conditions. " - Pavlis and Vernon, 1994 view 3 / stage 3 ------------------ The view3 plot ("Response components from Pavlis and from PZ") overlays the Stage 2 response (dark blue = real part, dark green = imaginary part) against the PZ-fit reconstruction (red = real, cyan = imaginary). A good fit has all four lines tracking closely. **Amplitude underestimation** .. image:: _static/amplitude-issues.png :alt: Example of amplitude underestimation — cyan imaginary part (PZ fit) does not reach the peak of dark green (Stage 2 data) :align: center If the cyan line (imaginary part, calculated from PZ) does not reach the peak amplitude of the dark green line (imaginary part from Stage 2), the PZ fit is underestimating the response amplitude. This typically means the pole/zero model does not have enough degrees of freedom to capture the full shape of the response. To correct this: - Increase the number of poles explicitly by setting ``DETERMINE_DEGREE = False`` and raising ``NN`` (poles) or ``MM`` (zeros) in ``setup.py``. - Alternatively, raise ``COHE_LIMIT`` to force stage 3 to fit only the highest-quality frequency points, which can improve the fit quality in the peak region. After adjusting, re-run stage3 (and stage4) and check whether the cyan and dark green peaks align. Quality grade -------------- Every run produces a quality grade (A/B/C/F) displayed at the top of the Stage 4 summary, on the pole/zero plot, and on the response comparison plot: - **Grade A** — High confidence. No issues detected, MAD% < 3%. The sensitivity and pole/zero extraction can be trusted without further review. - **Grade B** — Acceptable. Minor flags only (asymmetric degree or coherence fallback). Results are usable but worth a quick visual check. - **Grade C** — Low confidence. Concerning issues present: marginal MAD% (5–15%), suspicious A0 (outside [0.8, 2.0] for accelerometers), pole reflection, or scale sign correction. The sensitivity may still be usable, but poles/zeros should be verified against known hardware characteristics. - **Grade F** — Unreliable. Disqualifying issues: MAD% > 15% or A0 outside [0.5, 5.0] (accelerometers only). Results should not be used. Investigate input data quality, coherence, or experiment conditions. The grade is computed from: - **MAD%** (normalized Mean Absolute Deviation) — MAD divided by mean response magnitude, expressed as a percentage. Normalization makes the metric comparable across instrument types (velocity sensors have much larger absolute response values than accelerometers). - **A0** — normalization factor at NORMFREQ; theoretically ~1.0 for accelerometers. Only checked for accelerometer channels (unit code ``N``). For velocity, broadband, and infrasound sensors, A0 depends on the pole/zero arrangement relative to NORMFREQ and is not a quality indicator. - **Degree symmetry** — whether M = N (symmetric degree is preferred) - **Pole reflection** — whether unstable poles were reflected to the left half-plane - **Scale correction** — whether the scale sign was flipped - **Coherence fallback** — whether the coherence threshold had to be lowered from the configured value All grading data is saved in ``out3.diagnostics.json`` for downstream automation, including both raw MAD and normalized MAD%. stage 4 ---------- A transfer function can be approximated by many different combinations of poles and zeros. As the solution is not unique, respGen does not and cannot exactly reproduce the instrument manufacturers published poles and zeros. A Note on the high frequency corner ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ An instrument response file is composed of two basic elements: 1) the response of the seismometer or accelerometer which controls the behavior of the lower frequency corner; and 2) the response of the digitizer which controls the behavior of the high frequency corner. The high frequency corner is generally very steep. It is controlled by the decimation routines commonly employed by digitizer manufacturers to downsample data (e.g., FIR, Butterworth, ...). respGen does not attempt to model this anti-alias filter — it is a digitizer artifact, not a property of the sensor being characterized. **Fitting range truncation (80% Nyquist)** Stage 3 automatically truncates the fitting range to 80% of the Nyquist frequency before polynomial fitting. This is standard seismological practice: the anti-alias filter rolloff near Nyquist (typically 100+ dB) would otherwise consume polynomial degrees producing spurious high-frequency poles/zeros that have no physical meaning. At 100 sps, the fitting cap is 40 Hz; at 1 sps, it is 0.4 Hz. Investigation on RS1D v11 velocity data (100 sps) demonstrated that including the anti-alias region degraded fit quality by 5× (MAD 2.1% vs 0.4% with truncation) and shifted sensitivity by ~2% due to the polynomial being pulled away from the true response at all frequencies — including at NORMFREQ. The truncated fit also produced physically interpretable scale factors, whereas the untruncated fit compensated with unphysical values (scale of 4×10\ :sup:`15` and A0 of 11 million). The anti-alias filter response is known (or can be easily approximated) and the FIR filter coefficients can be manually appended to the resulting RESP file.