Tplot Tutorial

Overview
Starting IDL
Loading tplot data
Displaying tplot data
Interacting with tplot data

Overview
• tplot is a software package that works in IDL.


• tplot is used to display and manipulate time series (particle and fields) data, typically in multi-panel plot formats.


• tplot was originally developed by Davin Larson at Berkeley Space Sciences Lab in the 90's


• tplot has been maintained by and contributed to by a number of different people over the years.


• The location of the "best" and most up-to-date distribution and documentation for tplot is at the Berkeley THEMIS web site, under software.


• It is possible using the documentation cited above to successfully use tplot on your own


• However, the typical user learns by having "someone knowledgeable" show them how it works.


• This short tutorial is intended to provide a supplement or replacement to the "someone knowledgeable" and a bridge to the on-line documentation.




Step 0: Start IDL and load some data into memory
• This tutorial will make more sense if you are familar with IDL, but here I try to give you just enough information to successfully navigate the tutorial.


• If you are not familiar with IDL, you can start IDL in immediate mode from a UNIX/Linux workstation by typing idl at the command line (assuming that your machine is set up to run IDL).


• The help pages in IDL are accessed by typing ? at the IDL prompt. I find them to be pretty good.


• Load some data into IDL memory. If you would like some sample data use this file. To load it into IDL memory, type restore, 'm04d062h04.idl' at the IDL prompt. This tutorial assumes you are working with this data file. Alternatively, you can load any other data on your own. For example if your machine is configured to access MGS data then feel free to use the mgs_restore command (after typing @mars_dat) to load some data of your choosing.


• To see what variables are currently loaded into IDL memory at any time, type help at the IDL prompt. If the data file above has been successfully loaded, then you will see that a number of data structures have been loaded, including MAGS and ENGYS, which we will use in this tutorial. If you are using mgs_restore to load data, then MAG and ENGY are the relevant variable names.


• Data structures in IDL (or any language) are a little more complex than normal variables. They are essentially 'groupings of normal variables'. For example, MAGS is an array of data structures, each containing a timestamp, the field amplitude, and the vector magnetic field in two cartesian coorinate systems. To see an overview of the contents of a data structure in IDL, type help, [variable name here], /structure. For MAGS, you should see that it is an array having 4800 elements, each one a data structure. Each data structure contains a time (a double precision number, having units of seconds), an amplitude (in nT), and two 3-element arrays containing the x, y, and z components of the magnetic field vector in SS (=MSO) and PC (=planetary) coordinates. For more information on using data structures and arrays in IDL, use the help pages.




Step 1: Load data into tplot variables
• tplot works by interacting with global variables (called a tplot variable) in IDL 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 IDL routine. Before anything can be plotted, tplot variables must be loaded into memory.


• The main command used for loading tplot data into memory is store_data.


• Single line plot: To create a tplot variable named 'amplitude' that can be used to create a line plot of magnetic field amplitudes, use store_data in the following manner from the IDL prompt: store_data, 'amplitude', data={x:mags.time, y:mags.amp}. The x-data are times, and the y-data are amplitudes. The curly bracets are used because 'data' is an IDL structure. From here, I suggest skipping ahead to Step 2 of the tutorial, then hopping back and forth between Step 1 and Step 2.


• Multi-line plot: To create a tplot variable named 'Bxyz' that can be used to create a plot panel having three lines (the x, y, and z coordinates of magnetic field as a function of time), use store_data as follows: store_data, 'Bxyz', data={x:mags.time, y: transpose(mags.ss)}. Note the 'transpose' of mags.ss. This is because mags.ss is a 3-column array, and tplot interprets each separate row in the y-data as a separate line to be plotted.


• Spectrogram: To create a tplot variable named 'fluxes' that can be used to plot a spectrogram of electron fluxes as a function of time and energy, use store_data as follows: store_data, 'fluxes', data={x:engys.time, y:transpose(engy.data), v:engyinfo.energy}. For spectrograms, the x-data are times (along the x-axis of the plot), the v-data are energies (along the y-axis of the plot), and the y-data are fluxes corresponding to the color that will be plotted at each time and energy in the spectrogram. I realize that calling the fluxes 'y-data' is misleading, but there you have it.


