Plotting (seislib.plotting)

SeisLib provides support for plotting the results obtained from each of its modules, through the functions contained in seislib.plotting. seislib.plotting relies on CartoPy, and allows one to

  • Display geographic location of seismic receivers and epicenters

  • Plot inter-station (or epicenter-station) great-circle paths for which velocity measurements are available. These can also be colored according to the measured velocity

  • Display spatial variations in any physical parameter defined on unstructured blocks (e.g., equal-area grids)

  • Display Earth’s features (e.g., coastlines) in a very simple (high-level) fashion

  • Easily add inset axes and colorbars

  • Combine the above features to obtain high-quality figures.

seislib.plotting.plotting.add_earth_features(ax, scale='110m', oceans_color='aqua', lands_color='coral', edgecolor='k', lands_lw=0.5, oceans_lw=0.5, lakes_lw=0.5)

Adds natural features to a cartopy.mpl.geoaxes.GeoAxesSubplot, fetching data from the Natural Earth dataset

Parameters
axcartopy.mpl.geoaxes.GeoAxesSubplot
scale{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Default is ‘110m’

oceans_color, lands_colorstr

Color of oceans and continents in the map. They should be valid matplotlib colors or be part of cartopy.cfeature.COLORS. Defaults are ‘aqua’ and ‘coral’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. Passed to cartopy.feature.NaturalEarthFeature. Default is ‘k’ (black)

lands_lw, oceans_lw, lakes_lwfloat

Linewidths for lands, oceans, and lakes. Arguments passed to GeoAxesSubplot.add_feature

seislib.plotting.plotting.add_earth_features_GSHHS(ax, scale='auto', oceans_color='aqua', lands_color='coral', edgecolor='face')

Adds natural features to a cartopy.mpl.geoaxes.GeoAxesSubplot, fetching data from the GSHHS dataset

Parameters
axcartopy.mpl.geoaxes.GeoAxesSubplot
scale{‘auto’, ‘coarse’, ‘low’, ‘intermediate’, ‘high’, ‘full’}

Scale of the dataset, passed to cartopy.feature.GSHHSFeature. Default is ‘auto’

oceans_color, lands_colorstr

Color of oceans and continents in the map. They should be valid matplotlib colors or be part of cartopy.cfeature.COLORS. Defaults are ‘aqua’ and ‘coral’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. Passed to cartopy.feature.GSHHSFeature. Default is ‘face’ (the boundaries will have the same color as the continent)

seislib.plotting.plotting.add_inset_axis(axis, rect, polar=False)

Adds an axis inset

Parameters
axismatplotlib AxesSubplot

Instance of matplotlib.pyplot.subplot

rectlist or tuple of shape (4,)

[bottom, left, width, height] of the inset. Bottom and left coordinates are expressed with respect to axis

polarbool

If True, a polar plot is created. Default is False

Returns
Inset axis
seislib.plotting.plotting.colormesh(mesh, c, ax, **kwargs)

Adaptation of matplotlib.pyplot.pcolormesh to the (adaptive) equal-area grid

Parameters
meshndarray (n, 4)

Equal area grid, consisting of n blocks described by lat1, lat2, lon1, lon2

clist of ndarray (n,)

Values to plot in each grid cell

axcartopy.mpl.geoaxes.GeoAxesSubplot

Earth image on which c will be plotted

**kwargs

Additional keyword arguments passed to ax.pcolormesh

Returns
imgInstance of matplotlib.collections.QuadMesh
seislib.plotting.plotting.contour(mesh, c, ax, smoothing=None, **kwargs)

Adaptation of matplotlib.pyplot.contour to the (adaptive) equal area grid

Parameters
meshndarray (n, 4)

Equal area grid, consisting of n pixels described by lat1, lat2, lon1, lon2

clist of ndarray (n,)

Values to plot in each grid cell

axcartopy.mpl.geoaxes.GeoAxesSubplot

Earth image on which c will be plotted

smoothingfloat, optional

Value passed to scipy.ndimage.filters.gaussian_filter and used to obtain a smooth representation of c (default is None)

**kwargs

Additional keyword arguments passed to ax.contour

Returns
imgInstance of matplotlib.contour.QuadContourSet
seislib.plotting.plotting.contourf(mesh, c, ax, smoothing=None, **kwargs)

Adaptation of matplotlib.pyplot.contourf to the (adaptive) equal area grid.

Parameters
meshndarray (n, 4)

Equal area grid, consisting of n pixels described by lat1, lat2, lon1, lon2

clist of ndarray (n,)

Values to plot in each grid cell

axcartopy.mpl.geoaxes.GeoAxesSubplot

Earth image on which c will be plotted

smoothingfloat, optional

Value passed to scipy.ndimage.filters.gaussian_filter and used to obtain a smooth representation of c (default is None)

**kwargs

Additional keyword arguments passed to ax.contourf

Returns
imgInstance of matplotlib.contour.QuadContourSet
seislib.plotting.plotting.lower_threshold_projection(projection, thresh=1000.0, **kwargs)

Effective work around to get a higher-resolution curvature of the great-circle paths to be plotted in a given projection. This is useful when plotting the great-circle paths in a relatively small region.

Parameters
projectionclass

Should be one of the cartopy projection classes, e.g., cartopy.crs.Mercator

threshfloat

Smaller values achieve higher resolutions. Default is 1e3

Returns
Instance of the input (projection) class

Examples

>>> proj = lower_threshold_projection(cartopy.crs.Mercator, 
...                                   thresh=1e3)

Note that the cartopy.crs.Mercator was not initialized (i.e., there are no brackets after the word Mercator)

seislib.plotting.plotting.make_colorbar(ax, mappable, size='5%', pad='3%', **kwargs)

Prepares and attaches a colorbar to the GeoAxesSubplot

Parameters
axcartopy.mpl.geoaxes.GeoAxesSubplot
mappablematplotlib.cm.ScalarMappable
sizestr

Width of the colorbar, default is ‘5%’

padstr

Space between the colorbar and ax, default is ‘3%’

**kwargs

Additional keyword arguments passed to matplotlib.pyplot.colorbar

Returns
matplotlib.colorbar.Colorbar
seislib.plotting.plotting.plot_colored_rays(data_coords, c, ax=None, show=True, cmap=<matplotlib.colors.LinearSegmentedColormap object>, vmin=None, vmax=None, stations_color='k', oceans_color='lightgrey', lands_color='w', edgecolor='k', stations_alpha=None, paths_alpha=None, resolution='110m', projection='Mercator', map_boundaries=None, bound_map=True, paths_width=1, colorbar=True, cbar_dict={}, **kwargs)

Utility function to display the great-circle paths associated with pairs of data coordinates, colored according to their respective measurements

Parameters
data_coordsndarray of shape (n, 4)

Lat1, lon1, lat2, lon2 of the great-circle paths to be plotted

cndarray of shape (n)

Value associated with each pair of coordinates in data_coords

axcartopy.mpl.geoaxes.GeoAxesSubplot

If not None, c is plotted on the GeoAxesSubplot instance. Otherwise, a new figure and GeoAxesSubplot instance is created

showbool

If True (default), the map will be showed once generated. Otherwise a GeoAxesSubplot instance is returned

cmapstr or Colormap

If str, it should be a valid matplotlib.cm.colormap name (see matplotlib documentation). Otherwise, it should be the name of a colormap available in seislib.colormaps (see also the documentation at https://www.fabiocrameri.ch/colourmaps/)

vmin, vmaxfloat

Boundaries of the colormap. If None, the minimum and maximum values of c will be taken

stations_colorstr

Color of the receivers and of the great-circle paths (see matplotlib documentation for valid color names). Defaults are ‘r’ (red) and ‘k’ (black)

oceans_color, lands_colorstr

Color of oceans and lands. The arguments are ignored if ax is not None. Otherwise, they are passed to cartopy.feature.NaturalEarthFeature (to the argument ‘facecolor’). Defaults are ‘water’ and ‘land’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. The argument is ignored if ax is not None. Otherwise, it is passed to cartopy.feature.NaturalEarthFeature (to the argument ‘edgecolor’). Default is ‘k’ (black)

stations_alpha, paths_alphafloat, optional

Transparency of the stations and of the great-circle paths. Defaults are None and 0.3

paths_widthfloat

Linewidth of the great-circle paths

projectionstr

Name of the geographic projection used to create the GeoAxesSubplot. (Visit the cartopy website for a list of valid projection names.) If ax is not None, projection is ignored. Default is ‘Mercator’

resolution{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Valid arguments are ‘110m’, ‘50m’, ‘10m’. Default is ‘110m’. Ignored if ax is not None.

map_boundarieslist or tuple of floats, shape (4,), optional

Lonmin, lonmax, latmin, latmax (in degrees) defining the extent of the map

bound_mapbool

If True, the map boundaries will be automatically determined. Ignored if map_boundaries is not None

colorbarbool

If True (default), a colorbar associated with c is displayed on the side of the map

cbar_dictdict

Keyword arguments passed to matplotlib.colorbar.ColorbarBase

**kwargs

Additional keyword arguments passed to ax.plot

Returns
If show is True

None

Otherwise

GeoAxesSubplot instance together with an instance of matplotlib.colorbar.Colorbar (if colorbar is True)

seislib.plotting.plotting.plot_events(lat, lon, mag=None, ax=None, show=True, oceans_color='water', lands_color='land', edgecolor='k', projection='Mercator', resolution='110m', min_size=5, max_size=200, legend_markers=4, legend_dict={}, **kwargs)

Creates a map of epicenters

Parameters
lat, lonndarray of shape (n,)

Latitude and longitude of the epicenters

magndarray of shape(n,), optional

If not given, the size of each on the map will be constant

axcartopy.mpl.geoaxes.GeoAxesSubplot

If not None, the receivers are plotted on the GeoAxesSubplot instance. Otherwise, a new figure and GeoAxesSubplot instance is created

showbool

If True, the plot is shown. Otherwise, a GeoAxesSubplot instance is returned. Default is True

oceans_color, lands_colorstr

Color of oceans and lands. The arguments are ignored if ax is not None. Otherwise, they are passed to cartopy.feature.NaturalEarthFeature (to the argument ‘facecolor’). Defaults are ‘water’ and ‘land’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. The argument is ignored if ax is not None. Otherwise, it is passed to cartopy.feature.NaturalEarthFeature (to the argument ‘edgecolor’). Default is ‘k’ (black)

projectionstr

Name of the geographic projection used to create the GeoAxesSubplot. (Visit the cartopy website for a list of valid projection names.) If ax is not None, projection is ignored. Default is ‘Mercator’

resolution{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Default is ‘110m’

min_size, max_sizefloat, optional

Minimum and maximum size of the epicenters on the map. These are used to interpolate all magnitudes associated with each event, so as to scale them appropriately on the map. (The final “sizes” are passed to the argument s of matplotlib.pyplot.scatter.) If mag is None, these params are ignored

legend_markersint

Number of markers displayed in the legend. Ignored if s (size of the markers in matplotlib.pyplot.scatter) is passed. Only considered if mag is not None

legend_dictdict

Keyword arguments passed to matplotlib.pyplot.legend

**kwargs

Additional keyword arguments passed to matplotlib.pyplot.scatter

Returns
If show is True

None

Otherwise

ax, i.e. the GeoAxesSubplot

seislib.plotting.plotting.plot_map(mesh, c, ax=None, projection='Mercator', map_boundaries=None, bound_map=True, colorbar=True, show=True, style='colormesh', add_features=False, resolution='110m', cbar_dict={}, **kwargs)

Utility function to display the lateral variations of some quantity on a equal-area grid

Parameters
meshndarray, shape (n, 4)

Grid cells in seislib format, consisting of n pixels described by lat1, lat2, lon1, lon2 (in degrees)

cndarray, shape (n,)

Values associated with the grid cells (mesh)

axcartopy.mpl.geoaxes.GeoAxesSubplot

If not None, c is plotted on the GeoAxesSubplot instance. Otherwise, a new figure and GeoAxesSubplot instance is created

projectionstr

Name of the geographic projection used to create the GeoAxesSubplot. (Visit the cartopy website for a list of valid projection names.) If ax is not None, projection is ignored. Default is ‘Mercator’

map_boundarieslist or tuple of floats, shape (4,), optional

Lonmin, lonmax, latmin, latmax (in degrees) defining the extent of the map

bound_mapbool

If True, the map boundaries will be automatically determined. Ignored if map_boundaries is not None

colorbarbool

If True (default), a colorbar associated with c is displayed on the side of the map

showbool

If True (default), the map will be showed once generated

style{‘colormesh’, ‘contourf’, ‘contour’}

Possible options are ‘colormesh’, ‘contourf’, and ‘contour’, each corresponding to the homonymous method. Default is ‘colormesh’

add_featuresbool

If True, natural Earth features will be added to the GeoAxesSubplot. Default is False. If ax is None, it is automatically set to True

resolution{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Valid arguments are ‘110m’, ‘50m’, ‘10m’. Default is ‘110m’

cbar_dictdict

Keyword arguments passed to matplotlib.colorbar.ColorbarBase

**kwargs

Additional inputs passed to the ‘colormesh’, ‘contourf’, and ‘contour’ methods of SeismicTomography

Returns
If show is True

None

Otherwise

an instance of matplotlib.collections.QuadMesh, together with an instance of matplotlib.colorbar.Colorbar (if colorbar is True)

seislib.plotting.plotting.plot_rays(data_coords, ax=None, show=True, stations_color='r', paths_color='k', oceans_color='water', lands_color='land', edgecolor='k', stations_alpha=None, paths_alpha=0.3, projection='Mercator', resolution='110m', map_boundaries=None, bound_map=True, paths_width=0.2, **kwargs)

Utility function to display the great-circle paths associated with pairs of data coordinates

Parameters
data_coordsndarray of shape (n, 4)

Lat1, lon1, lat2, lon2 of the great-circle paths to be plotted

axcartopy.mpl.geoaxes.GeoAxesSubplot

If not None, c is plotted on the GeoAxesSubplot instance. Otherwise, a new figure and GeoAxesSubplot instance is created

showbool

If True (default), the map will be showed once generated. Otherwise a GeoAxesSubplot instance is returned

stations_color, paths_colorstr

Color of the receivers and of the great-circle paths (see matplotlib documentation for valid color names). Defaults are ‘r’ (red) and ‘k’ (black)

oceans_color, lands_colorstr

Color of oceans and lands. The arguments are ignored if ax is not None. Otherwise, they are passed to cartopy.feature.NaturalEarthFeature (to the argument ‘facecolor’). Defaults are ‘water’ and ‘land’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. The argument is ignored if ax is not None. Otherwise, it is passed to cartopy.feature.NaturalEarthFeature (to the argument ‘edgecolor’). Default is ‘k’ (black)

stations_alpha, paths_alphafloat, optional

Transparency of the stations and of the great-circle paths. Defaults are None and 0.3

paths_widthfloat

Linewidth of the great-circle paths

projectionstr

Name of the geographic projection used to create the GeoAxesSubplot. (Visit the cartopy website for a list of valid projection names.) If ax is not None, projection is ignored. Default is ‘Mercator’

resolution{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Valid arguments are ‘110m’, ‘50m’, ‘10m’. Default is ‘110m’. Ignored if ax is not None.

map_boundarieslist or tuple of floats, shape (4,), optional

Lonmin, lonmax, latmin, latmax (in degrees) defining the extent of the map

bound_mapbool

If True, the map boundaries will be automatically determined. Ignored if map_boundaries is not None

Returns
None if show is True. Otherwise a GeoAxesSubplot instance
seislib.plotting.plotting.plot_stations(stations, ax=None, show=True, oceans_color='water', lands_color='land', edgecolor='k', projection='Mercator', resolution='110m', color_by_network=True, legend_dict={}, **kwargs)

Creates a maps of seismic receivers

Parameters
stationsdict

Dictionary object containing stations information. This should structured so that each key corresponds to a station code ($network_code.$station_code) and each value is a tuple containing latitude and longitude of the station. For example:

{ net1.sta1 : (lat1, lon1),
  net1.sta2 : (lat2, lon2),
  net2.sta3 : (lat3, lon3)
  }
axcartopy.mpl.geoaxes.GeoAxesSubplot

If not None, the receivers are plotted on the GeoAxesSubplot instance. Otherwise, a new figure and GeoAxesSubplot instance is created

showbool

If True, the plot is shown. Otherwise, a GeoAxesSubplot instance is returned. Default is True

oceans_color, lands_colorstr

Color of oceans and lands. The arguments are ignored if ax is not None. Otherwise, they are passed to cartopy.feature.NaturalEarthFeature (to the argument ‘facecolor’). Defaults are ‘water’ and ‘land’

edgecolorstr

Color of the boundaries between, e.g., lakes and land. The argument is ignored if ax is not None. Otherwise, it is passed to cartopy.feature.NaturalEarthFeature (to the argument ‘edgecolor’). Default is ‘k’ (black)

projectionstr

Name of the geographic projection used to create the GeoAxesSubplot. (Visit the cartopy website for a list of valid projection names.) If ax is not None, projection is ignored. Default is ‘Mercator’

resolution{‘10m’, ‘50m’, ‘110m’}

Resolution of the Earth features displayed in the figure. Passed to cartopy.feature.NaturalEarthFeature. Default is ‘110m’

color_by_networkbool

If True, each seismic network will have a different color in the resulting map, and a legend will be displayed. Otherwise, all stations will have the same color. Default is True

legend_dictdict

Keyword arguments passed to matplotlib.pyplot.legend

kwargs :

Additional keyword arguments passed to matplotlib.pyplot.scatter

Returns
If show is True

None

Otherwise

ax, i.e. the GeoAxesSubplot

seislib.plotting.plotting.scientific_label(obj, precision)

Creates a scientific label approximating a real number in LaTex style

Parameters
objfloat

Number that must be represented

precisionint

Number of decimal digits in the resulting label

Returns
scientific_notationstr

Approximated number, e.g., r’5.000 times 10^{-6}’, arising from the function call scientific_label(5e-06, 3)

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-2, 2, 150)
>>> y = x**2 * 1e-5
>>> plt.plot(x, y)
>>> ticks = plt.gca().get_yticks()
>>> labels = [r'$%s$'%scientific_label(i, 1) for i in ticks]
>>> plt.yticks(ticks=ticks, labels=labels)
>>> plt.show()