Merge pull request #1726 from obspy/custom_basemap_example

Tutorial: add example for custom basemap plot with Inventory/Catalog

misc/docs/source/tutorial/code_snippets/basemap_plot_custom.py

@@ -0,0 +1,36 @@
+from mpl_toolkits.basemap import Basemap
+import numpy as np
+import matplotlib.pyplot as plt
+
+from obspy import read_inventory, read_events
+
+# Set up a custom basemap, example is taken from basemap users' manual
+fig, ax = plt.subplots()
+
+# setup albers equal area conic basemap
+# lat_1 is first standard parallel.
+# lat_2 is second standard parallel.
+# lon_0, lat_0 is central point.
+m = Basemap(width=8000000, height=7000000,
+            resolution='c', projection='aea',
+            lat_1=40., lat_2=60, lon_0=35, lat_0=50, ax=ax)
+m.drawcoastlines()
+m.drawcountries()
+m.fillcontinents(color='wheat', lake_color='skyblue')
+# draw parallels and meridians.
+m.drawparallels(np.arange(-80., 81., 20.))
+m.drawmeridians(np.arange(-180., 181., 20.))
+m.drawmapboundary(fill_color='skyblue')
+ax.set_title("Albers Equal Area Projection")
+
+# we need to attach the basemap object to the figure, so that obspy knows about
+# it and reuses it
+fig.bmap = m
+
+# now let's plot some data on the custom basemap:
+inv = read_inventory()
+inv.plot(fig=fig, show=False)
+cat = read_events()
+cat.plot(fig=fig, show=False, title="", colorbar=False)
+
+plt.show()

misc/docs/source/tutorial/code_snippets/basemap_plot_with_beachballs.rst

@@ -1,9 +1,28 @@
-============================
-Basemap Plot with Beachballs
-============================
+=============
+Basemap Plots
+=============
 
-Basemap Plot of a Local Area
-============================
+Basemap Plot with Custom Projection Setup
+=========================================
+
+Simple Basemap plots of e.g. :class:`~obspy.core.inventory.inventory.Inventory`
+or :class:`~obspy.core.event.catalog.Catalog` objects can be performed with
+builtin methods, see e.g.
+:meth:`Inventory.plot() <obspy.core.inventory.inventory.Inventory.plot>` or
+:meth:`Catalog.plot() <obspy.core.event.catalog.Catalog.plot>`.
+
+For full control over the projection and map extent, a custom basemap can be
+set up (e.g. following the examples in the
+`basemap documentation <http://matplotlib.org/basemap/users/index.html>`_),
+and then be reused for plots of
+e.g. :class:`~obspy.core.inventory.inventory.Inventory` or
+:class:`~obspy.core.event.catalog.Catalog` objects:
+
+.. plot:: tutorial/code_snippets/basemap_plot_custom.py
+   :include-source:
+
+Basemap Plot of a Local Area with Beachballs
+============================================
 
 The following example shows how to plot beachballs into a basemap plot together
 with some stations. The example requires the basemap_ package (download_ site)
@@ -45,8 +64,8 @@ our SRTM data file (from CGIAR_) look like this::
 .. _plotmap_shaded.py: https://github.com/matplotlib/basemap/blob/master/examples/plotmap_shaded.py?raw=true
 
 
-Basemap Plot of the Globe
-=========================
+Basemap Plot of the Globe with Beachballs
+=========================================
 
 .. plot:: tutorial/code_snippets/basemap_plot_with_beachballs2.py
    :include-source: