viscid.plot.vpyplot module

Convenience module for making matplotlib plots

Your best friend in this module is the plot() function, but the best reference for all quirky options is plot2d_field().

Note

You can’t set rc parameters for this module!

viscid.plot.vpyplot.apply_labels(labels=None, colors=None, ax=None, magnet=(0.5, 0.75), magnetcoords=u'axes fraction', padding=None, paddingcoords=u'offset points', choices=u'00:02:20:22', n_candidates=32, ignore_filling=False, spacing=u'linear', _debug=False, **kwargs)[source]

Apply labels directly to series in liu of a legend

The choices offsets are as follows:

---------------------
|  02  |  12  | 22  |
|-------------------|
|  01  |  XX  | 21  |
|-------------------|
|  00  |  10  | 20  |
---------------------
Parameters:
  • labels (sequence) – Optional sequence of labels to override the labels already in the data series
  • colors (str, sequence) – color as hex string, list of hex strings to color each label, or an Nx4 ndarray of rgba values for N labels
  • ax (matplotlib.axis) – axis; defaults to plt.gca()
  • magnet (tuple) – prefer positions that are closer to the magnet
  • magnetcoords (str) – ‘offset pixels’, ‘offset points’ or ‘axes fraction’
  • padding (tuple) – padding for text in the (x, y) directions
  • paddingcoords (str) – ‘offset pixels’, ‘offset points’ or ‘axes fraction’
  • choices (str) – colon separated list of possible label positions relative to the data values. The positions are summarized above.
  • alpha (float) – alpha channel (opacity) of label text. Defaults to 1.0 to make text visible. Set to None to use the underlying alpha from the handle’s color.
  • n_candidates (int) – number of potential label locations to consider for each data series.
  • ignore_filling (bool) – if True, then assume it’s ok to place labels inside paths that are filled with color
  • spacing (str) – one of ‘linear’ or ‘random’ to specify how far apart candidate locations are spaced along path segments
  • _debug (bool) – Mark up all possible label locations
  • **kwargs – passed to plt.annotate
Returns:

annotation objects
Return type:

List
viscid.plot.vpyplot.auto_adjust_subplots(fig=None, tight_layout=True, subplot_params=None)[source]

Wrapper to adjust subplots w/ tight_layout remembering axes lims

Parameters:
  • fig (Figure) – a matplotlib figure
  • tight_layout (bool, dict) – flag for whether or not to apply a tight layout. If a dict, then it’s unpacked into plt.tight_layout(…)
  • subplot_params (dict) – unpacked into fig.subplots_adjust(…)
Returns:

keyword arguments for fig.subplots_adjust that describe

the current figure after all adjustments are made
Return type:

dict
viscid.plot.vpyplot.get_current_colorcycle()[source]
viscid.plot.vpyplot.interact(stack_depth=0, **kwargs)[source]
viscid.plot.vpyplot.plot(fld, selection=Ellipsis, force_cartesian=False, **kwargs)[source]

Plot a field by dispatching to the most appropiate funciton

  • If fld has 1 spatial dimensions, call plot1d_field(fld[selection], **kwargs)()
  • If fld has 2 spatial dimensions, call plot2d_field(fld[selection], **kwargs)()
  • If fld is 2-D and has spherical coordinates (as is the case for ionospheric fields), try to use plot2d_mapfield() which uses basemap to make its axes.
Parameters:
  • fld (Field) – Some Field
  • selection (optional) – something that describes a field slice
  • force_cartesian (bool) – if false, then spherical plots will use plot_mapfield
  • **kwargs – Passed on to plotting function
Returns:

(plot, colorbar)

plot: matplotlib plot object colorbar: matplotlib colorbar object
Return type:

tuple

See also

Note

Field slices are done using “slice_reduce”, meaning extra dimensions are reduced out.

Raises:
  • TypeError – Description
  • ValueError – Description
viscid.plot.vpyplot.plot1d_field(fld, ax=None, plot_opts=None, **plot_kwargs)[source]

Plot a 1D Field using lines

Parameters:
  • ax (matplotlib axis, optional) – Plot in a specific axis object
  • plot_opts (str, optional) – plot options
  • **plot_kwargs (str, optional) – plot options

See also

viscid.plot.vpyplot.plot2d_field(fld, ax=None, plot_opts=None, **plot_kwargs)[source]

Plot a 2D Field using pcolormesh, contour, etc.

Parameters:
  • ax (matplotlib axis, optional) – Plot in a specific axis object
  • plot_opts (str, optional) – plot options
  • **plot_kwargs (str, optional) – plot options
Returns:

(plot_object, colorbar_object)

See also

viscid.plot.vpyplot.plot2d_line(line, scalars=None, **kwargs)[source]
viscid.plot.vpyplot.plot2d_lines(lines, scalars=None, symdir='', ax=None, show=False, flip_plot=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker=None, colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)[source]

