Source code for mspasspy.algorithms.TimeDomainGIDDecon

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Python wrappers for the time-domain generalized iterative deconvolution
engine.

The underlying operator follows the generalized iterative deconvolution
interpretation of Wang and Pavlis (2016).  Iteration is performed on a sparse
three-component impulse response.  The returned receiver function is that
sparse impulse response convolved with the configured output shaping wavelet
for the requested lag window; it is not the raw sparse result itself.
"""

from mspasspy.util.decorators import mspass_func_wrapper
from mspasspy.ccore.algorithms.deconvolution import TimeDomainGIDDecon
from mspasspy.algorithms._gid_decon_wrapper import _run_gid_rf_decon




@mspass_func_wrapper
def TimeDomainGIDRFDecon(
    seis,
    engine,
    *args,
    signal_window=None,
    noise_window=None,
    external_wavelet=None,
    wavelet_t0=None,
    external_noise=None,
    QCdata_key="TimeDomainGIDDecon_properties",
    return_wavelet=False,
    object_history=False,
    alg_name="TimeDomainGIDRFDecon",
    alg_id=None,
    dryrun=False,
    inplace_return=False,
    handles_ensembles=False,
    function_return_key=None,
    checks_arg0_type=True,
    handles_dead_data=True,
    **kwargs,
):
    """
    Estimate a three-component receiver function with generalized iterative
    deconvolution.

    The engine first builds a configurable inverse operator for the source
    wavelet, applies it to the current residual to form the detection function,
    picks the largest vector spike, subtracts the corresponding shaped source
    pulse from the residual, and repeats until the residual-improvement or
    residual-energy convergence criteria are met.

    This receiver-function API operates in P-relative lag coordinates.  UTC
    input is returned dead with an error; convert it first with
    ``ator(P-arrival epoch)``.

    :param seis: input `Seismogram` containing signal and noise windows.
    :param engine: configured `TimeDomainGIDDecon` instance.
    :param signal_window: optional `TimeWindow` defining the full output and
        iterative analysis window.  When omitted the input datum time range is
        used.  The window must contain the engine's configured deconvolution
        window.
    :param noise_window: optional `TimeWindow` defining pre-event noise.  When
        omitted the engine's parameter-file noise window is used.
    :param external_wavelet: optional prepared wavelet passed directly to the
        GID engine.  This may be a TimeSeries or a bare numeric
        vector.  If omitted, any external wavelet already loaded into
        ``engine`` is preserved; otherwise the engine preserves RF
        compatibility and derives the wavelet from component 2 of the input
        seismogram.  Use ``engine.clear_external_wavelet()`` to force
        component-derived wavelets after loading an external one.
    :param wavelet_t0: physical time of sample zero for a bare vector supplied
        as ``external_wavelet``.  A TimeSeries retains its own coordinates.
        ``None`` preserves the legacy analysis-window-start origin for vectors
        and emits a warning; it is invalid when no external wavelet is given.
    :param external_noise: optional scalar noise `TimeSeries`, `CoreTimeSeries`,
        or `PowerSpectrum` passed to NS-GID inverse stabilization.
        If omitted, any external noise already loaded into ``engine`` is
        preserved.  Use ``engine.clear_external_noise()`` to force the
        configured noise window only.
    :param QCdata_key: metadata key used to store the engine's QC metrics.
    :param return_wavelet: when True return
        ``[rf, actual_output, output_shaping_wavelet]``, where both diagnostic
        waveforms are full ``TimeSeries`` objects.
    :return: deconvolved `Seismogram`, or the list described above when
        ``return_wavelet`` is True.  Dead inputs and recoverable processing or
        diagnostic-access failures return a dead `Seismogram`; with
        ``return_wavelet`` True the auxiliary outputs are ``None``.
    """
    return _run_gid_rf_decon(
        seis,
        engine,
        TimeDomainGIDDecon,
        alg_name,
        signal_window=signal_window,
        noise_window=noise_window,
        external_wavelet=external_wavelet,
        wavelet_t0=wavelet_t0,
        external_noise=external_noise,
        QCdata_key=QCdata_key,
        return_wavelet=return_wavelet,
    )