pysep.utils.process =================== .. py:module:: pysep.utils.process .. autoapi-nested-parse:: Utilities for processing waveforms Functions --------- .. autoapisummary:: pysep.utils.process.format_streams_for_rotation pysep.utils.process.append_back_azimuth_to_stats pysep.utils.process._append_null_trace pysep.utils.process._check_component_availability pysep.utils.process.rotate_to_uvw pysep.utils.process.trim_start_end_times pysep.utils.process.merge_gapped_data pysep.utils.process.resample_data pysep.utils.process.zerophase_chebychev_lowpass_filter pysep.utils.process.estimate_prefilter_corners Module Contents --------------- .. py:function:: format_streams_for_rotation(st) ObsPy requires specific channel naming to get stream rotation working. Comb through the stream and check that this is correct before passing stream to rotation :type st: obspy.core.stream.Stream :param st: Stream to format for rotation :rtype st: obspy.core.stream.Stream :return st: Stream that has been formatted for rotation .. py:function:: append_back_azimuth_to_stats(st, inv, event) ObsPy rotation requires back azimuth information which is accessed through trace.stats.back_azimuth. This function appends back azimuth values to the stream by cacluating using metadata from the inventory and event objects. .. note:: This was written and then I realized that `_append_sac_headers_trace` already does this, so it is unused, but left incase it's useful later. :type st: obspy.core.stream.Stream :param st: Stream with missing components :type inv: obspy.core.inventory.Inventory :param inv: optional user-provided inventory object which will force a skip over StationXML/inventory searching :type event: obspy.core.event.Event :param event: optional user-provided event object which will force a skip over QuakeML/event searching :rtype: obspy.core.stream.Stream :return: stream with back azimuth values appended .. py:function:: _append_null_trace(st, component, cmpaz=None, cmpinc=None) Create a copy of a trace with zeroed out data, used for rotation :type st: obspy.core.stream.Stream :param st: Stream with missing components :type component: str :param component: component of data to turn into a null trace :type cmpaz: float :param cmpaz: component azimuth for SAC header :type cmpinc: float :param cmpinc: component inclination for SAC header :rtype st: obspy.core.stream.Stream :return st: Stream that has had null traces appended .. py:function:: _check_component_availability(st) Quick logic check to see if stream is missing horizontals or vertical :type st: obspy.core.stream.Stream :param st: Steam to check :rtype: tuple of bool :return: (is the vertical component missing?, is one or both horizontal components missing?) .. py:function:: rotate_to_uvw(st) UVW orthogonal frame rotation In Symmetric Triaxial Seismometers, the sensing elements are also arranged to be mutually orthogonal, but instead of one axis being vertical, all three are inclined upwards from the horizontal at precisely the same angle, as if they were aligned with the edges of a cube balanced on a corner. TODO test this, not sure how it's supposed to work See reference: http://link.springer.com/referenceworkentry/10.1007/978-3-642-36197-5_194-1 Rotation matrix reference: http://link.springer.com/referenceworkentry/10.1007/ 978-3-642-36197-5_194-1#page-1 :type st: obspy.core.stream.Stream :param st: three-component stream to rotate the UVW :rtype: obspy.core.stream.Stream :return: Stream that has been rotated to UVW .. py:function:: trim_start_end_times(st, starttime=None, endtime=None, fill_value=None) Trim all traces in a Stream to a uniform start and end times. If no `starttime` or `endtime` are provided, they are selected as the outer bounds of the Streams time bounds. :type st: obspy.core.stream.Stream :param st: stream to merge and trim start and end times for :type starttime: obspy.core.UTCDateTime :param starttime: user-defined starttime to trim stream. If None, will get the maximum starttime in entire stream :type endtime: obspy.core.UTCDateTime :param endtime: user-defined endtime to trim stream. If None, will get the minimum endtime in entire stream :type fill_value: str or int or float :param fill_value: How to deal with data gaps (missing sections of waveform before trace start or trace end w.r.t requested start and end times). NoneType by default, which means data with gaps are removed completely. Options include: - 'mean': fill with the mean of all data values in the gappy data - : fill with a constant, user-defined value, e.g., 0 or 1.23 or 9.999 - None: do not fill data gaps .. py:function:: merge_gapped_data(st, fill_value=None, gap_fraction=1.0) Merges traces with the same ID, filling gappy data with values if requested, otherwise removes traces that have gapped data. .. note:: Be careful about `fill_value` data types, as there are no checks that the fill value matches the internal data types. This may cause unexpected errors. :type st: obspy.core.stream.Stream :param st: stream to merge and trim start and end times for :type fill_value: str or int or float :param fill_value: How to deal with data gaps (missing sections of waveform over a continuous time span). NoneType by default, which means data with gaps are removed completely. Users who want access to data with gaps must choose how gaps are filled. See API for ObsPy.core.stream.Stream.merge() for how merge is handled: Options include: - 'mean': fill with the mean of all data values in the gappy data - : fill with a constant, user-defined value, e.g., 0 or 1.23 or 9.999 - 'interpolate': linearly interpolate from the last value pre-gap to the first value post-gap - 'latest': fill with the last value of pre-gap data - False: do not fill data gaps, which will lead to stations w/ data gaps being removed. :type gap_fraction: float :param gap_fraction: if `fill_data_gaps` is not None, determines the maximum allowable fraction (percentage) of data that gaps can comprise. For example, a value of 0.3 means that 30% of the data (in samples) can be gaps that will be filled by `fill_data_gaps`. Traces with gap fractions that exceed this value will be removed. Defaults to 1. (100%) of data can be gaps. :rtype: obspy.core.stream.Stream :return: Stream that has been trimmed .. py:function:: resample_data(st, resample_freq, method='interpolate') Apply a lowpass filter and taper data before resampling it using one of a choice of resampling strategies TODO did not refactor `resample_cut` which doesn't seem to do anything but is included in old code :type st: obspy.core.stream.Stream :param st: Stream to resample data for :type resample_freq: float :param resample_freq: frequency to resample for :type method: str :param method: choice of ObsPy resampling strategy: - interpolate: interpolate data, requires anti-aliasing lowpass filter before interpolating - resample: reample data with fourier methods :rtype: obspy.core.stream.Stream :return: Stream that has been resampled and maybe filtered .. py:function:: zerophase_chebychev_lowpass_filter(tr, freqmax) Custom Chebychev type two zerophase lowpass filter useful for decimation filtering. This filter is stable up to a reduction in frequency with a factor of 10. If more reduction is desired, simply decimate in steps. Partly based on a filter in ObsPy. Filter parameters: rp: maximum ripple of passband rs: attenuation of stopband ws: stop band frequency wp: pass band frequency .. note:: Should be replaced once ObsPy has a proper decimation filter. .. note:: This function affects the trace in place! :type tr: obspy.core.trace.Trace :param tr: The trace to be filtered. :type freqmax: float :param freqmax: The desired lowpass frequency. .. py:function:: estimate_prefilter_corners(tr) Estimates corners for pre-deconvolution (instrument response removal) Essentially band limits the data based on the minimum and maximum allowable periods based on the sampling rate and overall waveform length. See also: https://ds.iris.edu/files/sac-manual/commands/transfer.html Replaces the old `get_pre_filt` function :type tr: obspy.core.trace.Trace :param tr: trace from which stats are taken :rtype: tuple of float :return: frequency corners (f0, f1, f2, f3)