Tplot Tutorial

Load data into memory
Storing Data
Pytplot Variables
Options
Displaying Data Using Tplot
Interacting with Data Plot
Time Variables

Load some data into memory
• The pytplot package comes with a sample IDL tplot save file which will be used for the following tutorial, located in pytplot/pytplot/sampledata. You can also download it here.


• This file was generated in IDL, and therefore can be loaded into tplot if you wish to compare the IDL and python versions.


• To load this data into pytplot, type in the command pytplot.tplot_restore('path/to/file/test_data.tplot')


Storing Data
• pytplot works by interacting with global variables (called tplot variables) that contain information necessary for creating one panel (or even one portion of a panel) of a plot, that can be accessed from the main level or within any Python routine. Before anything can be plotted, tplot variables must be loaded into memory.


• Single line Plot: to store data to plot a single line, the 'y' data will be a single list of data that will correspond to the points that will make up the line.


• Multi-line Plot: to store data to plot a multi-line plot, the 'y' data will be a list of lists. Each column of the "matrix" created is the data for one line. So if you had a list with four lists in it and three elements in each list [[1,2,3],[4,5,6],[7,8,9],[10,11,12]] three lines with four data points each will be plotted.


• Spectrogram Plot: to store data to plot for a spectrogram, 'v' data will be a list of bins for the data, and the 'y' data will be a matrix of values with dimensions of the length of "x" time the length of "v"


• Map Plot: to store data to plot for a latitude/longitude plot, 'x' will contain a list of latitudes and a list of longitudes, for example 'x':[[15,30,45],[30,60,90]], and the 'y' data will be a list of values that correspond to those latitude/longitude points



• Combining Two Plots: py_overplot('new_name', ['old_name1', 'old_name2']) to combine multiple existing tplot variables ('old_name1' and 'old_name2') into one new tplot variable ('new_name'). 'new_name' will have all data from the existing tplot variables entered in one new tplot variable.




Pytplot Variables


• pytplot.tplot_names() will print the numbers and names of the tplot variables currently in memory.


• When using any routines that require the name of the tplot variable, the user can use either the name of the variable or the corresponding number.




Options


• pytplot.options('tplot_var', 'option', 'option_value') can be used to change plotting options corresponding to specific tplot variables. All options currently implemented are described in the pytplot documentation, but here are some examples to get you started.
• Line Thickness: pytplot.options('swia_vel', 'thick', 4)
• Title of y-axis: pytplot.options('swia_vel', 'ytitle', 'speed (km/s)')
• Vertical Bounds of Plot: pytplot.options('SEP_1_ION', 'yrange', [5,5000])
• Vertical Size of Panel: pytplot.options(['mag','swia_den','swia_vel'], 'panel_size', 0.5)


• pytplot.tplot_options('option', 'option_value') can be used to change plotting options for the tplot routine. These control options that effect all panels in a plot, such as:
• Title: pytplot.tplot_options('title', 'All Plots')
• Window Size: pytplot.tplot_options('wsize', [800, 800])




Display Data Using Tplot
• Single Panel Plot: pytplot.tplot('swia_vel') or alternatively use the tplot variable number pytplot.tplot(6)


• Multiple Panel Plot: pytplot.tplot(['swia_counts', 'swia_vel', 'mag']) or pytplot.tplot([4,6,7])



• Note: If you are using the jupyter notebook and you want the plots to appear there, specify nb=True when calling tplot. For example, pytplot.tplot([4,6,7], nb=True).




Interacting with Data Plot
• There are several ways to interact with the data plots. There is command line interaction that follows the same pattern of functions IDL utilizes. Pytplot additionally has interactivity built into the viewing window in the form of "tools".


• Move forward and backward in time: The Pan tool allows the user to click and drag the mouse on the plot to move along the x- or y-axis.


• Zoom in and out (in time) on a plot
  
  • Command Line: pytplot.tlimit(['2016-06-20 00:00:00', '2016-06-20 04:00:00']) will zoom in to show the data from the first time supplied to the second time when tplot is called again. pytplot.tlimit('last') will revert to the previous time range. pytplot.tlimit('full') will display the plots using the full time range.
  • Tools: The Box Zoom tool allows the user to click and drag the mouse on the plot to specify their desired x-axis range. The Undo tool can then revert the time range to that previously shown. The Reset tool reverts the entire plot to the way it was when first plotted (full time range).
  
  


• Show data points: The Hover Tool displays the data of a given point when the user hovers their mouse over the line.


• To put crosshairs on the window: The Crosshairs tool displays a set of crosshairs that follow the location of the mouse on the plot.


• To place a vertical line at a specific time on all panels: pytplot.timebar('2016-06-20 01:15:32', thick=3, color='green') will add a vertical black line to all plots at the time entered. Further settings related to this routine are described in the pytplot documentation.


• pytplot also has the ability to interact directly with spectrograms. If you supply the interactive=True keyword to pytplot (pytplot.tplot([1,2,3,4], interactive=True)), a plot will appear next to the spectrogram that reads out "slices" of the plot when you hover the mouse over it.




Time Variables
• For routines that use time inputs (timebar, timespan, tlimit, xlim), time can be input in two ways. The first is simply the number of seconds since epoch. The second is a string formatted in the following way: "YYYY-MM-DD hh:mm:ss" with M: month, D: day, Y: year, h: hour, m: minute, s: second.
• For example, "2016-8-25 16:43:37" is equivalent to 1472143417.