Epoch plots

.gitattributes

@@ -1 +1,2 @@
 * text=auto eol=lf
+*.png binary

obspy/core/inventory/channel.py

@@ -14,9 +14,11 @@
 from future.builtins import *  # NOQA
 from future.utils import python_2_unicode_compatible
 
+from obspy.core.utcdatetime import UTCDateTime
 from obspy.core.util.obspy_types import FloatWithUncertainties
 from . import BaseNode
-from .util import Azimuth, ClockDrift, Dip, Distance, Latitude, Longitude
+from .util import (Azimuth, ClockDrift, Dip, Distance, Latitude, Longitude,
+                   plot_inventory_epochs)
 
 
 @python_2_unicode_compatible
@@ -365,6 +367,43 @@ def plot(self, min_freq, output="VEL", start_stage=None, end_stage=None,
             unwrap_phase=unwrap_phase, plot_degrees=plot_degrees, show=show,
             outfile=outfile)
 
+    def _get_epoch_plottable_struct(self):
+        # channel is leaf object of inventory tree -- has no sub-dictionary
+        # but does have a sample rate defined
+        # for more information see same-name method in inventory.py
+        plot_dict = {}
+        name = str(self.location_code) + "." + str(self.code)
+        if self.start_date is not None:
+            if self.end_date is None:
+                end = UTCDateTime.now()
+            else:
+                end = self.end_date
+            time_tuple = (self.start_date, end)
+            plot_dict[name] = ([time_tuple], {})
+        return plot_dict
+
+    def plot_epochs(self, outfile=None, colormap=None, show=True,
+                    combine=True):
+        """
+        Plot the epochs of this given inventory object.
+        Returns a pyplot figure which can be saved to file.
+        :param outfile: If included, the plot will be saved to a file with the
+            given filename. (Otherwise it will be displayed in a window)
+        :type outfile: str
+        :param colormap: If this parameter is included, the plot will use the
+            given colorspace for inventory plotting
+        :type colormap: matplotlib.colors.LinearSegmentedColormap
+        :param show: If set as true, will display the plot in a window
+        :type show: boolean
+        :param combine: If set as true, channels with matching epochs will be
+            merged onto the same y-axis values
+        :type combine: boolean
+        """
+        plot_dict = self._get_epoch_plottable_struct()
+        fig = plot_inventory_epochs(plot_dict, outfile, colormap, show,
+                                    combine)
+        return fig
+
 
 if __name__ == '__main__':
     import doctest

obspy/core/inventory/inventory.py

@@ -21,6 +21,7 @@
 import warnings
 
 import obspy
+from obspy.core.utcdatetime import UTCDateTime
 from obspy.core.util.base import (ENTRY_POINTS, ComparingObject,
                                   _read_from_plugin, NamedTemporaryFile,
                                   download_to_file, sanitize_filename)
@@ -29,7 +30,8 @@
 from obspy.core.util.obspy_types import ObsPyException, ZeroSamplingRate
 
 from .network import Network
-from .util import _unified_content_strings, _textwrap
+from .util import (_unified_content_strings, _textwrap, plot_inventory_epochs,
+                   _merge_plottable_structs)
 
 # Make sure this is consistent with obspy.io.stationxml! Importing it
 # from there results in hard to resolve cyclic imports.
