mspasspy.graphics

class mspasspy.graphics.BasicSeismicPlotter(scale=1.0, normalize=False, title=None)[source]

Bases: ABC

Base class for MsPASS graphics objects used to visualize seismic data with the geometry of time as the x axis. That produces graphics with seismograms horizontal as opposed to record sections where the time axis is y.

This base class should never be instantiated by itself. It contains methods that can be reused by different implementations in a class hierarchy.

bottomup()[source]

Restore (or force) default ensemble plot order of bottup upward.

abstract plot()[source]

Alll concrete implementations must implement this method to do some plotting.

set_topdown()[source]

Call this method to have datat plotted from top down. Default plots ensemble member 0 at the bottom of the plot with successive members plotted in units of 1.0 above the last. When this is called the order is reversed.

topdown()[source]

Switch to mode of plotting ensembles from the top downward from default of bottum upward.

class mspasspy.graphics.LargeEnsemblePlotter(scale=0.5, normalize=True, title=None, members_per_frame=20)[source]

Bases: SeismicPlotter

This is a special class to handle ensembles. It forces a solution that can be mysterous for a naive use of the more general SeismicPlotter. That is, with a large ensemble the plot can easily come out a black image when the number of ensemble members are of the order of 1/10 or more of the number of pixels defining the y axis. The way thsi subclass addresses that is by forcing the following:

  1. It normally produces multiple plots to display data in blocks. sac users can think of this like theh “perplot” argument used in the sac ppk function.

  2. It defaults to wiggle trace only plots to improve performance.

  3. It defaults to automatic scaling assuming that for many inputs something always needs to be scaled

  4. It will only accept ensemble objects

Note since this is a subclass of SeismicPlotter, Seismogram enembles will be plotted in three different figure windows.

Be warned large ensembles can produce a very large number of plots with a single call to the plot method of this class. With interactive use you may need to click on a lot of windows to see all the data and for notebooks you can quickly create a huge notebook. All plotting for large data sets must be done with caution.

plot(ens, skip_the_dead=True)[source]

Plots esembles in groups of size defined by the instance.

This plot method overrides the plot method of SeismicPlotter but actually uses the same functions to make the plots. It does so using a trick to run the “super” function. When run interactively the function will block with each frame until the window(s) is(are) closed. In a notebook the frames will all be rendered sequentially into the notebook.

As far as I can tell a limitation of the matplotlib is that to allow an event loop for zoom and pan operatios on the plot the window has to be closed in interactive mode. It would be nice to not have to have the window have to pop up for each frame but I (glp) can’t see how to do that - it may be impossible without a major rewrite.

Note if the input ensemble is marked dead or has no live members a informational message will be “printed” (print staement) and nothing will be plotted.

Parameters:

  • ens (Must be either a TimeSeriesEnsemble of SeismogramEnsemle or the method will throw a TypeError exception.) – Ensemble to be plotted

  • skip_the_dead – Boolean controllng how dead data are handed. When True (default) dead data will be silently skippped. When False all dead data will create an empty plot cell in the position of the body.

class mspasspy.graphics.SectionPlotter(scale=1.0, normalize=False, title=None)[source]

Bases: object

This class was designed to plot data in a seismic reflection style display. That means time is the y axis but runs in a reverse direction and traces are equally spaced along the x axis. The data can be plotted as simple wiggle traces, wiggle trace variable area, an image format, and a wiggletrace variable area plot overlaying an image plot.

The object itself only defines the style of plot to be produced along with other assorted plot parameters. The plot method can be called on any mspass data object to produce a graphic display. TimeSeries data produce a frame with one seismogram plotted. Seismogram data will produce a one frame display with the 3 components arranged in component order from left to right. TimeSeriesEnsembles produce conventional reflection style sections with the data displayed from left to right in whatever order the ensemble is sorted to. SeismogramEnsembles are the only type that create multiple windows. That is, each component is displayed in a different window. The display can be understood as a conversion of a SeismogramEnsemble to a set of 3 TimeSeriesEnsembles that are displayed in 3 windows. The component can be deduced only from the title string with has :0, :1, and :2 appended to it to denote components 0, 1, and 2 respectively.

