Plotting

tplot function

All plotting is called through the “tplot()” function. If you’d like to customize how you plots are displayed, it is assume that you have set them up prior to calling this function.

pytplot.tplot(name, trange=None, var_label=None, slice=False, combine_axes=True, nb=False, save_file=None, gui=False, qt=False, bokeh=False, save_png=None, display=True, testing=False, extra_functions=[], extra_function_args=[], vert_spacing=None, pos_2d=False, pos_3d=False, exec_qt=True, window_name='Plot', interactive=False, xsize=None, ysize=None, save_eps='', save_svg='', save_pdf='', save_jpeg='', dpi=None, fig=None, axis=None, pseudo_plot_num=None, second_axis_size=0.0, return_plot_objects=False)

This is the function used to display the tplot variables stored in memory. It is a wrapper that calls a matplotlib-specific version of tplot.

Parameters:

• name (str or list of str, required) – List of tplot variables that will be plotted. If this is empty, nothing will be plotted.

• trange (list of string or float, optional) – If set, this time range will be used, temporarily overriding any previous xlim or timespan calls

• var_label (str, optional) – The name of the tplot variable you would like as a second x axis.

• xsize (float, optional) – Plot size in the horizontal direction (in inches)

• ysize (float, optional) – Plot size in the vertical direction (in inches)

• dpi (float, optional) – The resolution of the plot in dots per inch

• save_png (str, optional) – A full file name and path. If this option is set, the plot will be automatically saved to the file name provided in a PNG format.

• save_eps (str, optional) – A full file name and path. If this option is set, the plot will be automatically saved to the file name provided in a EPS format.

• save_jpeg (str, optional) – A full file name and path. If this option is set, the plot will be automatically saved to the file name provided in a JPEG format.

• save_pdf (str, optional) – A full file name and path. If this option is set, the plot will be automatically saved to the file name provided in a PDF format.

• save_svg (str, optional) – A full file name and path. If this option is set, the plot will be automatically saved to the file name provided in a SVG format.

• display (bool, optional) – If True, then this function will display the plotted tplot variables. Necessary to make this optional so we can avoid it in a headless server environment.

• return_plot_objects (bool, optional) – If true, returns the matplotlib fig and axes objects for further manipulation.

Returns:

Returns matplotlib fig and axes objects, if return_plot_objects==True

Return type:

Any

Examples

>>> #Plot a single line in bokeh
>>> import pyspedas
>>> x_data = [2,3,4,5,6]
>>> y_data = [1,2,3,4,5]
>>> pyspedas.store_data("Variable1", data={'x':x_data, 'y':y_data})
>>> pyspedas.tplot("Variable1",bokeh=True)

>>> #Display two plots
>>> x_data = [1,2,3,4,5]
>>> y_data = [[1,5],[2,4],[3,3],[4,2],[5,1]]
>>> pyspedas.store_data("Variable2", data={'x':x_data, 'y':y_data})
>>> pyspedas.tplot(["Variable1", "Variable2"])

>>> #Display 2 plots, using Variable1 as another x axis
>>> x_data = [1,2,3]
>>> y_data = [ [1,2,3] , [4,5,6], [7,8,9] ]
>>> v_data = [1,2,3]
>>> pyspedas.store_data("Variable3", data={'x':x_data, 'y':y_data, 'v':v_data})
>>> pyspedas.options("Variable3", 'spec', 1)
>>> pyspedas.tplot(["Variable2", "Variable3"], var_label='Variable1')

Interactive time selection

To interactively select a list of times corresponding to features of interest in your plot, you can use the ctime() routine.

pytplot.ctime(fig)

Select time values by clicking on a plot, similar to ctime in IDL SPEDAS

Left click saves the time at the current cursor position. ‘c’, ‘e’, or shift-left click clears the list of times selected. Right click or ‘q’ exits and returns the list of saved times (as floating point Unix times).

Parameters:

fig – A matplotlib fig object specifying the plot to be used for the time picker (returned by tplot with return_plot_objects=True)

Notes

This feature is very platform-dependent, and should still be considered experimental. Please let the PySPEDAS developers know if you have trouble using it in your environment.

As of this release, ctime seems to work in most situations, except for Jupyter notebooks using the ‘ipympl’ (aka ‘widget’) matplotlib backend. With that backend, the most common failure modes are that the ctime() call returns immediately, with no chance to interact with the plot, or the tplot call gets stuck somehow and never renders the plot.

We are working on a fix for the ipympl incompatibility, but for now, the best workaround for Jupyter notebooks may be to use “%matplotlib auto” as the backend. Depending on your exact environment, this will probably render the plots outside of the Jupyter notebooks (so the plot results won’t be saved in the notebook), but at least ctime should work, allowing you to continue with your desired workflow.

Returns:

The selected times as floating point Unix times (in seconds)

Return type:

list of double

Examples

>>> import pyspedas
>>> from pyspedas import tplot, ctime, time_string
>>> pyspedas.projects.themis.state(probe='a')
>>> myfig, ax = tplot('tha_pos', return_plot_objects=True)
>>> saved_timestamps = ctime(myfig)
>>> print(time_string(saved_timestamps))

Oveplotting

To combine two or more variables in the same plot, you need to create a new variable like so:

pytplot.store_data("new_variable", data=["variable1_to_overplot", "variable2_to_overplot"])

Then when you plot this new variable, it will be a combination of the two variables given in “data”.

Note

Each variable should still retain the plot options you set for it, but I am still working out the kinks.

Extra X axes

A commonly used feature of tplot is adding extra x axes (in addition to time), on the bottom of the plot.

To do so in pytplot, specify which tplot variable(s) you’d like to to be included on the axis by passing them to the “var_label” option in tplot:

pytplot.tplot("variable1", var_label = ["variable2", "variable3"])

Note

Unfortunately, in the Bokeh plots currently the extra x axes must be linearly increasing in order to display properly. Hopefully we can determine a way to map variables onto the axes at some point in the future.

A common use case would be orbit numbers or spacecraft position. Here is an example of multiple x axes below: