Plotting tools#

This module contains functions to simplify the examples in the documentation, mostly plotting functions, but also to provide basic tools to quickly visualize data and results from this package.

covseisnet.plot.make_axis_symmetric(ax: Axes, axis: str = 'both') → None[source]#

Make the axis of a plot symmetric.

Given an axis, this function will set the limits of the axis to be symmetric around zero. This is useful to have a better visual representation of data that is symmetric around zero.

Parameters:

ax (Axes) -- The axis to modify.
axis (str) -- The axis to modify. Can be "both", "x", or "y".

Examples

Create a simple plot and make the x-axis symmetric:

import covseisnet as csn
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(-10, 10, 100)
y = np.random.randn(100)

fig, ax = plt.subplots(ncols=2, figsize=(6, 3))
ax[0].plot(x, y)
ax[1].plot(x, y)
ax[0].grid()
ax[1].grid()
csn.plot.make_axis_symmetric(ax[1], axis="both")
ax[0].set_title("Original axis")
ax[1].set_title("Symmetric axis")

covseisnet.plot.trace_and_spectrum(trace: Trace) → tuple[Figure, list[Axes]][source]#

Plot a trace and its spectrum side by side.

The spectrum is calculated with the scipy.fft.rfft() function, which assumes that the trace is real-valued and therefore only returns the positive frequencies.

Parameters:: trace (Trace) -- The trace to plot.
Returns:: ax (Axes)

Examples

Read a stream and plot the first trace and its spectrum:

import covseisnet as csn
stream = csn.read()
trace = stream[0]
csn.plot.trace_and_spectrum(trace)

covseisnet.plot.trace_and_spectrogram(trace: Trace, f_min: None | float = None, cmap: str = 'cividis', **kwargs: Any) → tuple[Figure, list[Axes]][source]#

Plot a trace and its spectrogram.

This function is deliberately simple and does not allow to customize the spectrogram plot. For more advanced plotting, you should consider creating a derived function.

Parameters:

trace (Trace) -- The trace to plot.
f_min (None or float) -- The minimum frequency to display. Frequencies below this value will be removed from the spectrogram.
cmap (str) -- The colormap to use for the spectrogram.
**kwargs -- Additional arguments to pass to calculate_spectrogram().

Examples

Read a stream and plot the first trace and its spectrogram:

import covseisnet as csn
stream = csn.read()
trace = stream[0]
csn.plot.trace_and_spectrogram(trace, window_duration=1)

covseisnet.plot.coherence(times, frequencies, coherence, f_min=None, ax=None, **kwargs) → tuple[Figure, Axes][source]#

Plot a coherence matrix.

This function is deliberately simple and does not allow to customize the coherence plot. For more advanced plotting, you should consider creating a derived function.

Parameters:

times (ndarray) -- The time axis of the coherence matrix.
frequencies (ndarray) -- The frequency axis of the coherence matrix.
coherence (ndarray) -- The coherence matrix.
f_min (float, optional) -- The minimum frequency to display. Frequencies below this value will be removed from the coherence matrix.
ax (Axes, optional) -- The axis to plot on. If not provided, a new figure will be created.
**kwargs -- Additional arguments passed to the pcolormesh method. By default, the shading is set to "nearest" and the colormap is set to "magma_r".

Returns:

ax (Axes)

covseisnet.plot.stream_and_coherence(stream: NetworkStream, times: ndarray, frequencies: ndarray, coherence: ndarray, f_min: float | None = None, trace_factor: float = 0.1, **kwargs: dict) → tuple[Figure, list[Axes]][source]#

Plot a stream of traces and the coherence matrix.

This function is deliberately simple and does not allow to customize the coherence plot. For more advanced plotting, you should consider creating a derived function.

Parameters:

stream (Stream) -- The stream to plot.
times (ndarray) -- The time axis of the coherence matrix.
frequencies (ndarray) -- The frequency axis of the coherence matrix.
coherence (ndarray) -- The coherence matrix.
f_min (float, optional) -- The minimum frequency to display. Frequencies below this value will be removed from the coherence matrix.
trace_factor (float, optional) -- The factor to multiply the traces by for display.
**kwargs -- Additional arguments passed to the pcolormesh method.