• Merging two plots: To create a tplot varaible named 'allmag' that can be used to plot the time series of magnetic field amplitudes and the vector components in a single panel, you could start from scratch by creating a multi-line plot, or you could merge previously defined tplot variables as follows: store_data, 'allmag', data=['amplitude','Bxyz']
• The next most important command for loading tplot variables into memory, after store_data, is options. This command can be used to change alomst any plotting option, just as it is done within 'regular IDL'. The syntax is options, 'tplot variable name here', 'plot option here', value[s]. See a few examples below (refer to the tplot documentation for many more options). Keep in mind that once a plot option has been set, it can not be unset without using another 'option' command.


• Changing line thickness: options, 'amplitude', 'thick', 4


• Changing the title of the y axis: options, 'Bxyz', 'ytitle', 'Bxyz (nT)'


• Changing the vertical bounds of the plot: options, 'amplitude', 'yrange', [0,300]


• Changing the color of every line in the panel: options, 'amplitude', 'color', 150. Assuming that colortable #39 is loaded, this should make your panel green.


• Changing the colors of individual lines in a multi-line plot: options, 'Bxyz', 'colors', [80, 150, 250]


• Changing the color scale of a spectrogram: zlim, 'fluxes', 10, 1e7, 1. Note the use of the zlim command, rather than options. The '1' at the end indicates that the spectrogram should use a log scale between 10 and 1e7 to color the plot. If a '0' had been used, the colorscale would be linear.


• Changing a spectrogram to/from a multi-line plot: options, 'fluxes', 'spec', 1. '1' indicates a spectrogram should be plotted. '0' indicates a multi-line plot should be plotted.


• Changing the vertical size of the panel to be plotted: options, 'allmag', 'panel_size', .5. The '.5' is the fractional size of the plot relative to the other panels. However, tplot will add up all of the fractional sizes of panels that it is plotting, and normalize everything (divide the fractional size of each panel by the total fractional size of all panels) so that it fits on the page.




Step 2: Display data using tplot
• This is the easy part, and one of the main reasons to learn tplot!


• To see what tplot variables are currently loaded in IDL memory, type tplot_names. The result is an itemized list of tplot_variables that can be referenced either by number or by name when plotting.


• To create a single-panel plot, use the tplot command as follows: tplot, 'amplitude'. Alternatively, you could type tplot, 1.


• To redisplay the plot at any time, type tplot. You don't need to specify the variable - tplot remembers the last variables you plotted.


• To create a multi-panel plot, type tplot, ['amplitude', 'fluxes','Bxyz'] or tplot, [1,3,2]




Step 3: Interact with the data plot
• There are several ways to interact with the data plot, and by this point you probably feel comfortable enough with tplot to go hunting in the on-line documentation. But here are three useful commands.


• To zoom in and out (in time) within a plot: Use the tlimit command.


• Typing tlimit will allow you to use the mouse to click the start and end times in the current tplot that you want to zoom to. tplot then redisplays the variables, restricted to the two times. You can keep doing this as many times as you like.


• Typing tlimit, /last will redisplay the tplot variables using the previous time range.


• Typing tlimit, /full will redisplay the tplot variables using the full time range.


• To put crosshairs on the tplot window: type crosshairs. You can then scroll around to different points and the IDL window will display the time and data value at each point. To exit, click the mouse button. To retrieve the time and data value at the location where the mouse button is pressed, instead type crosshairs, [time variable name of your choosing here], [data value variable name of your choosing here]. For a more sophisticated version of this routine capable of retrieving a bunch of times, use ctime.


• To place a vertical line at a specific time on all panels, use timebar, timestamp, where timestamp (or whatever variable name you choose) is a variable containing the double precision time at which to draw the line. You can also specify the color and linestyle (e.g. red and dashed).

Created 04 February, 2009 by Dave Brain