seisflows.tools.noise
=====================

.. py:module:: seisflows.tools.noise

.. autoapi-nested-parse::

   Preprocessing tools for the ambient noise adjoint tomography Noise
   Inversion workflow module. Tools here are used for waveform rotation
   required for horizontal component sensitivity kernels (RR and TT).



Functions
---------

.. autoapisummary::

   seisflows.tools.noise.rotate_ne_trace_to_rt
   seisflows.tools.noise.rotate_rt_adjsrc_to_ne


Module Contents
---------------

.. py:function:: rotate_ne_trace_to_rt(tr_ee, tr_ne, tr_en, tr_nn, theta, theta_p)

   Used during ambient noise adjoint tomography (workflow: noise inversion) to
   rotate N and E component Synthetic Greens Functions (SGF) to R and T
   components so that they can be directly compared to RR and TT
   Empirical Greens Functions (EGF)

   Naming convention: AB (A=force source direction, B=waveform component)
   Order of input follows Wang et al. 2019 Eqs. 9 and 10

   :type tr_ee: obspy.core.trace.Trace
   :param tr_ee: E component FORCE, E component SGF
   :type tr_ne: obspy.core.trace.Trace
   :param tr_ne: N component FORCE, E component SGF
   :type tr_en: obspy.core.trace.Trace
   :param tr_en: E component FORCE, N component SGF
   :type tr_nn: obspy.core.trace.Trace
   :param tr_nn: N component FORCE, N component SGF
   :type theta: float
   :param theta: azimuth between source station and receiver station in units
       of radians (see Wang et al. 2018 Fig. 1)
   :type theta_p: float
   :param theta_p: theta prime, 180 degrees from the backazimuth of the source
       station and receiver station in units radians. theta != theta_prime
       for a spherical Earth, but they will be close.


.. py:function:: rotate_rt_adjsrc_to_ne(tr, theta, theta_p)

   Rotate RR and TT adjoint sources to N and E components for use in
   N and E component adjoint simulations in ambient noise inversion workflow.

   Paraphrasing Wang et al. (2019) 2.2.2

   Kernels are generated from the time convolution of a forward field due to a
   point force in the [east or north] direction, and an adjoint field obtained
   by injecting [f_TT or f_RR (adjoint source)] in the east and north
   directions at the receiver, with their amplitude modulated by the rotation
   matrix.

   :type tr: obspy.core.trace.Trace
   :param tr: input trace that is either R or T component. Component stat
       of the Trace is required (Trace.stats.component)
   :type theta: float
   :param theta: azimuth between source station and receiver station in units
       of radians
   :type theta_p: float
   :param theta_p: theta prime, 180 degrees from the backazimuth of the source
       station and receiver station in units radians. theta != theta_prime
       for a spherical Earth, but they will be close.
   :rtype: tuple of obspy.core.trace.Trace
   :return: (EE, NE, EN, NN) component adjoint sources that have been rotated
       based on the component of `tr_in`