Plot a list of lines in 2D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • symdir (str) – direction perpendiclar to plane; one of ‘xyz’
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • flip_plot (bool) – flips x and y axes on the plot
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to matplotlib.collections.LineCollection. Note that LineCollection only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar. Use colors=zloc to color vertices with out-of-plane position.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to matplotlib.collections.LineCollection
Raises:

ValueError – If a 2D plane can’t be determined
Returns:

a LineCollection
viscid.plot.vpyplot.plot2d_mapfield(fld, ax=None, plot_opts=None, **plot_kwargs)[source]

Plot data on a map projection of a sphere

The default projection is polar, but any other basemap projection can be used.

Parameters:
  • ax (matplotlib axis, optional) – Plot in a specific axis object
  • plot_opts (str, optional) – plot options
  • **plot_kwargs (str, optional) – plot options
Returns:

(plot_object, colorbar_object)

Note

Parameters are in degrees, but if the projection is ‘polar’, then the plot is actually made in radians, which is important if you want to annotate a plot.

See also

viscid.plot.vpyplot.plot2d_quiver(fld, step=1, ax=None, axis='none', equal=False, **kwargs)[source]

Put quivers on a 2D plot

The quivers will be plotted in the 2D plane of fld, so if fld is 3D, then one and only one dimenstion must have shape 1.

Note

There are some edge cases where step doesn’t work.

Parameters:
  • fld (VectorField) – 2.5-D Vector field to plot
  • step (int) – only quiver every Nth grid cell. Can also be a list of ints to specify x & y downscaling separatly
  • **kwargs – passed to matplotlpb.pyplot.quiver()
Raises:
  • TypeError – vector field check
  • ValueError – 2d field check
Returns:

result of matplotlpb.pyplot.quiver()
viscid.plot.vpyplot.plot3d_line(line, scalars=None, **kwargs)[source]
viscid.plot.vpyplot.plot3d_lines(lines, scalars=None, ax=None, show=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker='', colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)[source]

Plot a list of lines in 3D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to mpl_toolkits.mplot3d.art3d.Line3DCollection. Note that this only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to mpl_toolkits.mplot3d.art3d.Line3DCollection
Returns:

Line3DCollection
Return type:

TYPE
viscid.plot.vpyplot.plot_earth(plane_spec, ax=None, scale=1.0, rot=0, daycol='w', nightcol='k', crd_system='gse', zorder=10, axis=None)[source]

Plot a black and white Earth to show sunward direction