@@ -892,6 +894,64 @@ def plot_response(self, min_freq, output="VEL", network="*", station="*",
 
         return fig
 
+    def _get_epoch_plottable_struct(self, combine):
+        # get structure of inventory epoch's data in format
+        # {inventory: ([(start, end)...], sample_rate, subdictionary)}
+        # where subdictionary is recursively the same for netwk, stn, ch data
+        # note that sample rate is only defined for the station level
+        # and subdictionary of inventory is network objects
+        # the conistent formatting at each level means that each level can be
+        # concatenated together -- i.e., each network epoch is a diff. object
+        # in obspy, but here they have their times merged together by name
+        plot_dict = {}
+        sub_dict = {}
+        for network in self.networks:
+            eps = network._get_epoch_plottable_struct(combine)
+            sub_dict = _merge_plottable_structs(sub_dict, eps)
+        if hasattr(self, 'start_date'):
+            start = self.start_date
+            if self.end_time is None:
+                end = UTCDateTime.now()
+            else:
+                end = self.end_time
+        else:
+            start = UTCDateTime(0)
+            end = UTCDateTime(0)
+        time_tuple = (start, end)
+        plot_dict[str('')] = ([time_tuple], sub_dict)
+        return plot_dict
+
+    def plot_epochs(self, outfile=None, colormap=None, show=True,
+                    combine=True):
+        """
+        Plot the epochs of this given inventory object.
+        Returns a pyplot figure which can be saved to file.
+        :param outfile: If included, the plot will be saved to a file with the
+            given filename. (Otherwise it will be displayed in a window)
+        :type outfile: str
+        :param colormap: If this parameter is included, the plot will use the
+            given colorspace for inventory plotting
+        :type colormap: matplotlib.colors.LinearSegmentedColormap
+        :param show: If set as true, will display the plot in a window
+        :type show: boolean
+        :param combine: If set as true, channels with matching epochs will be
+            merged onto the same y-axis values
+        :type combine: boolean
+
+        .. rubric:: Example
+
+        >>> inv = read_inventory()
+        >>> inv.plot_epochs(show=True) # doctest: +SKIP
+
+        .. plot::
+            inv = read_inventory()
+            inv.plot_epochs(show=True)
+
+        """
+        plot_dict = self._get_epoch_plottable_struct(combine=combine)
+        fig = plot_inventory_epochs(plot_dict, outfile, colormap, show)
+        return fig
+
 
 if __name__ == '__main__':
     import doctest

obspy/core/inventory/network.py

@@ -18,10 +18,12 @@
 import fnmatch
 import warnings
 
+from obspy.core.utcdatetime import UTCDateTime
 from obspy.core.util.obspy_types import ObsPyException, ZeroSamplingRate
 
-from .station import Station
-from .util import BaseNode, _unified_content_strings, _textwrap
+from .station import (Station, _group_by_epochs)
+from .util import (BaseNode, _unified_content_strings, _textwrap,
+                   plot_inventory_epochs, _merge_plottable_structs)
 
 
 @python_2_unicode_compatible
@@ -675,6 +677,57 @@ def plot_response(self, min_freq, output="VEL", station="*", location="*",
 
         return fig
 
+    def _get_epoch_plottable_struct(self, combine):
+        # combine is boolean controlling whether or not to merge channels
+        # with matching epochs for any given station
+        # see the description for same-named method in inventory.py
+        plot_dict = {}
+        sub_dict = {}
+        name = str(self.code)
+        for station in self.stations:
+            eps = station._get_epoch_plottable_struct()
+            sub_dict = _merge_plottable_structs(sub_dict, eps)
+        #
+        if combine:
+            for station_key in sub_dict.keys():
+                (station_epoch, channel_dict) = sub_dict[station_key]
+                channel_dict = _group_by_epochs(channel_dict)
+                sub_dict[station_key] = (station_epoch, channel_dict)
+        if self.start_date is not None:
+            start = self.start_date
+            if self.end_date is None:
+                end = UTCDateTime.now()
+            else:
+                end = self.end_date
+        else:
+            start = UTCDateTime(0)
+            end = UTCDateTime(0)
+        # time tuple is just start, end times (does not include sample rates)
+        time_tuple = (start, end)
+        plot_dict[name] = ([time_tuple], sub_dict)
+        return plot_dict
+
+    def plot_epochs(self, outfile=None, colormap=None, show=True,
+                    combine=True):
+        """
+        Plot the epochs of this given inventory object.
+        Returns a pyplot figure which can be saved to file.
+        :param outfile: If included, the plot will be saved to a file with the
+            given filename. (Otherwise it will be displayed in a window)
+        :type outfile: str
+        :param colormap: If this parameter is included, the plot will use the
+            given colorspace for inventory plotting
+        :type colormap: matplotlib.colors.LinearSegmentedColormap
+        :param show: If set as true, will display the plot in a window
+        :type show: boolean
+        :param combine: If set as true, channels with matching epochs will be
+            merged onto the same y-axis values
+        :type combine: boolean
+        """
+        plot_dict = self._get_epoch_plottable_struct(combine=combine)
+        fig = plot_inventory_epochs(plot_dict, outfile, colormap, show)
+        return fig
+
 
 if __name__ == '__main__':
     import doctest

obspy/core/inventory/station.py

@@ -20,11 +20,12 @@
 
 import numpy as np
 
-from obspy import UTCDateTime
+from obspy.core.utcdatetime import UTCDateTime
 from obspy.core.util.obspy_types import ObsPyException, ZeroSamplingRate
 
 from .util import (BaseNode, Equipment, Operator, Distance, Latitude,
-                   Longitude, _unified_content_strings, _textwrap)
+                   Longitude, _unified_content_strings, _textwrap,
+                   plot_inventory_epochs)
 
 
 @python_2_unicode_compatible
@@ -507,6 +508,96 @@ def plot(self, min_freq, output="VEL", location="*", channel="*",
 
         return fig
 
+    def _get_epoch_plottable_struct(self):
+        # list epochs of this inventory sub-object
+        # and the epochs of sub-objects (channels)
+        # see same method in inventory.py for more details
+        channel_epoch_dict = {}
+        plot_dict = {}
+        name = str(self.code)
+        for channel in self.channels:
+            single_channel_dict = channel._get_epoch_plottable_struct()
+            for key in single_channel_dict.keys():
+                # though we use an iterator here we expect only one key
+                if key not in channel_epoch_dict:
+                    channel_epoch_dict[key] = single_channel_dict[key]
+                else:
+                    # if station epoch contains a channel w/ multiple epochs
+                    channel_epoch_dict[key].extend(single_channel_dict[key])
+        start = self.start_date
+        if self.end_date is None:
+            end = UTCDateTime.now()
+        else:
+            end = self.end_date
+        time_tuple = (start, end)
+        plot_dict[name] = ([time_tuple], channel_epoch_dict)
+        return plot_dict
+
+    def plot_epochs(self, outfile=None, colormap=None, show=True,
+                    combine=True):
+        """
+        Plot the epochs of this given inventory object.
+        Returns a pyplot figure which can be saved to file.
+        :param outfile: If included, the plot will be saved to a file with the
+            given filename. (Otherwise it will be displayed in a window)
+        :type outfile: str
+        :param colormap: If this parameter is included, the plot will use the
+            given colorspace for inventory plotting
+        :type colormap: matplotlib.colors.LinearSegmentedColormap
+        :param show: If set as true, will display the plot in a window
+        :type show: boolean
+        :param combine: If set as true, channels with matching epochs will be
+            merged onto the same y-axis values
+        :type combine: boolean
+        """
+        plot_dict = self._get_epoch_plottable_struct()
+        if combine:
+            for key in plot_dict.keys():
+                (station_epoch, sub_dict) = plot_dict[key]
+                sub_dict = _group_by_epochs(sub_dict)
+                plot_dict[key] = (station_epoch, sub_dict)
+        fig = plot_inventory_epochs(plot_dict, outfile, colormap, show)
+        return fig
+
+
+def _group_by_epochs(plot_dict):
+    # if we're just plotting a single station's data
+    # then we can do a simple means of combining epochs
+    # (we don't have to check channels' consistency over multiple epochs)
+    # since (lists of) tuples of immutable objects can be made as sets
+    # we will exploit that in order to create matching epochs
+    epoch_dict = {}  # keys here will be epoch lists made into sets
+    for key in plot_dict.keys():
+        (channel_epochs, _) = set(plot_dict[key])
+        if channel_epochs not in epoch_dict.keys():
+            epoch_dict[channel_epochs] = [key]
+        else:
+            epoch_dict[channel_epochs].append(key)
+    # now epoch_dict has lists of all channels matching a given epoch
+    # we can simplify the plotted dict by merging them
+    # note that these are strings of form "[location].[channel]"
+    # we will set strings like "loc1: (ch1, ch2, ch3), loc2:..." etc.
+    # to be the keys for these matching epochs instead
+    new_plot_dict = {}
+    for epoch_set in epoch_dict.keys():
+        channel_strings = epoch_dict[epoch_set]
+        location_channel_map = {}
+        for channel_name in channel_strings:
+            split_string = channel_name.split('.')
+            location = split_string[0]
+            channel = split_string[1]
+            if location not in location_channel_map.keys():
+                location_channel_map[location] = channel
+            else:
+                location_channel_map[location].append(channel)
+        # now that the epoch listing exists, convert into a single string for plot dict key
+        combined_name = '['
+        for location in location_channel_map.keys():
+            combined_name += channel + ': ' + str(location_channel_map[location])
+            combined_name += ", "
+        combined_name = combined_name.rstrip(', ') + ']'
+        new_plot_dict[combined_name] = (list(epoch_set), {})
+    return new_plot_dict
 
 if __name__ == '__main__':
     import doctest