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.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()

Plotting (seislib.plotting)

Plotting (`seislib.plotting`)