covseisnet.plot.plot_stream(stream: NetworkStream, trace_factor: float = 1, ax: Axes | None = None, **kwargs) → Axes[source]#

Plot a stream of traces.

This function is deliberately simple and does not allow to customize the trace plot. For more advanced plotting, you should consider creating a derived function.

Parameters:

stream (Stream) -- The stream to plot.
**kwargs -- Additional arguments passed to the plot method.

Returns:

ax (Axes)

covseisnet.plot.covariance_matrix_modulus_and_spectrum(covariance: CovarianceMatrix) → tuple[Figure, Axes][source]#

Plot the modulus of a covariance matrix and its spectrum.

This function plots the modulus of the covariance matrix and its eigenvalues in a single figure. The eigenvalues are normalized to sum to 1.

Parameters:: covariance (CovarianceMatrix) -- The covariance matrix to plot.
Returns:: ax (Axes)

Examples

Create a covariance matrix and plot its modulus and spectrum:

import covseisnet as csn
import numpy as np
np.random.seed(0)
c = np.random.randn(3, 3)
c = (c @ c.T) / 0.5
c = csn.covariance.CovarianceMatrix(c)
c.stats = [{"station": station} for station in "ABC"]
csn.plot.covariance_matrix_modulus_and_spectrum(c)

covseisnet.plot.dateticks(ax: Axes, locator: DateLocator | None = None) → None[source]#

Set date ticks on the x-axis of a plot.

Parameters:

ax (Axes) -- The axis to modify.
locator (DateLocator) -- The locator to use for the date ticks. This can be an instance of AutoDateLocator, DayLocator, etc. Check the documentation for more information.
formatter (DateFormatter) -- The formatter to use for the date ticks. This can be an instance of ConciseDateFormatter for example. Check the documentation for more information.

Examples

Create a simple plot with date ticks:

import covseisnet as csn
import numpy as np
import matplotlib.pyplot as plt

stream = csn.read()
trace = stream[0]

fig, ax = plt.subplots(nrows=2, figsize=(6, 3), constrained_layout=True)

ax[0].plot(trace.times(), trace.data)
ax[0].set_title("Time series with times in seconds")
ax[0].grid()
ax[0].set_xlabel("Time (seconds)")

ax[1].plot(trace.times("matplotlib"), trace.data)
ax[1].set_title("Time series with times in datetime")
ax[1].grid()
csn.plot.dateticks(ax[1])

covseisnet.plot.grid3d(grid, profile_coordinates=None, receiver_coordinates=None, label=None, **kwargs) → tuple[Figure, dict][source]#

Plot a three-dimensional grid of data.

This function plots the data of a three-dimensional grid in three different views: xy, xz, and zy. The grid data is plotted as a contour plot. In addition, the function can plot receiver coordinates, and a profile line can be highlighted.

Parameters:

grid (Grid3D or derived class) -- The grid to plot.
profile_coordinates (tuple, optional) -- The coordinates of the profile line to highlight. The profile line will be highlighted with dashed lines.
receiver_coordinates (tuple, optional) -- The coordinates of the receivers to plot. The receivers will be plotted as black squares.
label (str, optional) -- The label of the colorbar.
**kwargs -- Additional arguments passed to the contourf method.

Returns:

ax (dict) -- A dictionary with the axes of the plot. The keys are "xy", "xz", "zy", "cb", and ".". This is the output of the subplot_mosaic() function.

Examples

Create a simple grid and plot it:

import covseisnet as csn
import matplotlib.pyplot as plt
import numpy as np

# Create a random grid
grid = csn.spatial.Regular3DGrid(extent=(-10, 10, -10, 10, 0, 10), shape=(10, 10, 10))
grid[:] = grid.mesh[0] + grid.mesh[1] + grid.mesh[2]

# Show the grid
csn.plot.grid3d(
    grid,
    profile_coordinates=(0, 0, 0),
    receiver_coordinates=(0, 0, 0),
    label="Amplitude (dB)"
)
plt.show()

Plotting tools

Contents

Plotting tools#