The plots produced by this object are simple ones for display only. The concept is that fancier tools for gui interaction like a trace editor be created as children of this base class.

change_style(newstyle, fill_color='k', color_map='seismic')[source]

Use this method to change the plot style. Options are described below. Some parameter combinations are illegal and will result in a RuntimeError if used. The illegal combos are listed below for each style.

Parameters:

newstyle –

This is the primary switch for this method and is used to define the style of plot that will be produced. The allowed values for this string are listed below along with restrictions (when they exist) on related parameters.

wtva - wiggle trace variable area. That means a wiggle traced with

the positive quadrants colored by the color defined by the fill_color parameter. If fill_color is passed as None a RuntimeError will be thrown.

img - data are displayed as an image with the color_map parameter

defining the matplotlib color map used to map amplitudes into a given color. Note as with wtva the data are presumed to be scaled to be of order 1. color_map must not be None, which it can be if the plot was changed from a previous style like wtva, or a RuntimeError exception will be thrown.

wtvaimg is like wtva but the wtva plot is drawn on top of an

image plot. Since this is the union of wtva and img a RuntimeError exception will be throw if either color_map or fill_color are null.

wt will produce a standard line graph of each input as a

black line (that feature is currently frozen). color_map and fill_color are ignored for this style so no exceptions should occur when the method is called with this value of newstyle.

plot(d)[source]

Call this method to plot any data using the current style setup and any details defined by public attributes.

Parameters:

d – is the data to be plotted. It can be any of the following: TimeSeries, Seismogram, TimeSeriesEnsemble, or SeismogramEnsemble. If d is any other type the method will throw a RuntimeError exception.

Returns:

an array of one or 3 (only for SeismogramEnsemble dat) matplotlib.pylot.gcf() plot handle(s).

Return type:

The plot handle is what matplotlib.plt calls a gcf. It is the return of plt.gcf() and can be used to alter some properties of the figure. See matplotlib documentation.

class mspasspy.graphics.SeismicPlotter(scale=1.0, normalize=False, title=None, style='wtvaimg')[source]

Bases: BasicSeismicPlotter

SeismicPlotter is used to plot mspass data objects in the seismology convention with time as the x axis. Use SectionPlotter to plot data in the seismic reflection convention with time on the y axis and oriented backward (increasing downward).

Four types of plots are supported: wiggle trace, wiggle trace variable area (i.e. filled on positive peaks), image plots, and colored wiggle trace variable area (wtva overlays an image display). Ensembles of Seismogram objects (SeismogramEnsemble object) are plotted in three windows that will appear as Figure 0, Figure 1, and Figure 2. All other object are displayed in a single window. Default display order for ensembles is fill in ensemble order from the bottom up. Use the topdown() method to switch to reverse order.

This is a simple plotter that just generates a basic graphic. The design idea is to use this as a base class for more advanced graphics uses like a trace editor or generic picker. The plot object must be created before any plots can be generated. Any optional changes to the plot behavior, most commonly calls to the change_style method, should be done before calling plot.

change_style(newstyle, fill_color='k', color_map='seismic')[source]

Use this method to change the plot style. Options are described below. Some parameter combinations are illegal and will result in a RuntimeError if used. The illegal combos are listed below for each style.

Parameters:

newstyle –

This is the primary switch for this method and is used to define the style of plot that will be produced. The allowed values for this string are listed below along with restrictions (when they exist) on related parameters.

wtva - wiggle trace variable area. That means a wiggle traced with

the positive quadrants colored by the color defined by the fill_color parameter. If fill_color is passed as None a RuntimeError will be thrown.

img - data are displayed as an image with the color_map parameter

defining the matplotlib color map used to map amplitudes into a given color. Note as with wtva the data are presumed to be scaled to be of order 1. color_map must not be None, which it can be if the plot was changed from a previous style like wtva, or a RuntimeError exception will be thrown.

wtvaimg is like wtva but the wtva plot is drawn on top of an

image plot. Since this is the union of wtva and img a RuntimeError exception will be throw if either color_map or fill_color are null.

wt will produce a standard line graph of each input as a

black line (that feature is currently frozen). color_map and fill_color are ignored for this style so no exceptions should occur when the method is called with this value of newstyle.

