This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Sep 27 14:05:48 2007.
NAME:
bitplot
INPUT: (optional if DATA keyword is set)
x: array of x values
y: array of y values
PURPOSE:
Plots 'ON' bits for housekeeping type data.
Can be used by "tplot".
See "_tplot_example" and "_get_example_dat" for an example.
KEYWORDS:
PSYMS: array of IDL plot psym values corresponding to each bit.
OVERPLOT: create plot without erasing previous plot.
DI: value to be given to first bit in plot. Default is 0.
LIMITS: TPLOT limits structure corresponding to the variable plotted.
DATA: TPLOT data structure corresponding to the variable plotted.
(See ssl_general/tplot/bitplot.pro)
Procedure: CLEAN_SPIKES, 'name' Purpose: Simple routine to remove spikes from tplot data. Author: unknown, Probably Frank Marcoline jmm, 4-jul-2007, made to work for negative data, by adding absolute values jmm, 30-jul-2007, Added more error checking $LastChangedBy$ $LastChangedDate$ $LastChangedRevision$ $URL$
(See ssl_general/tplot/clean_spikes.pro)
PROCEDURE: copy_data, oldname, newname
PURPOSE: to copy a data structure
INPUT:
oldname: name associated with old data structure
newname: name associated with new data structure
KEYWORDS:
LINK: if set, then the data is not copied but is linked to the old
name.
SEE ALSO: "get_data",
"store_data"
CREATED BY: Davin Larson
LAST MODIFICATION: copy_data.pro 1.10 97/05/20
(See ssl_general/tplot/copy_data.pro)
NAME: crosshairs
PURPOSE:
Display crosshairs on the plot window, display the data coordinates of the
cursor position on the plot, and return the coordinates of clicked points.
Use the mouse buttons to control operation:
1: Record and print a point
2: Delete the previously recorded point
3: Quit.
CALLING SEQUENCE: crosshairs,x,y
INPUTS: x,y: set to named variables to return the data
coordinates of the cursor position where mouse
button 1 was pressed.
KEYWORD PARAMETERS:
COLOR: set to a scalar byte to change the color of the crosshairs.
note: you will not get the color you ask for. it's the nature
of XOR graphics. could be useful to change colors though.
LEGEND: set a position for the legend, in data coords.
DOT_CURSOR: change the cursor to a dot. it's smaller and makes seeing
the data easier. warning: will reset the cursor to crosshairs
after quitting. if you had set your own cursor (changed from
the default) it'll be replaced.
FIX: if crosshairs crashes (if you Control-C out of it) then
you probabaly want to call crosshairs,/fix
all it does is calls: device,set_graphics=3,/cursor_cross
but do you want to remember that line?
FIX repairs the changes to the X device that crosshairs made.
SILENT: don't print clicked points
NOLEGEND: don't display the legend
OUTPUTS: prints clicked data points to the terminal, prints the current
cursor position on the graphics window (or last position before
leaving the window)
SIDE EFFECTS: can mess up your display. use crosshairs,/fix to fix.
can leave junk on your plot. not recommended for use
if you intend to call tvrd() before reploting.
LAST MODIFICATION: @(#)crosshairs.pro 1.5 98/07/31
CREATED BY: Frank V. Marcoline
NOTES: Inspired by IDL's box_cursor.pro
(See ssl_general/tplot/crosshairs.pro)
PROCEDURE: ctime,time,y,z
INPUT:
time: Named variable in which to return the selected time (seconds
since 1970)
y: Named variable in which to return the y value
z: Named variable in which to return the z value
KEYWORDS:
PROMPT: Optional prompt string
NPOINTS: Max number of points to return
PSYM: If set to a psym number, the cooresponding psym is plotted at
selected points
SILENT: Do not print data point information
PANEL: Set to a named variable to return an array of tplot panel numbers
coresponding to the variables points were chosen from.
APPEND: If set, points are appended to the input arrays,
instead of overwriting the old values.
VNAME: Set to a named variable to return an array of tplot variable names,
cooresponding to the variables points were chosen from.
COLOR: An alternative color for the crosshairs. 0<=color<=!d.n_colors-1
SLEEP: Sleep time (seconds) between polling the cursor for events.
Defaults to 0.1 seconds. Increasing SLEEP will slow ctime down,
but will prevent ctime from monopolizing cpu time.
INDS: Return the indices into the data arrays for the points nearest the
recorded times to this named variable.
VINDS: Return the second dimension of the v or y array.
Thus TIME(i) is data.x(INDS(i)) and
Y(i) is data.y(INDS(i),VINDS(i)) and
V(i) is data.v(VINDS(i)) or data.v(INDS(i),VINDS(i))
for get_data,VNAME(i),data=data,INDS=INDS,VINDS=VINDS
EXACT: Get the time,y, and (if applicable) z values from the data
arrays. If on a multi-line plot, get the value from the line
closest to the cursor along y.
NOSHOW: Do not show the plot window.
DEBUG: Avoids default error handling. Useful for debugging.
DAYS, HOURS, MINUTES, SECONDS: Sets time granularity. For example
with MINUTES=1, CTIME will find nearest minute to cursor
position.
PURPOSE:
Interactively uses the cursor to select a time (or times)
NOTES: If you use the keyword EXACT, ctime may run noticeablly slower.
Reduce the number of time you cross panels, especially with
tplots of large data sets.
SEE ALSO: "crosshairs"
CREATED BY: Davin Larson & Frank Marcoline
LAST MODIFICATION: @(#)ctime.pro 1.44 02/11/01
WARNING!
If ctime crashes, you may need to call:
IDL> device,set_graph=3,/cursor_crosshair
(See ssl_general/tplot/ctime.pro)
PROCEDURE: cuts PURPOSE: to show x cuts or y cuts of a "tplot" spectrogram INPUT: none KEYWORDS: name: name of the variable you want cuts for CREATED BY: Peter Schroeder LAST MODIFICATION: @(#)cuts.pro 1.6 98/01/29
(See ssl_general/tplot/cuts.pro)
FUNCTION: A = data_cut(name, t)
PURPOSE: Interpolates data from a data structure.
INPUT:
name: Either a data structure or a string that can be associated with
a data structure. (see "get_data" routine)
the data structure must contain the element tags: "x" and "y"
the y array may be multi dimensional.
t: (scalar or array) x-values for interpolated quantities.
RETURN VALUE:
a data array: the first dimension is the dimension of t
the second dimension is the dimension of name
NOTE!! keyword options have been temporarily removed!!!!
KEYWORDS:
EXTRAPOLATE: Controls interpolation of the ends of the data. Effects:
0: Default action. Set new y data to NAN or to MISSING.
1: Extend the endpoints horizontally.
2: Extrapolate the ends. If the range of 't' is
significantly larger than the old time range, the ends
are likely to blow up.
INTERP_GAP: Determines if points should be interpolated between data gaps,
together with the GAP_DIST. IF the data gap > GAP_DIST,
follow the action of INTERP_GAP
0: Default action. Set y data to MISSING.
1: Interpolate gaps
GAP_DIST: Determines the size of a data gap above which interpolation
is regulated by INTERP_GAP.
Default value is 5, in units of the average time interval:
delta_t = (t(end)-t(start)/number of data points)
MISSING: Value to set the new y data to for data gaps. Default is NAN.
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)data_cut.pro 1.19 02/04/17
Added the four keywords. (fvm 9/27/95)
(See ssl_general/tplot/data_cut.pro)
FUNCTION: data_to_normal PURPOSE: convert data coordinates to normal coordinates INPUT: datav: data coordinates s: !AXIS structure KEYWORDS: none CREATED BY: Frank Marcoline. Hiested from Davin's normal_to_data. LAST MODIFICATION: @(#)data_to_normal.pro 1.2 97/01/09 NOTE: I think this procedure is superceded by convert_coord.
(See ssl_general/tplot/data_to_normal.pro)
NAME: del_data
PURPOSE:
obsolete procedure! use "STORE_DATA" instead
delete tplot variables
del_data calls "store_data" with the DELETE keyword set
let: input=['a','b','c','d','e','f']
then, del_data,input is the same as
store_data,delete=input
CALLING SEQUENCE: del_data,input
INPUTS: input: strarr() or intarr() of tplot variables
LAST MODIFICATION: @(#)del_data.pro 1.4 01/10/08
CREATED BY: Frank Marcoline
(See ssl_general/tplot/del_data.pro)
PROCEDURE: draw_color_scale
NAME:
draw_color_scale
PURPOSE:
Procedure to draw a color scale.
INPUTS: (none)
KEYWORDS:
RANGE: Array of two giving the range in data values the scale
corresponds to.
BRANGE: intarr(2) giving the range in color map values the
scale spans.
LOG: If set, make scale logarithmic.
CHARSIZE: Character size to be used for scale.
YTICKS: Functions like IDL plot yticks keyword. Used to set
number of scale annotations.
POSITION: fltarr(4) giving the position of the color scale in the
window in the form (x0,y0,x1,y1).
OFFSET: fltarr(2) giving the offsets from the right side of the
current plot for calculating the x0 and x1 positions
of the color scale. In device units. Ignored if
POSITION keyword is set.
TITLE: String title for color scale.
CREATED BY: Davin Larson
LAST MODIFIED: 1.17 05/29/07
MODIFIED BY: Patrick Cruce
(See ssl_general/tplot/draw_color_scale.pro)
FUNCTION: find_handle(name)
PURPOSE:
Returns the index associated with a string name.
This function is used by the "TPLOT" routines.
INPUT: name (scalar string)
name can also be the corresponding integer index to a TPLOT quantity,
in which case name will be converted to the string handle.
RETURN VALUE: tplot index. (0 if not found)
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)find_handle.pro 1.14 99/02/26
(See ssl_general/tplot/find_handle.pro)
FUNCTION: gettime(x)
INPUTS: x: Null or double or string or integer
OUTPUT: double, seconds since Jan 1, 1970
Examples:
t = gettime('95-7-4/12:34')
t = gettime('12:34:56') (get time on reference date)
t = gettime(t+300.) (assumes t is a double)
t = gettime(10) (t = 10 am on reference date)
t = gettime(/key) (prompts user for time on reference date)
t = gettime(key='Enter time: ')
t = gettime(/curs) (select time using cursor in tplot routine)
KEYWORDS:
KEYBOARD: If non-zero then user is prompted to enter a time. If KEYBOARD
is a string then that string is used as a prompt.
CURSOR: if non-zero then user can select a time with the cursor.
VALUES: if cursor keyword set, returns data values for time chosen.
REFDATE: Sets the reference date if REFDATE is a string with
format: "yyyy-mm-dd".
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)gettime.pro 1.17 98/08/02
(See ssl_general/tplot/gettime.pro)
PROCEDURE: get_data , name, time, data, values
PURPOSE:
Retrieves the data and or limit structure associated with a name handle.
This procedure is used by the "TPLOT" routines.
INPUT: name scalar string or index of TPLOT variable
time named variable to return time values.
data named variable to return data (y) values.
values named variable to return additional (v) values.
KEYWORDS:
DATA: named variable to hold the data structure.
LIMITS: named variable to hold the limits structure.
DLIMITS: named variable to hold the default limits structure.
ALIMITS: named variable to hold the combined limits and default limits
structures.
DTYPE: named variable to hold the data type value. These values are:
0: undefined data type
1: normal data in x,y format
2: structure-type data in time,y1,y2,etc. format
3: an array of tplot variable names
PTR: named variable to hold pointers to data structure.
INDEX: named variable to hold the name index. This value will be 0
if the request was unsuccessful.
SEE ALSO: "STORE_DATA", "TPLOT_NAMES", "TPLOT"
CREATED BY: Davin Larson
MODIFICATION BY: Peter Schroeder
LAST MODIFICATION: @(#)get_data.pro 1.28 02/04/17
(See ssl_general/tplot/get_data.pro)
PROCEDURE: get_timespan PURPOSE: To get timespan from tplot_com or by using timespan, if tplot time range not set. INPUT: t, actually returned to you KEYWORDS: none SEE ALSO: "timespan" CREATED BY: Davin Larson LAST MODIFICATION: @(#)get_timespan.pro 1.9 97/06/02
(See ssl_general/tplot/get_timespan.pro)
PROCEDURE: get_ylimits, datastr, limits, trg PURPOSE: Calculates appropriate ylimits for a string array of "TPLOT" variables to be plotted in the same panel. INPUT: datastr string array of TPLOT variables limits limits structure to be modified (usually the limits structure of the TPLOT variable whose data field is a string array of TPLOT variables) trg time range over which to calculate the limits; double[2] CREATED BY: Peter Schroeder LAST MODIFIED: %W% %E%
(See ssl_general/tplot/get_ylimits.pro)
NAME: iton
PURPOSE:
Convert an index or array of indicies to data names.
This exits because it is not always reasonable to make
a program tell the difference between a data array
and an index array, and because not all programs
accept indicies as inputs instead of data names.
CALLING SEQUENCE: names=iton(ind)
INPUTS: ind: an index or array of indicies
OPTIONAL INPUTS: none
KEYWORD PARAMETERS: none
OUTPUTS: a data name or array of data names
OPTIONAL OUTPUTS: none
COMMON BLOCKS: tplot_com
SIDE EFFECTS: none
EXAMPLE: for i=6,13 do store_data,iton(6),/delete
LAST MODIFICATION: @(#)iton.pro 1.5 97/06/11
CREATED BY: Frank Marcoline
(See ssl_general/tplot/iton.pro)
PROCEDURE makegap,dg,x,y
PURPOSE:
Creates data gaps (by inserting NaN) when the time between data points is
larger than a value either passed in by the user or calculated to a
default.
INPUT:
dg: If dg is positive, it is the maximum allowed time gap. Any time gaps
greater than dg will be treated as data gaps. If dg is negative,
the procedure will calculate a default value for dg of 20 times the
the smallest time gap in the time series.
x: The time array.
y: The data array.
KEYWORDS:
v: Optional third dimension array.
dy: Optional uncertainty in y.
CREATED BY: Peter Schroeder
LAST MODIFIED: @(#)makegap.pro 1.2 98/02/18
(See ssl_general/tplot/makegap.pro)
PROCEDURE: mplot, x, y, [,dy]
INPUT:
x: 1 or 2 dimensional array of x values.
y: 1 or 2 dimensional array of y values.
dy; error bars for y; same dimensions as y. (optional)
PURPOSE:
General purpose procedure used to make multi-line plots.
KEYWORDS:
DATA: A structure that contains the elements 'x', 'y' ['dy']. This
is an alternative way of inputing the data (used by "TPLOT").
LIMITS: Structure containing any combination of the following elements:
ALL PLOT/OPLOT keywords (ie. PSYM,SYMSIZE,LINESTYLE,COLOR,etc.)
ALL MPLOT keywords
NSUMS: array of NSUM keywords.
LINESTYLES: array of linestyles.
LABELS: array of text labels.
LABPOS: array of positions for LABELS.
LABFLAG: integer, flag that controls label positioning.
-1: labels placed in reverse order.
0: No labels.
1: labels spaced equally.
2: labels placed according to data.
3: labels placed according to LABPOS.
BINS: flag array specifying which channels to plot.
OVERPLOT: If non-zero then data is plotted over last plot.
NOXLAB: if non-zero then xlabel tick marks are supressed.
COLORS: array of colors used for each curve.
NOCOLOR: do not use color when creating plot.
NOTES:
The values of all the keywords can also be put in the limits structure or
in the data structure using the full keyword as the tag name.
The structure value will overide the keyword value.
CREATED BY: Davin Larson
FILE: mplot.pro
VERSION 1.43
LAST MODIFICATION: 02/11/01
(See ssl_general/tplot/mplot.pro)
FUNCTION: normal_to_data PURPOSE: convert normal coordinates to data coordinates INPUT: normv: normal coordinates s: !AXIS structure KEYWORDS: none CREATED BY: Davin Larson LAST MODIFICATION: @(#)normal_to_data.pro 1.5 98/08/02 NOTE: I think this procedure is superceded by convert_coord.
(See ssl_general/tplot/normal_to_data.pro)
PROCEDURE: options, str, tag_name, value
PURPOSE:
Add (or change) an element of a structure.
This routine is useful for changing plotting options for tplot, but can also
be used for creating limit structures for other routines such as "SPEC3D"
or "CONT2D"
INPUT:
str:
Case 1: String (or array of strings)
The limit structure associated with the "TPLOT" handle name is altered.
Warning! wildcards accepted! "*" will change ALL tplot quantities!
Case 2: Number (or array of numbers)
The limit structure for the given "TPLOT" quantity is altered. The
number/name association is given by "TPLOT_NAMES"
Case 3: Structure or not set (undefined or zero)
Structure to be created, added to, or changed.
tag_name: string, tag name for value.
value: (any type or dimension) value of new element.
NOTES:
if VALUE is undefined then it will be DELETED from the structure.
if TAG_NAME is undefined, then the entire limit structure is deleted.
KEYWORDS:
DEFAULT: If set, modify the default limits structure rather than the
regular limits structure (tplot variables only).
SEE ALSO:
"GET_DATA","STORE_DATA", "TPLOT", "XLIM", "YLIM", "ZLIM", "STR_ELEMENT"
CREATED BY: Jasper Halekas
Modified by: Davin Larson
LAST MODIFICATION: @(#)options.pro 1.19 99/04/07
(See ssl_general/tplot/options.pro)
PROCECURE: pmplot
PURPOSE: Used for making log y-axis plots. Preformats data for
use with "mplot". Plots negative data in red and positive
data in green.
KEYWORDS:
DATA: A structure that contains the elements 'x', 'y' ['dy']. This
is an alternative way of inputing the data (used by "TPLOT").
LIMITS: Structure containing any combination of the following elements:
ALL PLOT/OPLOT keywords (ie. PSYM,SYMSIZE,LINESTYLE,COLOR,etc.)
ALL PMPLOT keywords
NSUMS: array of NSUM keywords.
LINESTYLES: array of linestyles.
LABELS: array of text labels.
LABPOS: array of positions for LABELS.
LABFLAG: integer, flag that controls label positioning.
-1: labels placed in reverse order.
0: No labels.
1: labels spaced equally.
2: labels placed according to data.
3: labels placed according to LABPOS.
BINS: flag array specifying which channels to plot.
OVERPLOT: If non-zero then data is plotted over last plot.
NOXLAB: if non-zero then xlabel tick marks are supressed.
COLORS: array of colors used for each curve.
NOCOLOR: do not use color when creating plot.
NOTES:
The values of all the keywords can also be put in the limits structure or
in the data structure using the full keyword as the tag name.
The structure value will overide the keyword value.
LAST MODIFIED: @(#)pmplot.pro 1.4 02/04/17
(See ssl_general/tplot/pmplot.pro)
PROCEDURE: scat_plot, xname, yname
PURPOSE:
Produces a scatter plot of selected tplot variables.
Colors are scaled according to zname, if present
INPUTS:
xname: xvariable name
yname: yvariable name
zname: if present, color variable name
KEYWORDS:
TRANGE: two element vector giving start and end time.
limits: a structure with plotting keywords
begin_time: time at which to start plot
end_time: time at which to end plot
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)scat_plot.pro 1.13 02/04/17
(See ssl_general/tplot/scat_plot.pro)
PROCEDURE specplot,x,y,z
NAME:
specplot
PURPOSE:
Creates a spectrogram plot.
All plot limits and plot positions are handled by the keyword LIMITS.
INPUT:
x: xaxis values: dimension N.
y: yaxis values: dimension M. (Future update will allow (N,M))
Z: color axis values: dimension (N,M).
All options are passed in through a single structure.
KEYWORDS:
LIMITS: A structure that may contain any combination of the following
elements:
X_NO_INTERP: Prevents interpolation along the x-axis.
Y_NO_INTERP: Prevents interpolation along the y-axis.
NO_INTERP: Prevents interpolation along either axis
NO_COLOR_SCALE: Prevents drawing of color bar scale.
BOTTOM, TOP: Sets the bottom and top colors for byte-scaling
ALL plot keywords such as:
XLOG, YLOG, ZLOG,
XRANGE, YRANGE, ZRANGE,
XTITLE, YTITLE,
TITLE, POSITION, REGION etc. (see IDL documentation for a description)
The following elements can be included in LIMITS to effect DRAW_COLOR_SCALE:
ZTICKS, ZRANGE, ZTITLE, ZPOSITION, ZOFFSET
DATA: A structure that provides an alternate means of supplying
the data and options. This is the method used by "TPLOT".
X_NO_INTERP: Prevents interpolation along the x-axis.
Y_NO_INTERP: Prevents interpolation along the y-axis.
OVERPLOT: If non-zero then data is plotted over last plot.
OVERLAY: If non-zero then data is plotted on top of data from last
last plot.
PS_RESOLUTION: Post Script resolution. Default is 150.
NO_INTERP: If set, do no x or y interpolation.
IGNORE_NAN: If nonzero, ignore data points that are not finite.
Notes:
- The arrays x and y MUST be monotonic! (increasing or decreasing)
- The default is to interpolate in both the x and y dimensions.
- Data gaps can be included by setting the z values to NAN (!values.f_nan).
- If ZLOG is set then non-positive zvalues are treated as missing data.
See Also: "XLIM", "YLIM", "ZLIM", "OPTIONS", "TPLOT", "DRAW_COLOR_SCALE"
Author: Davin Larson, Space Sciences Lab
$LastChangedBy: kenb-mac $
$LastChangedDate: 2007-07-09 12:02:58 -0700 (Mon, 09 Jul 2007) $
$LastChangedRevision: 1035 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_2_02/tplot/specplot.pro $
(See ssl_general/tplot/specplot.pro)
NAME: split_vec
PURPOSE:
take a stored vector like 'Vp' and create stored vectors 'Vp_x','Vp_y','Vp_z'
CALLING SEQUENCE: split_vec,names
INPUTS: names: string or strarr, elements are data handle names
OPTIONAL INPUTS:
KEYWORD PARAMETERS: polar: Use '_mag', '_th', and '_phi'
titles: an array of titles to use instead of
the default or polar sufficies (NOT USED)
names_out: The variable names of the new variables
OUTPUTS:
OPTIONAL OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
EXAMPLE:
LAST MODIFICATION: 12-mar-2007, jmm
CREATED BY: Frank V. Marcoline
$LastChangedBy: jimm $
$LastChangedDate: 2007-03-12 16:25:30 -0700 (Mon, 12 Mar 2007) $
$LastChangedRevision: 461 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_2_02/tplot/split_vec.pro $
(See ssl_general/tplot/split_vec.pro)
PROCEDURE: store_data,name,DATA=data,LIMITS=limits,DLIMITS=dlimits,
NEWNAME=newname,DELETE=delete
PURPOSE:
Store time series structures in static memory for later retrieval
by the tplot routine. Three structures can be associated with the
string 'name': a data structure (DATA) that typically contains the x and
y data. A default limits structure (DLIMITS) and a user limits structure
(LIMITS) that will typically contain user defined limits and options
(typically plot and oplot keywords). The data structure and the default
limits structure will be
over written each time a new data set is loaded. The limit structure
is not over-written.
INPUT:
name: string name to be associated with the data structure and/or
the limits structure. Also, can enter tplot index as name.
The name should not contain spaces or the characters '*' and '?'
KEYWORDS:
DATA: variable that contains the data structure.
LIMITS; variable that contains the limit structure.
DLIMITS; variable that contains the default limits structure.
NEWNAME: new tplot handle. Use to rename tplot names.
DELETE: array of tplot handles or indices to delete from common block.
MIN: if set, data values less than this value will be made NaN. (obsolete)
MAX: if set, data values greater than this value will be made NaN. (obsolete)
NOSTRSW: if set, do not transpose multidimensional data arrays in
structures. The default is to transpose.
SEE ALSO: "GET_DATA", "TPLOT_NAMES", "TPLOT", "OPTIONS"
CREATED BY: Davin Larson
MODIFIED BY: Peter Schroeder
VERSION: @(#)store_data.pro 1.44 02/04/17
(See ssl_general/tplot/store_data.pro)
PROCEDURE: strplot, x, y
INPUT:
x: array of x values.
y: array of y strings.
PURPOSE:
Procedure used to print strings in a "TPLOT" style plot.
KEYWORDS:
DATA: A structure that contains the elements 'x', 'y.' This
is an alternative way of inputing the data.
LIMITS: The limits structure including PLOT and XYOUTS keywords.
OVERPLOT: If set, then data is plotted over last plot.
DI: Not used. Exists for backward compatibility.
LAST MODIFIED: @(#)strplot.pro 1.2 98/08/03
(See ssl_general/tplot/strplot.pro)
NAME: timebar
PURPOSE:
plot vertical lines on tplots at specified times
CALLING SEQUENCE: timebar,t
INPUTS: t: dblarr of times at which to draw vertical lines,
seconds since Jan, 1, 1970.
KEYWORD PARAMETERS:
COLOR: byte or bytarr of color values
LINESTYLE: int or intarr of linestyles
THICK: int or intarr of line thicknesses
for any of the above keywords, a scalar input will apply to all times
VERBOSE: print more error messages; useful for
debugging
VARNAME: TPLOT variable name indicating panel in which
to plot timebar
BETWEEN: array of two TPLOT variable names indicating
between which two panels to plot timebar
TRANSIENT: timebar,t,/transient called once plots a
timebar. Called twice, it deletes the timebar.
Note: 1) all other keywords except VERBOSE
be the same for both calls. 2) COLOR will most
likely not come out what you ask for, but
since it's transient anyway, shouldn't matter.
OUTPUTS:
OPTIONAL OUTPUTS:
COMMON BLOCKS: tplot_com
EXAMPLE: load_3dp_data,'95-01-01',2 & get_pmom
tplot,['Np','Tp','Vp']
t=time_double('95-01-01/1:12')
timebar,t ;put a white line at 1:12 am, Jan, 1, 1995
ctime,t1,t2 ;select two times from the plot
timebar,[t1,t2],color=!d.n_colors-2 ;plot them in red
SEE ALSO:
"CTIME","TPLOT"
CREATED BY: Frank V. Marcoline
LAST MODIFICATION: 99/01/21
FILE: 1.9
VERSION: timebar.pro
(See ssl_general/tplot/timebar.pro)
FUNCTION: timerange
PURPOSE: To get timespan from tplot_com or by using timespan, if
tplot time range not set.
INPUT:
tr (optional)
KEYWORDS:
CURRENT Set to 1 to get the current time range as set by tlimit.
RETURNS:
two element time range vector. (double)
SEE ALSO: "timespan"
REPLACES: "get_timespan"
CREATED BY: Davin Larson
$LastChangedBy: kenb-mac $
$LastChangedDate: 2007-06-05 08:30:27 -0700 (Tue, 05 Jun 2007) $
$LastChangedRevision: 731 $
$URL: svn+ssh:$
(See ssl_general/tplot/timerange.pro)
PROCEDURE: timespan, t1, dt
PURPOSE:
Define a time span for the "tplot" routine.
INPUTS:
t1: starting time (seconds since 1970 or string)
dt: duration of time span (DAYS is default)
KEYWORDS: set one of the following:
SECONDS
MINUTES
HOURS
DAYS (default)
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)timespan.pro 1.14 97/06/04
(See ssl_general/tplot/timespan.pro)
PROCEDURE: tlimit,t1,t2
PURPOSE: defines time range for "tplot"
(tplot must be called first)
INPUTS: Starting and Ending times. These can be string, double (seconds
since 1970), or hours since refdate. If no Input is given then the cursor
is used to select times from the most recent time plot.
KEYWORD:
REFDATE: new TPLOT reference data in seconds (double).
FULL: use full limits.
LAST: use the last plot's limits.
ZOOM: set to a value between 0 (no range in times) and 1 (full
time range) to zoom in on the center of the time range.
WINDOW: window in which to plot new time range.
OLD_TVARS: use this to pass an existing tplot_vars structure and
override the one in the tplot_com common block. This
can be used to select which window and set of data to
define a time range in.
NEW_TVARS: returns the tplot_vars structure created when plotting
the newly defined time range.
DAYS, HOURS, MINUTES, SECONDS: passed to "ctime" for cursor input of
time range.
SILENT If true, don't print output with x/y values under cursor.
Default value for Windows is silent=1, default for others is
silent = 0.
EXAMPLES:
tlimit ; Use the cursor
tlimit,'12:30','14:30'
tlimit, 12.5, 14.5
tlimit,t,t+3600 ; t must be set previously
tlimit,/FULL ; full limits
tlimit,/LAST ; previous limits
CREATED BY: Davin Larson
FILE: tlimit.pro
VERSION: 1.26
LAST MODIFICATION: 98/08/06
(See ssl_general/tplot/tlimit.pro)
FUNCTION: names=tnames(s [,n])
PURPOSE:
Returns an array of "TPLOT" names
This routine accepts wildcard characters.
CALLING SEQUENCE: nam=tnames('wi*') ; match tplot variables that start with 'wi'
INPUTS: s: a match string (ie. '*B3*' )
OPTIONAL INPUTS: s: an array of indices for tplot variables
KEYWORD PARAMETERS:
INDEX: named variable in which the the indices are returned.
TRANGE: named variable in which the start / end times are returned
CREATE_TIME named variable in which the creation time is stored.
TPLOT: if set then returns only the variables plotted in the most recent call to TPLOT
DATAQUANTS: if set then it returns the entire array of current stored TPLOT data quantities.
OUTPUTS: a data name or array of data names
OTHER OUTPUTS: n: the number of matched strings
COMMON BLOCKS: tplot_com
SIDE EFFECTS: none
EXAMPLE: print,tnames('*wi*')
VERSION: 1.8 @(#)tnames.pro 1.8 02/11/01
copied from iton.pro
CREATED BY: Davin Larson Feb 1999
(See ssl_general/tplot/tnames.pro)
PROCEDURE: tplot [,datanames]
PURPOSE:
Creates a time series plot of user defined quantities.
INPUT:
datanames: A string of space separated datanames.
wildcard expansion is supported.
if datanames is not supplied then the last values are used.
Each name should be associated with a data quantity.
(see the "STORE_DATA" and "GET_DATA" routines.)
Alternatively datanames can be an array of integers or strings.
run "TPLOT_NAMES" to show the current numbering.
KEYWORDS:
TITLE: A string to be used for the title. Remembered for future plots.
ADD_VAR: Set this variable to add datanames to the previous plot. If set
to 1, the new panels will appear at the top (position 1) of the
plot. If set to 2, they will be inserted directly after the
first panel and so on. Set this to a value greater than the
existing number of panels in your tplot window to add panels to
the bottom of the plot.
LASTVAR: Set this variable to plot the previous variables plotted in a
TPLOT window.
PICK: Set this keyword to choose new order of plot panels
using the mouse.
WINDOW: Window to be used for all time plots. If set to -1, then the
current window is used.
VAR_LABEL: String [array]; Variable(s) used for putting labels along
the bottom. This allows quantities such as altitude to be labeled.
VERSION: Must be 1,2,3, or 4 (3 is default) Uses a different labeling
scheme. Version 4 is for rocket-type time scales.
OVERPLOT: Will not erase the previous screen if set.
NAMES: The names of the tplot variables that are plotted.
NOCOLOR: Set this to produce plot without color.
TRANGE: Time range for tplot.
NEW_TVARS: Returns the tplot_vars structure for the plot created. Set
aside the structure so that it may be restored using the
OLD_TVARS keyword later. This structure includes information
about various TPLOT options and settings and can be used to
recreates a plot.
OLD_TVARS: Use this to pass an existing tplot_vars structure to
override the one in the tplot_com common block.
HELP: Set this to print the contents of the tplot_vars.options
(user-defined options) structure.
RESTRICTIONS:
Some data must be loaded prior to trying to plot it. Try running
"_GET_EXAMPLE_DAT" for a test.
EXAMPLES: (assumes "_GET_EXAMPLE_DAT" has been run)
tplot,'amp slp flx2' ;Plots the named quantities
tplot,'flx1',/ADD ;Add the quantity 'flx1'.
tplot ;Re-plot the last variables.
tplot,var_label=['alt'] ;Put Distance labels at the bottom.
For a long list of examples see "_TPLOT_EXAMPLE"
OTHER RELATED ROUTINES:
Examples of most usages of TPLOT and related routines are in
the crib sheet: "_TPLOT_EXAMPLE"
Use "TNAMES" function to return an array of current names.
Use "TPLOT_NAMES" to print a list of acceptable names to plot.
Use "TPLOT_OPTIONS" for setting various global options.
Plot limits can be set with the "YLIM" procedure.
Spectrogram limits can be set with the "ZLIM" procedure.
Time limits can be set with the "TLIMIT" procedure.
The "OPTIONS" procedure can be used to set all IDL
plotting keyword parameters (i.e. psym, color, linestyle, etc) as well
as some keywords that are specific to tplot (i.e. panel_size, labels,
etc.) For example, to change the relative panel width for the quantity
'slp', run the following:
OPTIONS,'slp','panel_size',1.5
TPLOT calls the routine "SPECPLOT" to make spectrograms and
calls "MPLOT" to make the line plots. See these routines to determine
what other options are available.
Use "GET_DATA" to retrieve the data structure (or
limit structure) associated with a TPLOT quantity.
Use "STORE_DATA" to create new TPLOT quantities to plot.
The routine "DATA_CUT" can be used to extract interpolated data.
The routine "TSAMPLE" can also be used to extract data.
Time stamping is performed with the routine "TIME_STAMP".
Use "CTIME" or "GETTIME" to obtain time values.
tplot variables can be stored in files using "TPLOT_SAVE" and loaded
again using "TPLOT_RESTORE"
CREATED BY: Davin Larson June 1995
FILE: tplot.pro
VERSION: 1.97
LAST MODIFICATION: 02/11/01
$LastChangedBy: davin-win $
$LastChangedDate: 2007-05-04 12:26:58 -0700 (Fri, 04 May 2007) $
$LastChangedRevision: 644 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_2_02/tplot/tplot.pro $
(See ssl_general/tplot/tplot.pro)
COMMON BLOCK: tplot_com WARNING! THIS COMMON BLOCK IS SUBJECT TO CHANGE! DON'T BE TOO SURPRISED IF VARIABLES ARE ADDED, CHANGED, OR DISAPPEAR! data_quants: structure array, handle to location of ALL data. tplot_vars: structure containing all tplot window and plotting information. SEE ALSO: "tplot_options" and "tplot" MODIFIED BY: Peter Schroeder CREATED BY: Davin Larson LAST MODIFICATION: 01/10/08 VERSION: @(#)tplot_com.pro 1.21
(See ssl_general/tplot/tplot_com.pro)
PROCEDURE: tplot_file , name [,filename] PURPOSE: OBSOLETE PROCEDURE! Use "TPLOT_SAVE" and "TPLOT_RESTORE" instead. Store tplot data in a file. gets the data, limits and name handle associated with a name string This procedure is used by the tplot routines. INPUT: name (string, tplot handle) filename: file name KEYWORDS: SAVE: set to save files. RESTORE:set to restore files. SEE ALSO: "STORE_DATA", "GET_DATA", "TPLOT" CREATED BY: Davin Larson LAST MODIFICATION: tplot_file.pro 98/08/06
(See ssl_general/tplot/tplot_file.pro)
PROCEDURE: tplot_keys PURPOSE: Sets up function keys on user keyboard to perform frequent "tplot" functions and procedures. Definitions will be explained when run. INPUT: (none) OUTPUT: (none) CREATED BY: Davin Larson LAST MODIFIED: @(#)tplot_keys.pro 1.5 02/11/22
(See ssl_general/tplot/tplot_keys.pro)
PROCEDURE: tplot_names [, datanames ]
PURPOSE:
Lists current stored data names that can be plotted with the TPLOT routines.
INPUT: (Optional) An string (or array of strings) to be displayed
The strings may contain wildcard characters.
Optional array of strings. Each string should be associated with a data
quantity. (see the "store_data" and "get_data" routines)
KEYWORDS:
TIME_RANGE: Set this keyword to print out the time range for each quantity.
CREATE_TIME: Set to print creation time.
VERBOSE: Set this keyword to print out more info on the data structures
NAMES: Named variable in which the array of valid data names is returned.
ASORT: Set to sort by name.
TSORT: Set to sort by creation time.
CURRENT: Set to display only names in last call to tplot.
EXAMPLE
tplot_names,'*3dp*' ; display all names with '3dp' in the name
CREATED BY: Davin Larson
SEE ALSO: "TNAMES" "TPLOT"
MODS: Accepts wildcards
LAST MODIFICATION: @(#)tplot_names.pro 1.19 01/10/08
(See ssl_general/tplot/tplot_names.pro)
PROCEDURE: tplot_options [,string,value]
NAME:
tplot_options
PURPOSE:
Sets global options for the "tplot" routine.
INPUTS:
string: option to be set.
value: value to be given the option.
KEYWORDS:
HELP: Display current options structure.
VAR_LABEL: String [array], variable[s] to be used for plot labels.
FULL_TRANGE: 2 element double array specifying the full time range.
TRANGE: 2 element double array specifying the current time range.
DATANAMES: String containing names of variable to plot
REFDATE: Reference date. String with format: 'YYYY-MM-DD'.
This reference date is used with the gettime subroutine.
WINDOW: Window to be used for all time plots. (-1 specifies current
window.
VERSION: plot label version. (1 or 2 or 3)
TITLE: string used for the tplot title
OPTIONS: tplot options structure to be passed to replace the current
structure.
GET_OPTIONS:returns the new tplot options structure.
EXAMPLES:
tplot_options,'ynozero',1 ; set all panels to YNOZERO=1
tplot_options,'title','My Data' ; Set title
tplot_options,'xmargin',[10,10] ; Set left/right margins to 10 characters
tplot_options,'ymargin',[4,2] ; Set top/bottom margins to 4/2 lines
tplot_options,'position',[.25,.25,.75,.75] ; Set plot position (normal coord)
tplot_options,'wshow',1 ; de-iconify window with each tplot
tplot_options,'version',3 ; Sets the best time ticks possible
tplot_options,'window',0 ; Makes tplot always use window 0
tplot_options,/help ; Display current options
tplot_options,get_options=opt ; get option structure in the variable opt.
SEE ALSO: "TPLOT", "OPTIONS", "TPLOT_COM"
CREATED BY: Davin Larson 95/08/29
LAST MODIFICATION: 01/10/08
VERSION: @(#)tplot_options.pro 1.16
(See ssl_general/tplot/tplot_options.pro)
PROCEDURE: tplot_panel [,time,y] INPUTS: (optional) time: dblarr of time values associated with a variable to overplot in a designated "tplot" panel. y: array of variable values to be plotted. KEYWORDS: VARIABLE: (string) name of previously plotted tplot variable. OPLOTVAR: Data that will be plotted on top of the selected panel DELTATIME: Named variable in which time offset is returned. PANEL: Returns panel number of designated tplot variable. PSYM: Sets the IDL plot PSYM value for overplot data. PURPOSE: Sets the graphics parameters to the specified tplot panel. The time offset is returned through the optional keyword DELTATIME. LAST MODIFICATION: @(#)tplot_panel.pro 1.9 02/04/17
(See ssl_general/tplot/tplot_panel.pro)
NAME: tplot_positions
PURPOSE:
Return a set of plot positions for tplot.
Given the number of plots, the margins, and the relative
sizes of the plot panels, determine the plot coordinates.
The positions are the device coordinates of the plot, not
of the plot region. (See IDL User's Guide Chapter 14.10)
If the margins are not specifically set, first the limit
structures are checked, then ![x,y].margin are checked,
then some defaults are used.
CALLING SEQUENCE: positions = tplot_positions(panels)
INPUTS: panels: the number of plots, an integer
KEYWORD PARAMETERS: xm,xom,ym,yom: the x and y inner and outer margins
these are two element arrays. ![x,y].margin
and ![x,y].omargin are used if left off
sizes: fltarr(panels) containing the relative plot sizes
OUTPUTS: positions = fltarr(4,n_elements(panels))
positions(*,i) is the ith plot position
(x0,y0,x1,y1)
EXAMPLE:
LAST MODIFICATION: @(#)tplot_positions.pro 1.2 97/05/30
(See ssl_general/tplot/tplot_positions.pro)
PROCEDURE: tplot_quant__define This procedure defines the tplot_quant structure.
(See ssl_general/tplot/tplot_quant__define.pro)
PROCEDURE: tplot_restore ,filenames=filenames, all=all, sort=sort
PURPOSE:
Restores tplot data, limits, name handles, options, and settings.
INPUT:
KEYWORDS:
filenames: file name or array of filenames to restore. If
no file name is chosen and the all keyword is not set,
tplot_restore will look for and restore a file called
saved.tplot.
all: restore all *.tplot files in current directory
append: append saved data to existing tplot variables
sort: sort data by time after loading in
get_tvars: load tplot_vars structure (the structure containing tplot
options and settings even if such a structure already exists
in the current session. The default is to only load these
if no such structure currently exists in the session.
restored_varnames=the tplot variable names for the restored data
SEE ALSO: "TPLOT_SAVE","STORE_DATA", "GET_DATA", "TPLOT"
CREATED BY: Peter Schroeder
LAST MODIFICATION: Added restore_varnames, 19-jun-2007, jmm
(See ssl_general/tplot/tplot_restore.pro)
PROCEDURE: tplot_save , name ,filename=filename, limits=limits
PURPOSE:
Store tplot data in a file.
INPUT:
name: (optional) tplot handle or array of tplot handles to save. If
no name is supplied, tplot_save will save all defined tplot
handles.
KEYWORDS:
filename: file name in which to save data. A default suffix of .tplot or
.lim will be added to this depending on whether the limits
keyword has been set. If not given, the default file name is
saved.tplot or saved.lim.
limits: will save only limits structures. No data will be saved.
SEE ALSO: "STORE_DATA", "GET_DATA", "TPLOT", "TPLOT_RESTORE"
CREATED BY: Peter Schroeder
LAST MODIFICATION: tplot_save.pro 97/05/14
(See ssl_general/tplot/tplot_save.pro)
PROCEDURE: tplot_sort,name PURPOSE: Sorts tplot data by time (or x). INPUT: name: name of tplot variable to be sorted. KEYWORDS: CREATED BY: Peter Schroeder LAST MODIFICATION: %W% %E%
(See ssl_general/tplot/tplot_sort.pro)
PROCEDURE: xlim,lim, [min,max, [log]]
PURPOSE:
To set plotting limits for plotting routines.
This procedure will add the tags 'xrange', 'xstyle' and 'xlog' to the
structure lim. This structure can be used in other plotting routines such
as "SPEC3D".
INPUTS:
lim: structure to be added to. (Created if non-existent)
min: min value of range
max: max value of range
KEYWORDS:
LOG: (optional) 0: linear, 1: log
See also: "OPTIONS", "YLIM", "ZLIM"
Typical usage:
xlim,lim,-20,100 ; create a variable called lim that can be passed to
; a plotting routine such as "SPEC3D".
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)xlim.pro 1.9 02/04/17
(See ssl_general/tplot/xlim.pro)
PROCEDURE: ylim [, str [ , min, max, [ LOG=log ] ] ]
PURPOSE:
Sets y-axis limits for plotting routines.
Adds the tags 'yrange', 'ystyle' and 'ylog' to the structure str, or to the
limit structure associated with the string str.
INPUTS:
str is a:
CASE 1: structure (or zero or non-existent)
Structure to be added to. (Created if non-existent)
CASE 2: string (handle associated with a "TPLOT" variable)
The limits structure associated with this string is used. This
structure can be retrieved with the "GET_DATA" procedure.
min: min value of yrange
max: max value of yrange
KEYWORDS:
LOG: (optional) 0: linear, 1: log
DEFAULT: Sets default tplot limits.
STYLE: value to set the IDL plot YSTYLE keyword
Typical usage:
ylim,lim,-20,100 ; create (or add to) the structure lim
ylim,'Ne',.01,100,1 ; Change limits of the "TPLOT" variable 'Ne'.
NO INPUTS:
ylim ; Set "TPLOT" limits using the cursor.
SEE ALSO: "OPTIONS", "TLIMIT", "XLIM", "ZLIM"
CREATED BY: Davin Larson
VERSION: ylim.pro
LAST MODIFICATION: 01/06/25
(See ssl_general/tplot/ylim.pro)
PROCEDURE: ylimit
PURPOSE: Interactive setting of y-limits for the "TPLOT" procedure.
SEE ALSO: "YLIM", a noninteractive version which calls this routine.
NOTES: This procedure will probably be made obsolete by embedding it in.
"YLIM".
Run "TPLOT" prior to using this procedure.
CREATED BY: Davin Larson
FILE: ylimit.pro
VERSION: 1.11
LAST MODIFICATION: 98/08/06
(See ssl_general/tplot/ylimit.pro)
PROCEDURE: zlim,lim, [min,max, [log]]
PURPOSE:
To set plotting limits for plotting routines.
This procedure will add the tags 'zrange', 'zstyle' and 'xlog' to the
structure lim. This structure can be used in other plotting routines.
INPUTS:
lim: structure to be added to. (Created if non-existent)
min: min value of range
max: max value of range
log: (optional) 0: linear, 1: log
If lim is a string then the limit structure associated with that "TPLOT"
variable is modified.
See also: "OPTIONS", "YLIM", "XLIM", "SPEC"
Typical usage:
zlim,'ehspec',1e-2,1e6,1 ; Change color limits of the "TPLOT" variable
; 'ehspec'.
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)zlim.pro 1.2 02/11/01
(See ssl_general/tplot/zlim.pro)
PROCEDURE: _get_example_dat NAME: _get_example_dat PURPOSE: A procedure that generates sample data for "TPLOT". See the crib sheet: "_tplot_example" for instructions on using this routine. CREATED BY: Davin Larson 96-2-19 FILE: _get_example_dat.pro VERSION: 1.4 LAST MODIFICATION: 96/10/14
(See ssl_general/tplot/_get_example_dat.pro)
DEMONSTRATION OF TPLOT AND RELATED ROUTINES PURPOSE: A sample crib sheet that explains how to use the "TPLOT" procedure. Written by Peter Schroeder 97-9-17
(See ssl_general/tplot/_tplot_demo.pro)
CRIB SHEET EXAMPLE PURPOSE: A sample crib sheet that explains how to use the "TPLOT" procedure. Written by Davin Larson 96-2-19
(See ssl_general/tplot/_tplot_example.pro)