Source code for obspy.core.event.catalog

# -*- coding: utf-8 -*-
"""
obspy.core.event.catalog - The Catalog class definition
=======================================================
This module provides a class hierarchy to consistently handle event metadata.
This class hierarchy is closely modelled after the de-facto standard format
`QuakeML <https://quake.ethz.ch/quakeml/>`_.

.. note::

    For handling additional information not covered by the QuakeML standard and
    how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`.

:copyright:
    The ObsPy Development Team (devs@obspy.org)
:license:
    GNU Lesser General Public License, Version 3
    (http://www.gnu.org/copyleft/lesser.html)
"""
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)
from future.builtins import *  # NOQA
from future.utils import native_str

import glob
import io
import copy
import os
import warnings

import numpy as np

from obspy.core.utcdatetime import UTCDateTime
from obspy.core.util import NamedTemporaryFile, _read_from_plugin
from obspy.core.util.base import (ENTRY_POINTS, download_to_file,
                                  sanitize_filename)
from obspy.core.util.decorator import (map_example_filename, rlock,
                                       uncompress_file)
from obspy.core.util.misc import buffered_load_entry_point
from obspy.imaging.cm import obspy_sequential

from .base import CreationInfo, ResourceIdentifier

from .event import Event

EVENT_ENTRY_POINTS = ENTRY_POINTS['event']
EVENT_ENTRY_POINTS_WRITE = ENTRY_POINTS['event_write']