get_3Censemble_gcf() → tuple[source]

Returns the matplotlb figure handles for handlng SeismogramEnsemble data. This plotter draws 3c data in three different figure handles with number tags 0, 1, and 2 for each component. Useful method mainly for subclasses of this class.

get_plot_gcf()[source]

Returns the matplotlib figure handle of the canvas used for all plots but that for a SeismogramEnsemble. Useful only for subclasses that need to manipulate the handle.

plot(d)[source]

Alll concrete implementations must implement this method to do some plotting.

mspasspy.graphics.image_raw(section, t0, dt, ranges=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, aspect=None, vmin=None, vmax=None)[source]

Plot a numpy 2D array (matrix) in an image format. This type of plot has two uses: (1) large numbers of spatially coherent signals (as in a conventional seismic reflection) are more clearly displayed this way than as wiggles, and (2) this function can be called immediately following a call to wtva_raw to produce an section with variable area wiggle trace data shown on top of the an image representation of the data data (note for dense data it is usually necessary to decimate the data on the column axis to make a clean plot - functions to make such plots need a decimate parameter). This is the low level function to make such plots. It is directly comparable to wtva_raw.

This function was taken directly from the fatiando a terra 0.5 package. The current web site is https://www.fatiando.org/ and apparently the code we use here has been depricated by that group. This function is unaltered from the original found on github for the 0.5 version. Only the documentation was changed to clarify this ancestory. We also changed the name from seismic_image to image_raw to mesh more cleanly with mspass as the name better reflects the functions use.

Parameters:

  • section2D array

    matrix of traces (first dimension time, second dimension traces)

  • t0float

    time of first sample (added for mspass - needed for passive data)

  • dtfloat

    sample rate in seconds

  • ranges(x1, x2)

    min and max horizontal coordinate values (default trace number)

  • cmapcolormap

    color map to be used. (see plt.cm module)

  • aspectfloat

    matplotlib imshow aspect parameter, ratio between axes

  • vmin, vmaxfloat

    min and max values for imshow

mspasspy.graphics.imageplot(d, ranges=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, aspect=None, vmin=None, vmax=None, title=None)[source]

Image plotter for mspass ensemble objects.

mspasspy.graphics.seis2nparray(d)[source]
mspasspy.graphics.ts2nparray(d)[source]
mspasspy.graphics.tse2nparray(ens)[source]
mspasspy.graphics.wtva_raw(section, t0, dt, ranges=None, scale=1.0, color='k', normalize=False)[source]

Plot a numpy 2D array (matrix) in a wiggle trace, variable area format as used in paper seismic section displays. This is the low level function that displays a ensemble of scalar data cast into a matrix with the rows as time and the columns as just trace number. This function is called by the ensemble plotters. For scalar data it is called one but for 3C data 3 windows are created with this function called 3 times.

This function was taken directly from the fatiando a terra 0.5 package. The current web site is https://www.fatiando.org/ and apparently the code we use here has been depricated by that group. This function is unaltered from the original found on github for the 0.5 version. Only the documentation was changed to clarify this ancestory. We also changed the name from seismic_wiggle to wtva_raw to mesh more cleanly with mspass as the name better reflects the functions use.

Additional changes:

Pavlis Aug 27, 2020

Added a test that if color was a None only the wiggles will be drawn (i.e. no shading)

Parameters:

  • section2D array

    matrix of traces (first dimension time, second dimension traces)

  • t0float

    time of first sample (added for mspass - needed for passive data)

  • dtfloat

    sample rate in seconds

  • ranges(x1, x2)

    min and max horizontal values (default trace number)

  • scalefloat

    scale factor multiplied by the section values before plotting

  • colortuple of strings

    Color for filling the wiggle, positive and negative lobes. If None draw only wiggle traces

  • normalize :

    True to normalizes all trace in the section using global max/min data will be in the range (-0.5, 0.5) zero centered

Warning

Slow for more than 200 traces, in this case decimate your data or use image_raw.

mspasspy.graphics.wtvaplot(d, ranges=None, scale=1.0, fill_color='k', normalize=False, cmap=None, title=None)[source]

Wiggle trace variable area plotter for mspass ensemble objects.