pysep.utils.fmt
===============

.. py:module:: pysep.utils.fmt

.. autoapi-nested-parse::

   Pysep-specific formatting functions



Functions
---------

.. autoapisummary::

   pysep.utils.fmt.channel_code
   pysep.utils.fmt.get_codes
   pysep.utils.fmt.get_data_availability
   pysep.utils.fmt.format_event_tag
   pysep.utils.fmt.format_event_tag_legacy
   pysep.utils.fmt.index_cat


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

.. py:function:: channel_code(dt)

   Specfem outputs seismograms with channel band codes set by IRIS. Instrument
   codes are always X for synthetics, but band code will vary with the sampling
   rate of the data, return the correct code given a sampling rate.
   Taken from Appenix B of the Specfem3D cartesian manual (June 15, 2018)

   :type dt: float
   :param dt: sampling rate of the data in seconds
   :rtype: str
   :return: band code as specified by Iris
   :raises KeyError: when dt is specified incorrectly


.. py:function:: get_codes(st=None, choice=None, suffix=None, up_to=True)

   Get station codes from the internal stream attribute, where station
   codes are formatted NN.SSS.LL.CCc where N=network, S=station,
   L=location, C=channel, and c=component

   :type st: obspy.core.stream.Stream
   :param st: Stream to get codes from by running: tr.get_id()
   :type choice: str
   :param choice: choice of the part of the code returned, available:
       * 'network': return unique network codes (e.g., NN)
       * 'station': return unique network + station codes (e.g., NN.SSS)
       * 'location': return up to location (e.g., NN.SSS.LL)
       * 'channel': return up to channel, no component (e.g., NN.SSS.LL.CC)
       * else: return full station code (e.g., NN.SSS.LL.CCc)
   :type suffix: str
   :param suffix: append a string `suffix` to the end of each code. Used to
       place wildcards at the end of a code, e.g., `suffix`=='?' with
       `choice`=='channel' will give codes like NN.SSS.LL.CC?
   :type up_to: bool
   :param up_to: if True gives code up to the `choice`, e.g.,
       `choice`=='station' would return NN.SSS. If False, returns only `choice`
       code, so e.g., SSS for `choice`=='station'
   :rtype: list
   :return: unique station codes filtered by choice


.. py:function:: get_data_availability(cat, inv)

   Determine data availability based on whether stations are 'on' for a
   given event origin time. Does not check waveforms, only station
   metadata, so not foolproof.

   :type cat: obspy.core.catalog.Catalog
   :param cat: Catalog of events to consider. Events must include origin
       information `latitude` and `longitude`
   :type inv: obspy.core.inventory.Inventory
   :param inv: Inventory of stations to consider
   :rtype: dict
   :return: keys are event resource ids and values are IDs for stations
       that were on during the event origin time


.. py:function:: format_event_tag(event)

   Generate a unique event tag based on event origin time and location using
   Flinn Engdahl regions

   :type event: obspy.core.event.Event
   :param event: event to generate tag from
   :rtype: str
   :return: event_name + FE region


.. py:function:: format_event_tag_legacy(event)

   Generate a unique event tag based on the event time. This was how the
   previous version of PySEP named directories and files. Replaces the old
   `otime2eid` from `util_helpers`

   :type event: obspy.core.event.Event
   :param event: event to generate tag from
   :rtype: str
   :return: event_name specified by event time


.. py:function:: index_cat(cat, idxs)

   ObsPy Catalog does not allow indexing by a list of values
   (e.g., cat[0, 1, 3]) so this convenience function takes care of that by
   forming a new catalog of events chosen by indices

   :type idxs: list of int
   :param idxs: list of indices to index catalog by
   :type cat: obspy.core.catalog.Catalog
   :param cat: Catalog to index. If not given defaults to internal Cat