Tplot Tutorial

Load data into memory
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')


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.