Parameters:
  • plane_spec – Specifies the plane for determining sunlit portion. This can be a viscid.field.Field object to try to auto-discover the plane and crd_system, or it can be a string like “y=0”.
  • axis (matplotlib Axis) – axis on which to plot
  • scale (float, optional) – scale of earth
  • rot (float, optional) – Rotation of day/night side… I forget all the details :(
  • daycol (str, optional) – color of dayside (matplotlib format)
  • nightcol (str, optional) – color of nightside (matplotlib format)
  • crd_system (str, optional) – ‘mhd’ or ‘gse’, can usually be deduced from plane_spec if it’s a Field instance.
viscid.plot.vpyplot.plot_iono(fld, *args, **kwargs)[source]

Wrapper for easier annotated ionosphere plots

Parameters:
  • fld (Field) – Some spherical field
  • **kwargs – Consumed, or passed to plot2d_mapfield()
Keyword Arugments:
scale (float): scale fld by some scalar annotations (str): ‘pot’ to annotate min/max/cpcp units (str): units for annotation values hemisphere (str): ‘north’ or ‘south’ fontsize (int): point of font titlescale (float): scale fontsize of title by this much title (str): title for the plot
Returns:(plot_object, colorbar_object)

See also

Raises:ValueError – on bad hemisphere
viscid.plot.vpyplot.plot_line(line, scalars=None, **kwargs)
viscid.plot.vpyplot.plot_line2d(line, scalars=None, **kwargs)
viscid.plot.vpyplot.plot_line3d(line, scalars=None, **kwargs)
viscid.plot.vpyplot.plot_lines(lines, scalars=None, ax=None, show=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker='', colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)

Plot a list of lines in 3D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to mpl_toolkits.mplot3d.art3d.Line3DCollection. Note that this only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to mpl_toolkits.mplot3d.art3d.Line3DCollection
Returns:

Line3DCollection
Return type:

TYPE
viscid.plot.vpyplot.plot_lines2d(lines, scalars=None, symdir='', ax=None, show=False, flip_plot=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker=None, colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)

Plot a list of lines in 2D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • symdir (str) – direction perpendiclar to plane; one of ‘xyz’
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • flip_plot (bool) – flips x and y axes on the plot
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to matplotlib.collections.LineCollection. Note that LineCollection only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar. Use colors=zloc to color vertices with out-of-plane position.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to matplotlib.collections.LineCollection
Raises:

ValueError – If a 2D plane can’t be determined
Returns:

a LineCollection
viscid.plot.vpyplot.plot_lines3d(lines, scalars=None, ax=None, show=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker='', colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)

Plot a list of lines in 3D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to mpl_toolkits.mplot3d.art3d.Line3DCollection. Note that this only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to mpl_toolkits.mplot3d.art3d.Line3DCollection
Returns:

Line3DCollection
Return type:

TYPE
viscid.plot.vpyplot.plot_opts_to_kwargs(plot_opts, plot_kwargs)[source]

Turn plot options from string to items in plot_kwargs

The Reason for this to to be able to specify arbitrary plotting kwargs from the command line

Parameters:
  • plot_opts (str) – plot kwargs as string
  • plot_kwargs (dict) – kwargs to be popped by hand or passed to plotting function
Returns:

None, the plot_opts are stuffed into plot_kwargs
viscid.plot.vpyplot.plot_streamlines(lines, scalars=None, ax=None, show=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker='', colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)

Plot a list of lines in 3D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to mpl_toolkits.mplot3d.art3d.Line3DCollection. Note that this only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to mpl_toolkits.mplot3d.art3d.Line3DCollection
Returns:

Line3DCollection
Return type:

TYPE
viscid.plot.vpyplot.plot_streamlines2d(lines, scalars=None, symdir='', ax=None, show=False, flip_plot=False, subsample=2, pts_interp='linear', scalar_interp='linear', marker=None, colors=None, marker_kwargs=None, axis='none', equal=False, **kwargs)

Plot a list of lines in 2D

Parameters:
  • lines (list) – list of 3xN ndarrays describing N xyz points along a line
  • scalars (list, ndarray) – a bunch of floats, rgb tuples, or ‘#0000ff’ colors. These can be given as one per line, or one per vertex. See viscid.vutil.prepare_lines() for more info.
  • symdir (str) – direction perpendiclar to plane; one of ‘xyz’
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool) – call plt.show when finished?
  • flip_plot (bool) – flips x and y axes on the plot
  • subsample (int) – Factor for resampling the number of vertices. If you are plotting a line where you want the color or line width to change along the line to show data, you will want subsample > 2 to oversample the number of segments by a factor of 2. Otherwise, the colors will be off by half a line segment (due to limitations in matplotlib). To undersample the lines, you can use 0 < subsample < 1.
  • pts_interp (str) – What kind of interpolation to use for vertices if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • scalar_interp (str) – What kind of interpolation to use for scalars if subsample > 0. Must be a value recognized by scipy.interpolate.interp1d().
  • marker (str) – if given, plot the vertices using plt.scatter
  • colors – overrides scalar to color mapping and is passed to matplotlib.collections.LineCollection. Note that LineCollection only accepts rgba tuples (ie, no generic strings). To give colors using one or more hex strings, use scalars=’#0f0f0f’ or similar. Use colors=zloc to color vertices with out-of-plane position.
  • marker_kwargs (dict) – additional kwargs for plt.scatter
  • **kwargs – passed to matplotlib.collections.LineCollection
Raises:

ValueError – If a 2D plane can’t be determined
Returns:

a LineCollection
viscid.plot.vpyplot.scatter_2d(points, c='k', symdir='', flip_plot=False, ax=None, show=False, axis='none', equal=False, **kwargs)[source]

Plot scattered points on a matplotlib 3d plot

Parameters:
  • points – something shaped 3xN for N points, where 3 are the xyz cartesian directions in that order
  • c (str, optional) – color (in matplotlib format)
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool, optional) – show
  • kwargs – passed along to plt.statter()
viscid.plot.vpyplot.scatter_3d(points, c='k', ax=None, show=False, axis='none', equal=False, **kwargs)[source]

Plot scattered points on a matplotlib 3d plot

Parameters:
  • points – something shaped 3xN for N points, where 3 are the xyz cartesian directions in that order
  • c (str, optional) – color (in matplotlib format)
  • ax (matplotlib Axis, optional) – axis on which to plot (should be a 3d axis)
  • show (bool, optional) – show
  • kwargs – passed along to plt.statter()
viscid.plot.vpyplot.show_cmap(cmap=None, size=1, aspect=8)[source]
viscid.plot.vpyplot.show_colorcycle(pal=None, size=1)[source]

Plot the values in a color palette as a horizontal array.

viscid.plot.vpyplot.streamplot(fld, ax=None, axis='none', equal=False, **kwargs)[source]

Plot 2D streamlines with matplotlib.pyplot.streamplot()

Parameters:
  • fld (VectorField) – Some 2.5-D Vector Field
  • **kwargs – passed to matplotlib.pyplot.streamplot()
Raises:
  • TypeError – vector field check
  • ValueError – 2d field check
Returns:

result of matplotlib.pyplot.streamplot()
viscid.plot.vpyplot.subplot2grid(*args, **kwargs)[source]
viscid.plot.vpyplot.tighten(**kwargs)[source]

Calls matplotlib.pyplot.tight_layout(**kwargs)