[docs]class Catalog(object): """ This class serves as a container for Event objects. :type events: list of :class:`~obspy.core.event.event.Event`, optional :param events: List of events :type resource_id: :class:`~obspy.core.event.base.ResourceIdentifier` :param resource_id: Resource identifier of the catalog. :type description: str, optional :param description: Description string that can be assigned to the earthquake catalog, or collection of events. :type comments: list of :class:`~obspy.core.event.base.Comment`, optional :param comments: Additional comments. :type creation_info: :class:`~obspy.core.event.base.CreationInfo`, optional :param creation_info: Creation information used to describe author, version, and creation time. .. note:: For handling additional information not covered by the QuakeML standard and how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`. """
[docs] def __init__(self, events=None, **kwargs): if not events: self.events = [] else: self.events = events self.comments = kwargs.get("comments", []) self._set_resource_id(kwargs.get("resource_id", None)) self.description = kwargs.get("description", "") self._set_creation_info(kwargs.get("creation_info", None))
[docs] def _get_resource_id(self): return self.__dict__['resource_id']
[docs] def _set_resource_id(self, value): if type(value) == dict: value = ResourceIdentifier(**value) elif type(value) != ResourceIdentifier: value = ResourceIdentifier(value) self.__dict__['resource_id'] = value
resource_id = property(_get_resource_id, _set_resource_id)
[docs] def _get_creation_info(self): return self.__dict__['creation_info']
[docs] def _set_creation_info(self, value): if type(value) == dict: value = CreationInfo(**value) elif type(value) != CreationInfo: value = CreationInfo(value) self.__dict__['creation_info'] = value
creation_info = property(_get_creation_info, _set_creation_info)
[docs] def __add__(self, other): """ Method to add two catalogs. """ if isinstance(other, Event): other = Catalog([other]) if not isinstance(other, Catalog): raise TypeError events = self.events + other.events return self.__class__(events=events)
[docs] def __delitem__(self, index): """ Passes on the __delitem__ method to the underlying list of traces. """ return self.events.__delitem__(index)
[docs] def __eq__(self, other): """ __eq__ method of the Catalog object. :type other: :class:`~obspy.core.event.Catalog` :param other: Catalog object for comparison. :rtype: bool :return: ``True`` if both Catalogs contain the same events. .. rubric:: Example >>> from obspy.core.event import read_events >>> cat = read_events() >>> cat2 = cat.copy() >>> cat is cat2 False >>> cat == cat2 True """ if not isinstance(other, Catalog): return False if self.events != other.events: return False return True
[docs] def __ne__(self, other): return not self.__eq__(other)
[docs] def __getitem__(self, index): """ __getitem__ method of the Catalog object. :return: Event objects """ if index == "extra": return self.__dict__[index] if isinstance(index, slice): return self.__class__(events=self.events.__getitem__(index)) else: return self.events.__getitem__(index)
[docs] def __getslice__(self, i, j, k=1): """ __getslice__ method of the Catalog object. :return: Catalog object """ # see also http://docs.python.org/reference/datamodel.html return self.__class__(events=self.events[max(0, i):max(0, j):k])
[docs] def __iadd__(self, other): """ Method to add two catalog with self += other. It will extend the current Catalog object with the events of the given Catalog. Events will not be copied but references to the original events will be appended. :type other: :class:`~obspy.core.event.Catalog` or :class:`~obspy.core.event.event.Event` :param other: Catalog or Event object to add. """ if isinstance(other, Event): other = Catalog(events=[other]) if not isinstance(other, Catalog): raise TypeError self.extend(other.events) return self
[docs] def __iter__(self): """ Return a robust iterator for Events of current Catalog. Doing this it is safe to remove events from catalogs inside of for-loops using catalog's :meth:`~obspy.core.event.Catalog.remove` method. Actually this creates a new iterator every time a event is removed inside the for-loop. """ return list(self.events).__iter__()
[docs] def __len__(self): """ Returns the number of Events in the Catalog object. """ return len(self.events)
count = __len__
[docs] def __setitem__(self, index, event): """ __setitem__ method of the Catalog object. """ if not isinstance(index, (str, native_str)): self.events.__setitem__(index, event) else: super(Catalog, self).__setitem__(index, event)
[docs] def __str__(self, print_all=False): """ Returns short summary string of the current catalog. It will contain the number of Events in the Catalog and the return value of each Event's :meth:`~obspy.core.event.event.Event.__str__` method. :type print_all: bool, optional :param print_all: If True, all events will be printed, otherwise a maximum of ten event will be printed. Defaults to False. """ out = str(len(self.events)) + ' Event(s) in Catalog:\n' if len(self) <= 10 or print_all is True: out += "\n".join([ev.short_str() for ev in self]) else: out += "\n".join([ev.short_str() for ev in self[:2]]) out += "\n...\n" out += "\n".join([ev.short_str() for ev in self[-2:]]) out += "\nTo see all events call " + \ "'print(CatalogObject.__str__(print_all=True))'" return out
[docs] def _repr_pretty_(self, p, cycle): p.text(self.__str__(print_all=p.verbose))
[docs] def append(self, event): """ Appends a single Event object to the current Catalog object. """ if isinstance(event, Event): self.events.append(event) else: msg = 'Append only supports a single Event object as an argument.' raise TypeError(msg)
[docs] def clear(self): """ Clears event list (convenient method). .. rubric:: Example >>> from obspy.core.event import read_events >>> cat = read_events() >>> len(cat) 3 >>> cat.clear() >>> cat.events [] """ self.events = []
[docs] def filter(self, *args, **kwargs): """ Returns a new Catalog object only containing Events which match the specified filter rules. Valid filter keys are: * magnitude; * longitude; * latitude; * depth; * time; * standard_error; * azimuthal_gap; * used_station_count; * used_phase_count. Use ``inverse=True`` to return the Events that *do not* match the specified filter rules. :rtype: :class:`Catalog` :return: Filtered catalog. A new Catalog object with filtered Events as references to the original Events. .. rubric:: Example >>> from obspy.core.event import read_events >>> cat = read_events() >>> print(cat) 3 Event(s) in Catalog: 2012-04-04T14:21:42.300000Z | +41.818, +79.689 | 4.4 mb | manual 2012-04-04T14:18:37.000000Z | +39.342, +41.044 | 4.3 ML | manual 2012-04-04T14:08:46.000000Z | +38.017, +37.736 | 3.0 ML | manual >>> cat2 = cat.filter("magnitude >= 4.0", "latitude < 40.0") >>> print(cat2) 1 Event(s) in Catalog: 2012-04-04T14:18:37.000000Z | +39.342, +41.044 | 4.3 ML | manual >>> cat3 = cat.filter("time > 2012-04-04T14:10", ... "time < 2012-04-04T14:20") >>> print(cat3) 1 Event(s) in Catalog: 2012-04-04T14:18:37.000000Z | +39.342, +41.044 | 4.3 ML | manual >>> cat4 = cat.filter("time > 2012-04-04T14:10", ... "time < 2012-04-04T14:20", ... inverse=True) >>> print(cat4) 2 Event(s) in Catalog: 2012-04-04T14:21:42.300000Z | +41.818, +79.689 | 4.4 mb | manual 2012-04-04T14:08:46.000000Z | +38.017, +37.736 | 3.0 ML | manual """ # Helper functions. Only first argument might be None. Avoid # unorderable types by checking first shortcut on positive is None # also for the greater stuff (is confusing but correct) def _is_smaller(value_1, value_2): if value_1 is None or value_1 < value_2: return True return False def _is_smaller_or_equal(value_1, value_2): if value_1 is None or value_1 <= value_2: return True return False def _is_greater(value_1, value_2): if value_1 is None or value_1 <= value_2: return False return True def _is_greater_or_equal(value_1, value_2): if value_1 is None or value_1 < value_2: return False return True # Map the function to the operators. operator_map = {"<": _is_smaller, "<=": _is_smaller_or_equal, ">": _is_greater, ">=": _is_greater_or_equal} try: inverse = kwargs["inverse"] except KeyError: inverse = False events = list(self.events) for arg in args: try: key, operator, value = arg.split(" ", 2) except ValueError: msg = "%s is not a valid filter rule." % arg raise ValueError(msg) if key == "magnitude": temp_events = [] for event in events: if (event.magnitudes and event.magnitudes[0].mag and operator_map[operator]( event.magnitudes[0].mag, float(value))): temp_events.append(event) events = temp_events elif key in ("longitude", "latitude", "depth", "time"): temp_events = [] for event in events: if (event.origins and key in event.origins[0] and operator_map[operator]( event.origins[0].get(key), UTCDateTime(value) if key == 'time' else float(value))): temp_events.append(event) events = temp_events elif key in ('standard_error', 'azimuthal_gap', 'used_station_count', 'used_phase_count'): temp_events = [] for event in events: if (event.origins and event.origins[0].quality and key in event.origins[0].quality and operator_map[operator]( event.origins[0].quality.get(key), float(value))): temp_events.append(event) events = temp_events else: msg = "%s is not a valid filter key" % key raise ValueError(msg) if inverse: events = [ev for ev in self.events if ev not in events] return Catalog(events=events)
[docs] def copy(self): """ Returns a deepcopy of the Catalog object. :rtype: :class:`~obspy.core.stream.Catalog` :return: Copy of current catalog. .. rubric:: Examples 1. Create a Catalog and copy it >>> from obspy.core.event import read_events >>> cat = read_events() >>> cat2 = cat.copy() The two objects are not the same: >>> cat is cat2 False But they have equal data: >>> cat == cat2 True 2. The following example shows how to make an alias but not copy the data. Any changes on ``cat3`` would also change the contents of ``cat``. >>> cat3 = cat >>> cat is cat3 True >>> cat == cat3 True """ return copy.deepcopy(self)
[docs] def extend(self, event_list): """ Extends the current Catalog object with a list of Event objects. """ if isinstance(event_list, list): for _i in event_list: # Make sure each item in the list is a event. if not isinstance(_i, Event): msg = 'Extend only accepts a list of Event objects.' raise TypeError(msg) self.events.extend(event_list) elif isinstance(event_list, Catalog): self.events.extend(event_list.events) else: msg = 'Extend only supports a list of Event objects as argument.' raise TypeError(msg)
[docs] def write(self, filename, format, **kwargs): """ Saves catalog into a file. :type filename: str :param filename: The name of the file to write. :type format: str :param format: The file format to use (e.g. ``"QUAKEML"``). See the `Supported Formats`_ section below for a list of supported formats. :param kwargs: Additional keyword arguments passed to the underlying plugin's writer method. .. rubric:: Example >>> from obspy import read_events >>> catalog = read_events() >>> catalog.write("example.xml", format="QUAKEML") # doctest: +SKIP Writing single events into files with meaningful filenames can be done e.g. using event.id >>> for ev in catalog: # doctest: +SKIP ... filename = str(ev.resource_id) + ".xml" ... ev.write(filename, format="QUAKEML") # doctest: +SKIP .. rubric:: _`Supported Formats` Additional ObsPy modules extend the parameters of the :meth:`~obspy.core.event.Catalog.write` method. The following table summarizes all known formats with write capability currently available for ObsPy. Please refer to the `Linked Function Call`_ of each module for any extra options available. %s """ format = format.upper() try: # get format specific entry point format_ep = EVENT_ENTRY_POINTS_WRITE[format] # search writeFormat method for given entry point write_format = buffered_load_entry_point( format_ep.dist.key, 'obspy.plugin.event.%s' % (format_ep.name), 'writeFormat') except (IndexError, ImportError, KeyError): msg = "Writing format \"%s\" is not supported. Supported types: %s" raise ValueError(msg % (format, ', '.join(EVENT_ENTRY_POINTS_WRITE))) return write_format(self, filename, **kwargs)
[docs] def plot(self, projection='global', resolution='l', continent_fill_color='0.9', water_fill_color='1.0', label='magnitude', color='depth', colormap=None, show=True, outfile=None, method=None, fig=None, title=None, **kwargs): # @UnusedVariable """ Creates preview map of all events in current Catalog object. :type projection: str, optional :param projection: The map projection. Currently supported are: * ``"global"`` (Will plot the whole world.) * ``"ortho"`` (Will center around the mean lat/long.) * ``"local"`` (Will plot around local events) Defaults to "global" :type resolution: str, optional :param resolution: Resolution of the boundary database to use. Will be based directly to the basemap module. Possible values are: * ``"c"`` (crude) * ``"l"`` (low) * ``"i"`` (intermediate) * ``"h"`` (high) * ``"f"`` (full) Defaults to ``"l"`` :type continent_fill_color: Valid matplotlib color, optional :param continent_fill_color: Color of the continents. Defaults to ``"0.9"`` which is a light gray. :type water_fill_color: Valid matplotlib color, optional :param water_fill_color: Color of all water bodies. Defaults to ``"white"``. :type label: str, optional :param label: Events will be labelled based on the chosen property. Possible values are: * ``"magnitude"`` * ``None`` Defaults to ``"magnitude"`` :type color: str, optional :param color: The events will be color-coded based on the chosen property. Possible values are: * ``"date"`` * ``"depth"`` Defaults to ``"depth"`` :type colormap: str, any matplotlib colormap, optional :param colormap: The colormap for color-coding the events. The event with the smallest property will have the color of one end of the colormap and the event with the biggest property the color of the other end with all other events in between. Defaults to None which will use the default colormap for the date encoding and a colormap going from green over yellow to red for the depth encoding. :type show: bool :param show: Whether to show the figure after plotting or not. Can be used to do further customization of the plot before showing it. Has no effect if `outfile` is specified. :type outfile: str :param outfile: Output file path to directly save the resulting image (e.g. ``"/tmp/image.png"``). Overrides the ``show`` option, image will not be displayed interactively. The given path/filename is also used to automatically determine the output format. Supported file formats depend on your matplotlib backend. Most backends support png, pdf, ps, eps and svg. Defaults to ``None``. The figure is closed after saving it to file. :type method: str :param method: Method to use for plotting. Possible values are: * ``'basemap'`` to use the Basemap library * ``'cartopy'`` to use the Cartopy library * ``None`` to pick the best available library Defaults to ``None``. :type fig: :class:`matplotlib.figure.Figure` (or :class:`matplotlib.axes.Axes`) :param fig: Figure instance to reuse, returned from a previous inventory/catalog plot call with `method=basemap`. If a previous basemap plot is reused, any kwargs regarding the basemap plot setup will be ignored (i.e. `projection`, `resolution`, `continent_fill_color`, `water_fill_color`). Note that multiple plots using colorbars likely are problematic, but e.g. one station plot (without colorbar) and one event plot (with colorbar) together should work well. If an :class:`~matplotlib.axes.Axes` is supplied, the given axes is used to plot into and no colorbar will be produced. :type title: str :param title: Title above plot. If left ``None``, an automatic title will be generated. Set to ``""`` for no title. :returns: Figure instance with the plot. .. rubric:: Examples Mollweide projection for global overview: >>> from obspy import read_events >>> cat = read_events() >>> cat.plot() # doctest:+SKIP .. plot:: from obspy import read_events cat = read_events() cat.plot() Orthographic projection: >>> cat.plot(projection="ortho") # doctest:+SKIP .. plot:: from obspy import read_events cat = read_events() cat.plot(projection="ortho") Local (Albers equal area) projection: >>> cat.plot(projection="local") # doctest:+SKIP .. plot:: from obspy import read_events cat = read_events() cat.plot(projection="local") Combining a station and event plot (uses basemap): >>> from obspy import read_inventory, read_events >>> inv = read_inventory() >>> cat = read_events() >>> fig = inv.plot(method=basemap, show=False) # doctest:+SKIP >>> cat.plot(method=basemap, fig=fig) # doctest:+SKIP .. plot:: from obspy import read_inventory, read_events inv = read_inventory() cat = read_events() fig = inv.plot(show=False) cat.plot(fig=fig) """ from obspy.imaging.maps import plot_map, _plot_basemap_into_axes import matplotlib import matplotlib.pyplot as plt if color not in ('date', 'depth'): raise ValueError('Events can be color coded by date or depth. ' "'%s' is not supported." % (color,)) if label not in (None, 'magnitude', 'depth'): raise ValueError('Events can be labeled by magnitude or events can' ' not be labeled. ' "'%s' is not supported." % (label,)) # lat/lon coordinates, magnitudes, dates lats = [] lons = [] labels = [] mags = [] colors = [] times = [] for event in self: if not event.origins: msg = ("Event '%s' does not have an origin and will not be " "plotted." % str(event.resource_id)) warnings.warn(msg) continue if not event.magnitudes: msg = ("Event '%s' does not have a magnitude and will not be " "plotted." % str(event.resource_id)) warnings.warn(msg) continue origin = event.preferred_origin() or event.origins[0] lats.append(origin.latitude) lons.append(origin.longitude) times.append(origin.time) magnitude = event.preferred_magnitude() or event.magnitudes[0] mag = magnitude.mag mags.append(mag) labels.append((' %.1f' % mag) if mag and label == 'magnitude' else '') if color == 'date': c_ = origin.get('time') or np.nan else: c_ = (origin.get('depth') or np.nan) / 1e3 colors.append(c_) # Create the colormap for date based plotting. if colormap is None: colormap = obspy_sequential if title is None: if len(lons) > 1: # if we have a `None` in the origin time list it likely ends up # as min and/or max and causes problems.. times_ = np.ma.masked_equal(times, None).compressed() min_time = times_.min() max_time = times_.max() title = ( "{event_count} events ({start} to {end}) " "- Color codes {colorcode}, size the magnitude".format( event_count=len(self.events), start=min_time.strftime("%Y-%m-%d"), end=max_time.strftime("%Y-%m-%d"), colorcode="origin time" if color == "date" else "depth")) else: title = "Event at %s" % times[0].strftime("%Y-%m-%d") if color not in ("date", "depth"): msg = "Invalid option for 'color' parameter (%s)." % color raise ValueError(msg) min_size = 2 max_size = 30 min_size_ = min(mags) - 1 max_size_ = max(mags) + 1 if len(lons) > 1: frac = [(0.2 + (_i - min_size_)) / (max_size_ - min_size_) for _i in mags] size_plot = [(_i * (max_size - min_size)) ** 2 for _i in frac] else: size_plot = 15.0 ** 2 if isinstance(fig, matplotlib.axes.Axes): if method is not None and method != "basemap": msg = ("Plotting into an matplotlib.axes.Axes instance " "currently only implemented for `method='basemap'`.") raise NotImplementedError(msg) ax = fig fig = ax.figure _plot_basemap_into_axes( ax=ax, lons=lons, lats=lats, size=size_plot, color=colors, bmap=None, labels=labels, projection=projection, resolution=resolution, continent_fill_color=continent_fill_color, water_fill_color=water_fill_color, colormap=colormap, marker="o", title=title, show=False, **kwargs) else: fig = plot_map(method, lons, lats, size_plot, colors, labels, projection=projection, resolution=resolution, continent_fill_color=continent_fill_color, water_fill_color=water_fill_color, colormap=colormap, marker="o", title=title, show=False, fig=fig, **kwargs) if outfile: fig.savefig(outfile) plt.close(fig) else: if show: plt.show() return fig
@rlock @map_example_filename("pathname_or_url")
[docs]def read_events(pathname_or_url=None, format=None, **kwargs): """ Read event files into an ObsPy Catalog object. The :func:`~obspy.core.event.read_events` function opens either one or multiple event files given via file name or URL using the ``pathname_or_url`` attribute. :type pathname_or_url: str or StringIO.StringIO :param pathname_or_url: String containing a file name or a URL or a open file-like object. Wildcards are allowed for a file name. If this attribute is omitted, an example :class:`~obspy.core.event.Catalog` object will be returned. :type format: str :param format: Format of the file to read (e.g. ``"QUAKEML"``). See the `Supported Formats`_ section below for a list of supported formats. :rtype: :class:`~obspy.core.event.Catalog` :return: An ObsPy :class:`~obspy.core.event.Catalog` object. .. rubric:: _`Supported Formats` Additional ObsPy modules extend the functionality of the :func:`~obspy.core.event.read_events` function. The following table summarizes all known file formats currently supported by ObsPy. Please refer to the `Linked Function Call`_ of each module for any extra options available at the import stage. %s Next to the :func:`~obspy.core.event.read_events` function the :meth:`~obspy.core.event.Catalog.write` method of the returned :class:`~obspy.core.event.Catalog` object can be used to export the data to the file system. """ if pathname_or_url is None: # if no pathname or URL specified, return example catalog return _create_example_catalog() elif not isinstance(pathname_or_url, (str, native_str)): # not a string - we assume a file-like object try: # first try reading directly catalog = _read(pathname_or_url, format, **kwargs) except TypeError: # if this fails, create a temporary file which is read directly # from the file system pathname_or_url.seek(0) with NamedTemporaryFile() as fh: fh.write(pathname_or_url.read()) catalog = _read(fh.name, format, **kwargs) return catalog elif isinstance(pathname_or_url, bytes) and \ pathname_or_url.strip().startswith(b'<'): # XML string return _read(io.BytesIO(pathname_or_url), format, **kwargs) elif "://" in pathname_or_url[:10]: # URL # extract extension if any suffix = os.path.basename(pathname_or_url).partition('.')[2] or '.tmp' with NamedTemporaryFile(suffix=sanitize_filename(suffix)) as fh: download_to_file(url=pathname_or_url, filename_or_buffer=fh) catalog = _read(fh.name, format, **kwargs) return catalog else: pathname = pathname_or_url # File name(s) pathnames = sorted(glob.glob(pathname)) if not pathnames: # try to give more specific information why the stream is empty if glob.has_magic(pathname) and not glob.glob(pathname): raise Exception("No file matching file pattern: %s" % pathname) elif not glob.has_magic(pathname) and not os.path.isfile(pathname): raise IOError(2, "No such file or directory", pathname) catalog = _read(pathnames[0], format, **kwargs) if len(pathnames) > 1: for filename in pathnames[1:]: catalog.extend(_read(filename, format, **kwargs).events) ResourceIdentifier.bind_resource_ids() return catalog
@uncompress_file
[docs]def _read(filename, format=None, **kwargs): """ Reads a single event file into a ObsPy Catalog object. """ catalog, format = _read_from_plugin('event', filename, format=format, **kwargs) for event in catalog: event._format = format return catalog
[docs]def _create_example_catalog(): """ Create an example catalog. """ return read_events('/path/to/neries_events.xml')
if __name__ == '__main__': import doctest doctest.testmod(exclude_empty=True)