This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
NAME:
auto_downsample
PURPOSE:
Downsamples spectral data to fit a given array and interpolates back
to the original. For specplot.pro in cases where there is a time
variation faster than the time resolution of device pixels. Not
done if n_elements(x_out) > n_elements(x_in)/2, or if dx_out/dx_in
is less than 2.0.
CALLING SEQUENCE:
spec_out = auto_downsample(spec_in, x_in, x_out)
INPUT:
spec_in = a spectrogram, ntimesXnchannels, or nxXny
x_in = x coordinate for input
x_out = x coordinate for output, the default is to use this for
scaling, an interpolate the result back to x_in, the x_out
coordinates are not overwritten
KEYWORDS:
downsample_interp2out = if set, then do not interpolate back to the
input coordinates, but to the output coordinates
HISTORY:
31-aug-2018, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: jimm $
$LastChangedDate: 2019-03-18 11:26:36 -0700 (Mon, 18 Mar 2019) $
$LastChangedRevision: 26846 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/auto_downsample.pro $
(See general/tplot/auto_downsample.pro)
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.
NUMBITS: the number of bits that will be plot
SYMSIZE: set the size of the symbol
$LastChangedBy: spfuser $
$LastChangedDate: 2017-12-19 11:16:22 -0800 (Tue, 19 Dec 2017) $
$LastChangedRevision: 24446 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/bitplot.pro $
(See general/tplot/bitplot.pro)
PROCEDURE: CLEAN_SPIKES, 'name' PURPOSE: Simple routine to remove spikes from tplot data. Clean_spikes smooths the data, then compares each data point with its smoothed value. Given a threshold value of FT (default of 10) and a number of smoothing points (default of 3) if the data value at any point is greater than FT*nsmooth/(nsmooth-1+FT) times the smoothed data point, then the data is reset to NaN. Note that the coefficient FT*nsmooth/(nsmooth-1+FT) is between a value of 1.0 (for FT = 1) and nsmooth (ft -> INF). For the default input the coefficient is 2.5. AUTHOR: unknown, Probably Frank Marcoline KEYWORDS: display_object = Object reference to be passed to dprint for output. new_name = a new name for the despiked variable, the default is to append '_cln' to the input variable name nsmooth = the number of data points for smoothing. The default is 3, will be reset to an odd number prior to smoothing if an even number is passed in. thresh = a threshold value, the default is 10.0 use_nn_median = if set, then do not compare the value of the data point to a smoothed version of itself, instead compare the value data[i] with the median value of the data[i-ns:i+ns], not including the value at data[i] subtract_average = if set, subtract the average value of the data prior to checking for spikes. **This is not recommended for data that is defined to be greater than zero, such as a density or particle count rate. mdeian = passed into the average subtraction. if set, use the median for the subtract_average option. jmm, 4-jul-2007, made to work for negative data, by adding absolute values jmm, 30-jul-2007, Added more error checking jmm, 15-sep-2009, documentation test jmm, 9-mar-2020, Added documentation, fixed absolute value calculation so that mixed positive-negative values are handled correctly. Also added use_nn_median, subtract_average keywords. $LastChangedBy: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: $
(See general/tplot/clean_spikes.pro)
PROCEDURE: copy_data, oldnames, newnames
PURPOSE: to copy a data structure
INPUT:
oldnames: names associated with old data structure
newnames: names 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
$LastChangedBy: ali $
$LastChangedDate: 2020-02-20 12:13:34 -0800 (Thu, 20 Feb 2020) $
$LastChangedRevision: 28324 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/copy_data.pro $
(See 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 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.
XNORM: Set to a named variable to return an array of normalized x
coordinates of each button-click.
YNORM: Set to a named variable to return an array of normalized y
coordinates of each button-click.
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.
Mac Os users:
You might need to set preferences on your X11 display:
Within X11 program go to X11 -> preferences -> Windows: check box labeled "Click=through Inactive Windows"
also: X11 -> preferences -> Input: check box labeled "Emulate three button mouse"
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 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 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 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 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 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.
_EXTRA: Passes the _EXTRA to the AXIS routine when called. Most options that AXIS accepts may be passed to DRAW_COLOR_SCALE
e.g. ytickformat,ytitle,yminor,yticklen,...
CREATED BY: Davin Larson
LAST MODIFIED: 1.17 05/29/07
MODIFIED BY: Patrick Cruce
(See 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 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 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.
TRANGE: named variable to hold the time range (output variable only,
does not affect data returned).
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
$LastChangedBy: davin-mac $
$LastChangedDate: 2019-07-03 16:08:21 -0700 (Wed, 03 Jul 2019) $
$LastChangedRevision: 27404 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/get_data.pro $
(See 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 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 general/tplot/get_ylimits.pro)
NAME:
highlight_time_interval
PURPOSE:
for a given tplot variable, click on a time interval to highlight
using the fill_time_intv option
CALLING SEQUENCE:
highlight_time_interval, tplot_variable, time_interval=time_interval,
color = color, polyfill_options =
polyfill_options, delete=delete
INPUT:
tplot_variable - one or more tplot variables, No input will apply to
all tplot variables.
KEYWORDS:
time_interval - a 2 or 2Xntimes array of time intervals. The default
is to use interactive ctime calls. If interactive,
then n_intervals is used to calculate the number of
time_intervals.
color - a color value or ntimes color values, the default is color
zero, string input is ok, e.g., 'rgb' for three intervals
line_fill - sets polyfill line_fill option, that uses parallel lines
instead of solid color
orientation - angle in degrees for orientation of lines for line_fill
option
linestyle - linestyle for line_fill option
thick - line thickness for line_fill option
n_intervals - used for cases with no time inputs, for number of
intervals to choose interactively.
delete - delete highlights.
refresh - call tplot to show the intervals
NOTES:
The same intervals are applied to each of the input tplot variables
$LastChangedBy: jimm $
$LastChangedDate: 2019-11-15 11:20:05 -0800 (Fri, 15 Nov 2019) $
$LastChangedRevision: 28023 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/highlight_time_interval.pro $
(See general/tplot/highlight_time_interval.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 general/tplot/iton.pro)
NAME: join_vec.pro
PURPOSE: Take a series of similar variables and store as a single vector;
e.g. one dimensional variables Vp_x, Vp_y, vp_z can be combined to
form a three dimensional variable Vp.
CALLING SEQUENCE:
join_vec, 'thm_state_pos'+['_x','_y','_z'], 'thm_state_pos_new'
ARGUMENTS:
NAMES: Array of tplot variable names to be joined into single variable
NEW_NAME: Single string containing the name of the tplot variable to be created
IGNORE_DLIMITS: Set this flag to ignore warnings about dlimits (meta data)
KEYWORDS
display_object = Object reference to be passed to dprint for output.
NOTES: Meant to compliment split_vec.pro
(See general/tplot/join_vec.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 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
$LastChangedBy: davin-mac $
$LastChangedDate: 2020-02-21 16:42:35 -0800 (Fri, 21 Feb 2020) $
$LastChangedRevision: 28332 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/mplot.pro $
(See general/tplot/mplot.pro)
PROCEDURE mplot_downsample_data, max_points, x, y
PURPOSE:
Enables fast plotting of time series plots with many elements.
This function is intended for use when plotting time series plots using
MPLOT. When n_elements >> number of pixels on the screen, the large number
of points slows down plotting considerably without adding any visual
information to the final plot.
This procedure groups the data into regularly spaced time intervals. If
MAX_POINTS is set correctly (see below), each interval is less than a pixel
in the plot. The procedure finds the minimum and maximum value of the
time series in that interval, and constructs a new time series from the
minima and maxima. The new series has many fewer points than the original
(and therefore the plotting runs much faster), but the resulting plot is
nearly visually identical to the full time series plot.
If the number of input points is smaller than MAX_POINTS, the function does
nothing.
This should not be used as a 'real' downsampling procedure to make a new
time series that can be used for calculations at a reduced cadence--use
only for plotting.
Works best with regularly spaced data that is plotted without a plot
symbol set.
INPUT:
MAX_POINTS: The maximum number of points in the downsampled array.
Set to a number that is several times larger than the maximum pixel
width of the plot window (something like 10000 gives more than enough
points for nearly any display, and plots nearly instantly). If the
number of input points is smaller than max_points, the function does
nothing.
For TPLOT variables, set 'max_points' using the OPTIONS procedure.
X: The time array.
Y: The data array.
KEYWORDS:
DY: Optional uncertainty in y.
CREATED BY:
pulupa
$LastChangedBy: pulupalap $
$LastChangedDate: 2018-06-08 15:15:49 -0700 (Fri, 08 Jun 2018) $
$LastChangedRevision: 25339 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/mplot_downsample_data.pro $
(See general/tplot/mplot_downsample_data.pro)
PROCEDURE: MPLOT_SYMLOG
PURPOSE: Draws a tplot variable with a bi-symmetric log y-axis
that allows to display both positive and negative
values in log scale.
In general, it is assumed to be only used as follows:
IDL> options, 'tplot name', tplot_routine='mplot_symlog'
In the current version, it can only draw multi-line plots.
INPUTS: Tplot data and settings same to 'mplot'.
KEYWORDS:
DATA: A structure that contains the elements 'x', 'y', and ['dy'].
(used by 'tplot').
LIMITS: A structure that contains any combination of the following elements:
All PLOT/OPLOT keywords (i.e., psym, symsize, linestyle, colors, etc.)
CREATED BY: Takuya Hara on 2016-09-27.
LAST MODIFICATION:
$LastChangedBy: egrimes $
$LastChangedDate: 2019-10-08 11:11:53 -0700 (Tue, 08 Oct 2019) $
$LastChangedRevision: 27831 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/mplot_symlog.pro $
(See general/tplot/mplot_symlog.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 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
$LastChangedBy: ali $
$LastChangedDate: 2019-05-14 14:18:26 -0700 (Tue, 14 May 2019) $
$LastChangedRevision: 27232 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/options.pro $
(See general/tplot/options.pro)
Procedure: plotxy
Purpose: Takes an array of 3-d(Nx3) vectors or tplot variable
and plots them using 2-d plots to help visualize them.
It can also take an MxNx3 array tplot variable storing
an MxNx3 array which represents a set of M lines with N
points
Can also accept an Nx2 or an MxNx2 element array...if this
is done the versus argument should not use a custom
designation or the z-axis, as it assumes 2-d vectors are in
the x-y plane, and thus will distort the vectors upon projection.
plotxy/tplotxy plots can be interleaved on the same window
with plotxyz & plotxyvec plots
Calling tplotxy with no arguments to redraw the entire
window(including plotxyz,plotxyvec plots)
***************************************************
Using custom axes: If you use two vectors to define custom
axes, the procedure will generate a plot of the data vectors
projected into a plane defined by the span of the two custom
vectors. The x-axis will be the first vector, the y axis
will be the second vector. This means that if the custom
vectors are not orthogonal the plot will show a distortion.
You can think of this as plotting along a plane that slices
though the 3-d space.
********************************
Plot windows and panels:
using, /overplot,/addpanel,/noisotropic and multi=
To put multiple panels in a window first call
plotxy with the multi keyword. It will either
plot in which ever window is your current one, or
create a new one if no window exists or if you
request the use of a nonexistent window.
During this first call you may want to specify things
like wtitle,xsize,ysize,window...in addition to your normal
plotting options. However,Calling window options will interfere with
the creation of postscripts.
multi specifies the plot window panel layout.
So if you set multi='3,2' you will get 6 plots
in your window with a layout like:
-------
|x x x|
|x x x|
-------
Each panel will have dimensions x number of pixels = 1/3 *
xsize of window and y number of pixels = 1/2 * ysize of window.
Your first call should also specify the layout of your
first panel. To add to that panel use the /overplot keyword.
If you wish to add an overall title and/or margins to your multi panel
window your first call should also specify mtitle and/or mmargin.
When you use the /add keyword the program will move on to
the next panel within the plot window and you should add
options to specify the layout of that panel.
If you set the xmargin or ymargin keyword the margin will be
relative to the overall size of that panel. When using the
not using the noisotropic keyword the procedure will make
each axis vary over the same range AND make the
largest possible square window given the size of the panel
and the sizes of the margins you have provided, if possible.
In some cases when ranges are set explictly the plot must
be rectangular.
An entire plot window is filled in sequence, if you move
on to a new window you will not be able to go back to the
previous panel without restarting.
It is possible use a panel out of sequence by setting mpanel.
mpanel also allows you to create non symmetric layouts by
creating plots that take up more than one panel.
If you call plotxy with no arguments it will redraw the
entire window including all panels and overplots. If you
resize the window before calling with new arguments it
will redraw the isotropic panels as the largest possible
squares. This comes at a cost of storing copies of the
commands and data you made in memory. If you need to save
memory you can call the function with the /memsave argument,
but then redraws will be done using hardware and window resizes
can distort isotropic plots.
NOTE TO PROGRAMMERS:
Information about plotting for plotxy is stored in
the global variable !TPLOTXY, this includes
information about the layout of the plot window
which panel it is currently working on, and the
sequence of commands used to generate current plot window
so that it can regenerate the plotwindow when called
with no arguments. This variable also stores information
used by the plotxyz function so spectrographic xyz plots
can be interleaved with xy line plots.
Example: a = [[dindgen(10)],[dindgen(10)],[dindgen(10)]]
get_data,'thb_state_pos',data=d
dat=d.y
plotxy
plotxy,a
plotxy,a,versus='yzr'
plotxy,dat,versus='cc',custom=transpose([[1,1,0],[0,0,1]])
plotxy,dat,versus='xryz',xrange=[0,10],yrange=[0,10]
Note: Recommend using the keyword /noiso if you're wondering why your plot has a weird aspect ratio.
Inputs: vectors(optional): an Nx3,MxNx3,Nx2, or MxNx2 list
Keywords:
versus(optional): specify the projection to be used, can be
'xx','xy','xz','yx','yy','yz','zx','zy','zz','cc' you can also
follow a letter with an 'r' to reverse the axis(goes from
positive to negative instead of from negative to positive)
if you specify 'cc','crc'...that indicate you want to use a
custom projection
example: 'xry' will be an xy plot with the maximum x value
listed on the left and the minimum on the right
(default:'xy')
custom(optional): set this variable to a
2x3 matrix whose columns define a plane in 3-d space, to define a
custom projection. In other words the 2-d plot will be a
plot of the vectors passed into plotxy when they are
projected into a plane defined by
span(custom[0,*],custom[1,*]). (span is defined as the set
of all the linear combinations of two vectors, or
span(x,y) = {mx+ny:m = element of the reals, n = element of
the reals} The vectors used to define this plane will be
relative to whatever 3-d coordinate system the input vector
data is in.
So if the call:
tplotxy,'somedata',versus='cc',custom=transpose([[1,1,0],[0,0,1])
is made, the plot generated will be of the vectors closest
to the data vectors that are inside a vertical plane whose
intersection with the x-y plane forms a line y=x.
tplotxy,'somedata',versus='cc',custom=transpose([[1,0,0],[0,1,0])
is effectively the same as:
tplotxy,'somedata',versus='xy'
overplot(optional): set this keyword if you want to plot
on the last plot and panel that you plotted on
addpanel(optional): set this keyword if you want to plot on a new
panel within the same plot window as where you last
plotted. This will go to the next column first and if it is
at the end of a row, to the next row.
multi(optional): set this keyword to a string that
specifies the layout of panels within a plotwindow. Set
this keyword only the first time you call tplotxy for a
given plotwindow. Each time you set it, the previous
contents of the window will be erased. You can separate
the two elements with a variety of different delimiters
The first element is columns left to right, the second rows
top to bottom. Append an 'r' to the elements to have it
reverse the direction of panel application
Examples: multi= '2 3'
multi= '5r,7'
multi=' 1:6r'
.....
mmargin(optional, can only be used if multi is also specified):
set this keyword to a 4 element array specifying margins to be left
around a multipanel plot. Element order is bottom, left, top, right.
Margins are specified relative to the overall size of the window:
0.0 is no margin, 1.0 is all margin.
e.g. mmargin=[0.1,0.1,0.15.0.1]
mtitle(optional, can only be used if multi is also specified):
set this keyword to a string to display as a title for a multi panel
plot window. This is displayed in addition to any titles specified for
individual panels.
If the top mmargin = 0, or has not been set then it will be set at 0.05
to allow room for the title.
It is not possible to set your own font size for the mtitle. The size is
chosen so that as much as possible the title fits in the top margin and
is not too long for the window. Setting a larger top mmargin will
increase the font size. NB: Size is fixed you are saving your plot
to a postscript. If you require more control over the title format
try leaving space using mmargin and adding your own text with idl
procedure XYOUTS.
mpanel(optional, can only be used if multi is also specified):
set this keyword to a string to specify which panels in a multipanel window
to plot to. This allows you to create non symmetric plot layouts in a multi
panel window.
mpanel must contain two numbers separated by a comma (col, row) or two ranges
indicated with a colon, separated by a comma.
Panels are numbered starting at 0, from top to bottom and from
left to right.
e.g. mpanel = '0,1' will plot to panel in the first column,
second row;
mpanel = '0:1,0' will create a plot that takes up both the first
and second columns in the first row.
You cannot plot to a panel if that panel has already been used.
Panels in a window are normally filled from left to right, top to bottom. You
can use mpanel to place a plot out of this standard sequence.
noisotropic(optional): set this keyword if you don't want the
scaling of both axes to be the same and the space to
be perspective corrected so that a cm of y unit takes
up the same space on the screen as a cm of x unit
xistime(optional): set this keyword if you want to treat the x-axis
as a time axis and use tplot-style time labels
memsave(optional): set this keyword to request command
copies not be saved and redraws be done without maintaining
square isotropic plots. Setting this option can potentially
save quite a lot of memory.
linestyle(optional):set this to change the linestyle used
0 = default,1=dotted=,2=dashed,3=dash dot,4=dash dot
dot,5=long dashes
xrange(optional): set this to a 2 element array to specify
the min and max for the first axis(x) of the 2-d plot
yrange(optional): set this to a 2 element array to specify
the min and max for the second axis(y) of the 2-d plot
pstart(optional): set this keyword to a number representing
the symbol you would like to start lines with. (This works
like the idl psym keyword, but only for the first symbol
in a line being plotted)
startsymcolor(optional): Set this keyword to a color table number
or letter(e.g. 'm') to control the color of the pstart symbol separately
from the color= keyword
pstop(optional): set this keyword to a number representing
the symbol you would like to end lines with. (This works
like the idl psym keyword, but only for the last symbol
in a line being plotted)
; stopsymcolor(optional): Set this keyword to a color table number
or letter(e.g. 'm') to control the color of the pstop symbol separately
from the color= keyword
psym(optional): use this to plot the line using a symbol
rather than a line.
symsize(optional): specify the size of the start and end
symbol or psym. (default:1.0)
WARNING: setting any of the 4 windowing options below
will interfere with postscripts
window(optional):specify the window for
output, if overplot is not specified, it will
always recreate the window so it can attempt to make
the window square (default:current)
xsize(optional):specify the xsize of the window in
pixels(default: current)
ysize(optional):specify the ysize of the window in pixels
(default: current)
wtitle(optional):the title you would like the window to have
colors(optional): if vectors in Nx3 colors should contain a
single element(name like 'r' or index like 2), if vectors is
an MxNx3 then it can contain a single element or M elements
xmargin(optional): set this option to a two element array
specifing the size of the margin of the current panel
relative to the size of overall panel on the x dimension.
Values range from 0.0(no margin) to 1.0(all margin)
The first element of the array is the left margin
The second element is the right margin
ymargin(optional): set this option to a two element array
specifing the size of the margin of the current panel
relative to the size of overall panel on the y dimension.
Values range from 0.0(no margin) to 1.0(all margin)
The first element of the array is the bottom margin and
The second element of the array is the top margin
xlog(optional): set the x scale to be logarithmic
ylog(optional): set the y scale to be logarithmic
xtitle(optional): set the xtitle for the plot
ytitle(optional): set the ytitle for the plot
grid(optional): set this to 1 to have the procedure
generate a grid rather than normal tickmarks
units(optional): set this if you want this unit label
appended to both axis titles.(This will be ignored if
you set the xtitle or ytitle explictly)
labels(optional): set this if you want to use the axis
labels array from limits/dlimits of a tvar.(This will be
ignored if you set the xtitle or ytitle explictly)
; markends: This keyword is deprecated. You can use
all the normal options for plot to manipulate the
position of the ticks on the axes.
xtick_get,ytick_get: These behave exactly as the plot
command versions, but they had to be identified explictly
to ensure they would be passed through correctly.
replot(internal): this option is used in recursive calls
by the routine to itself and should never be set by the
user
This function also takes normal idl keywords that effect
plotting style(things like xtitle,ytitle....etc..)
get_plot_pos=get_plot_pos: Return the normalized position of your plot.
Output will be a 4-element array [x1,y1,,x2,y2]
Where (x1,y1) is the lower-left corner of your plot and
(x2,y2) is the top right corner of your plot.
SEE ALSO:
plotxyz,tplotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz
plotxylib,plotxyvec
$LastChangedBy: pcruce $
$LastChangedDate: 2008-01-16 16:54:40 -0800 (Wed, 16 Jan 2008) $
$LastChangedRevision: 2283 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $
(See general/tplot/plotxy.pro)
Procedure: plotxylib
Purpose: A library of helper functions for plotxy, plotxyz, and plotxyvec.
To make the library available for a routine just call: plotxylib
That will force all the routines to be compiled.
pxy_set_state sets the state of !TPLOTXY which keeps track
of windowing information for the plotxy* routines. pxy_push_state
pushes arguments to these routines onto a data structure that allows
them to be replot without retyping the arguments. pxy_replot will
replot a series of calls from memory. pxy_get_pos will calculate
the position and shape of a window from the windowing information
in !TPLOTXY and the requested data ranges and margins for a window.
pxy_set_window is a routine that houses some redundant
initialization code.
SEE ALSO: plotxy,plotxyz,plotxyvec
$LastChangedBy: lphilpott $
$LastChangedDate: 2011-05-26 11:53:59 -0700 (Thu, 26 May 2011) $
$LastChangedRevision: 8701 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/plotxylib.pro $
(See general/tplot/plotxylib.pro)
Procedure: plotxyvec
Purpose: Plots a set of arrows on an image generated with
plotxy,tplotxy or, plotxyz this is a pretty simple wrapper
for the idl arrow routine. The major difference is that
this routine stores a history so that you can autoreplot it
This routine will take any of the options that the normal
arrows routine takes, with one exception. plotxyvec must
always use data coordinates.
Examples:
plotxyvec,xy,dxy
plotxyvec,xy,dxy,/grid,multi='2,1'
plotxyvec,xy,dxy,/grid,/addpanel,xticks=5
Arguments: xy: an Nx2 array that contains the starting coordinates of the arrows
dxy: an Nx2 array that contains the offset from each
starting coordinate to the end of the arrow
(They argument can be MxNx2 or JxMxNx2 ... the main requirement is that the last
dimension be 2)
Keywords:
noisotropic:Set this keyword if you want the plot to not be isotropic
overplot: set this keyword if you want to plot
on the last plot and panel that you plotted on
addpanel: set this keyword if you want to plot on a new
panel within the same plot window as where you last
plotted. This will go to the next column first and if it is
at the end of a row, to the next row.
multi: set this keyword to a string that
specifies the layout of panels within a plotwindow. Set
this keyword only the first time you call tplotxy for a
given plotwindow. Each time you set it, the previous
contents of the window will be erased. You can separate
the two elements with a variety of different delimiters
The first element is columns left to right, the second rows
top to bottom. Append an 'r' to the elements to have it
reverse the direction of panel application
Examples: multi= '2 3'
multi= '5r,7'
multi=' 1:6r'
.....
mmargin(optional, can only be used if multi is also specified):
set this keyword to a 4 element array specifying margins to be left
around a multipanel plot. Element order is bottom, left, top, right.
Margins are specified relative to the overall size of the window:
0.0 is no margin, 1.0 is all margin.
e.g. mmargin=[0.1,0.1,0.15.0.1]
mtitle(optional, can only be used if multi is also specified):
set this keyword to a string to display as a title for a multi panel
plot window. This is displayed in addition to any titles specified for
individual panels.
If the top mmargin = 0, or has not been set then it will be set at 0.05
to allow room for the title.
It is not possible to set your own font size for the mtitle. The size is
chosen so that as much as possible the title fits in the top margin and
is not too long for the window. Setting a larger top mmargin will
increase the font size. NB: Size is fixed you are saving your plot
to a postscript. If you require more control over the title format
try leaving space using mmargin and adding your own text with idl
procedure XYOUTS.
mpanel(optional, can only be used if multi is also specified):
set this keyword to a string to specify which panels in a multipanel window
to plot to. This allows you to create non symmetric plot layouts in a multi
panel window.
mpanel must contain two numbers separated by a comma (col, row) or two ranges
indicated with a colon, separated by a comma.
Panels are numbered starting at 0, from top to bottom and from
left to right.
e.g. mpanel = '0,1' will plot to panel in the first column,
second row;
mpanel = '0:1,0' will create a plot that takes up both the first
and second columns in the first row.
You cannot plot to a panel if that panel has already been used.
Panels in a window are normally filled from left to right, top to bottom. You
can use mpanel to place a plot out of this standard sequence.
xistime(optional): set this keyword if you want to treat the x-axis
as a time axis and use tplot-style time labels
[xy]range: The desired range of your plot on a particular axis. By default
this routine will not display any arrows that start or end outside this range.
Use noclip, nostartclip, nostopclip, or clip. To display clipped arrows.
[xy]margin: The desired margin for the plot on the left/right(x) axis
or the top/bottom(y) axis. This is specified as a proportion of
the overall plot window.(ie from 0.0 to 1.0)
grid: Set this option to draw a grid on the output
window: Set a specific window number to plot in.
[xy]size: The size in pixels of the window you want to plot
wtitle: The title of the window
uarrowside: A string storing the side on which the unit arrow should be drawn.
Can be: 'left','right','top','bottom','none'
uarrowoffset: The distance of the arrow from the edge of the plot. This is
specified as a proportion of the size of the plot. (By default it is .2 for left/right
arrows and .05 for top/bottom arrows
uarrowtext: Any text to be drawn after the number of data units the arrow represents.
This is usually used to indicate the units.
uarrowdatasize: The number of data units that the unit arrow should represent.
arrowscale: The ratio between the coordinate system of the
start points(xy) and the coordinate system of the offsets.(dxy)
(default:1.0)
xtick_get,ytick_get: These behave exactly as the plot
command versions, but they had to be identified explictly
to ensure they would be passed through correctly.
hsize: This scales the head size of the arrow. This is basically like the hsize argument
to arrow, except it is a normalized value instead of a fraction of !D.x_size.
clip: allows the user to set clipping to a particular bounding box.
either set /clip to clip to the current x,y range or set clip equal to q
a 4 element array with elements [x0,y0,x1,x2] specifying the corners of
the bounding box
startclip: clip xy, but not dxy
stopclip: clip dxy, but not xy
color: Set the color of the arrows. Can use color indexes or letters('b','g'...)
This does not currently allow you to set separate colors for separate arrows in
a single call.
Replot: For internal use only
All Other Keywords: See IDL documentation for arrow.pro,plot.pro, this routine
accepts most of the arguments to these routines through _extra
get_plot_pos=get_plot_pos: Return the normalized position of your plot.
Output will be a 4-element array [x1,y1,,x2,y2]
Where (x1,y1) is the lower-left corner of your plot and
(x2,y2) is the top right corner of your plot.
Notes: If the arrows are overplotted, the routine will use the
x,y range of the previous plot, by default.
The unit arrow will only be drawn automatically when using isotropic plots.
If you'd like the routine to draw two unit arrows when using nonisotropic plots,
to indicate the scaling in each direction, please request the feature.
Arrows that start or end outside of the user defined xrange,yrange will be clipped
by default. Use noclip, nostartclip, nostopclip, or clip. Clipping clips the apparent
range. So if the arrows are enlarged by uarrowscale, they may be clipped; even if the
data values they represent are in range.
********************************
Plot windows and panels:
using, /overplot,/addpanel,/noisotropic and multi=
To put multiple panels in a window first call
plotxy with the multi keyword. It will either
plot in which ever window is your current one, or
create a new one if no window exists or if you
request the use of a nonexistent window.
During this first call you may want to specify things
like wtitle,xsize,ysize,window...in addition to your normal
plotting options. However,Calling window options will interfere with
the creation of postscripts.
multi specifies the plot window panel layout.
So if you set multi='3,2' you will get 6 plots
in your window with a layout like:
-------
|x x x|
|x x x|
-------
Each panel will have dimensions x number of pixels = 1/3 *
xsize of window and y number of pixels = 1/2 * ysize of window.
Your first call should also specify the layout of your
first panel. To add to that panel use the /overplot keyword.
When you use the /add keyword the program will move on to
the next panel within the plot window and you should add
options to specify the layout of that panel.
If you set the xmargin or ymargin keyword the margin will be
relative to the overall size of that panel. When using the
not using the noisotropic keyword the procedure will make
each axis vary over the same range AND make the
largest possible square window given the size of the panel
and the sizes of the margins you have provided, if possible.
In some cases when ranges are set explictly the plot must
be rectangular.
An entire plot window must be filled in sequence, if you move
on to a new window you will not be able to go back to the
previous window without restarting.
If you call plotxy with no arguments it will redraw the
entire window including all panels and overplots. If you
resize the window before calling with new arguments it
will redraw the isotropic panels as the largest possible
squares. This comes at a cost of storing copies of the
commands and data you made in memory. If you need to save
memory you can call the function with the /memsave argument,
but then redraws will be done using hardware and window resizes
can distort isotropic plots.
NOTE TO PROGRAMMERS:
Information about plotting for plotxy is stored in
the global variable !TPLOTXY, this includes
information about the layout of the plot window
which panel it is currently working on, and the
sequence of commands used to generate current plot window
so that it can regenerate the plotwindow when called
with no arguments. This variable also stores information
used by the plotxyz function so spectrographic xyz plots
can be interleaved with xy line plots.
See Also:
plotxy.pro,tplotxy.pro,plotxyz.pro,plotxylib.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2013-08-23 17:25:01 -0700 (Fri, 23 Aug 2013) $
$LastChangedRevision: 12887 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/plotxyvec.pro $
(See general/tplot/plotxyvec.pro)
Procedure: plotxyz
Purpose: Generates an isotropic spectrographic plot. It takes one
2-d array(Z) and plots it using the values in 2 1-d arrays(X,Y) to
scale the data in Z. The X and Y axes can be any kind of data,
most specifically the X axis need not be time. By default the
plots, are scaled isotropically. Meaning that a unit on the x axis
will have the same length on the screen as a unit on the z axis.
The plots can be interleaved with plotxy/tplotxy plots in the same
panel/window. Calling plotxyz with no arguments will redraw the
entire window(including plotxy/tplotxy plots)
The most significant restiction to this function is that it will
clip any negative(or 0) data(in X,Y or Z) if you select a
logarithmic axis.
If one scaling axis is set to logarithmic and the other is not,
but the plot is set to isotropic, 1 power unit on the logarithmic
axis will take up the same space on screen as one normal unit on
the normal axis. Despite the capability to perform these mixed
x,y log plots, this is not recommended...but feel free to experiment.
************************************
Detailed explanation of Plot windows and panels:
/addpanel,/noisotropic and multi=
To put multiple panels in a window first call
plotxyz with the multi keyword. It will either
plot in which ever window is your current one, or
create a new one if no window exists or if you
request the use of a nonexistent window.
During this first call you may want to specify things
like wtitle,xsize,ysize,window...in addition to your normal
plotting options, setting these windowing options will
interfere with the creation of postscript
multi specifies the plot window panel layout.
So if you set multi='3,2' you will get 6 plots
in your window with a layout like:
-------
|x x x|
|x x x|
-------
Each panel will have dimensions x number of pixels = 1/3 *
xsize of window and y number of pixels = 1/2 * ysize of window.
Your first call should also specify the layout of your
first panel. To add to that panel use the /overplot keyword.
If you wish to add an overall title and/or margins to your multi panel
window your first call should also specify mtitle and/or mmargin.
When you use the /add keyword the program will move on to
the next panel within the plot window and you should add
options to specify the layout of that panel.
If you set the xmargin or ymargin keyword the margin will be
relative to the overall size of that panel. When using the
not using the noisotropic keyword the procedure will make
each axis vary over the same range AND make the
largest possible square window given the size of the panel
and the sizes of the margins you have provided, if possible.
In some cases when ranges are set explictly the plot must
be rectangular.
An entire plot window must be filled in sequence, if you move
on to a new window you will not be able to go back to the
previous panel without restarting.
It is possible use a panel out of sequence by setting mpanel.
mpanel also allows you to create non symmetric layouts by
creating plots that take up more than one panel.
If you call plotxyz with no arguments it will redraw the
entire window including all panels and overplots. If you
resize the window before calling with new arguments it
will redraw the isotropic panels as the largest possible
squares. This comes at a cost of storing copies of the
commands and data you made in memory. If you need to save
memory you can call the function with the /memsave argument,
but then redraws will be done using hardware and window resizes
can distort isotropic plots.
NOTE TO PROGRAMMERS:
Information about plotting for plotxyz is stored in
the global variable !TPLOTXY, this includes
information about the layout of the plot window
which panel it is currently working on, and the
sequence of commands used to generate current plot window
so that it can regenerate the plotwindow when called
with no arguments. This variable also stores information
used by the plotxy function so line plots
can be interleaved with xyz spectrographic plots.
Required Inputs:
x: 1-d array specifying the scaling/spacing of the x axis
This array must have the same number of elements as the
1st dimension of Z. One can think of the x coordinates of
the centers of the Z array data
y: 1-d array specifying the scaling/spacing of the y axis
This array must have the same number of elements as the
2nd dimension of Z. One can think of the y coordinates of
the centers of the Z array data
z: 2-d array specifying the intensity of each element, or the
height of the z-axis. This will be represented by color
in the 2-d plot this procedure generates.
Optional keywords:
interpolate: set this argument if you want the data to
be interpolated between z data. This will give the
appearance of smooth gradations, although this may not
exist in the data. If your Z data has blanks(NaNs),
interpolation can give inaccurate results near the blanks.
noisotropic: set this argument if you don't want
the plot to be isotropic. If this is set the plot
will fill the entire space available to it,
regardless of data scaling.
xistime: Set this argument to use tplot-style time formatting
for x-axis labels.
xlog,ylog,zlog: set any of these to create logarithmic
scaling on the appropriate axis. It is recommended,
but not required that if you set xlog on an isotropic
plot you also set ylog.
multi: as explained above set this to a string
indicating the desired number of columns and rows
in your window. This string can must contain 2 numbers
delimited by any common delimiter character or space.
the numbers may optionally be followed by an r to
indicate a reversal in the direction that the plots
will be added to the window.
mmargin(can only be used if multi is also specified):
set this keyword to a 4 element array specifying margins to be left
around a multipanel plot. Element order is bottom, left, top, right.
Margins are specified relative to the overall size of the window:
0.0 is no margin, 1.0 is all margin.
e.g. mmargin=[0.1,0.1,0.15.0.1]
mtitle(can only be used if multi is also specified):
set this keyword to a string to display as a title for a multi panel
plot window. This is displayed in addition to any titles specified for
individual panels.
If the top mmargin = 0, or has not been set then it will be set at 0.05
to allow room for the title.
It is not possible to set your own font size for the mtitle. The size is
chosen so that as much as possible the title fits in the top margin and
is not too long for the window. Setting a larger top mmargin will
increase the font size. NB: Size is fixed you are saving your plot
to a postscript. ] If you require more control over the title format
try leaving space using mmargin and adding your own text with idl
procedure XYOUTS.
mpanel(can only be used if multi is also specified):
set this keyword to a string to specify which panels in a multipanel window
to plot to. This allows you to create non symmetric plot layouts in a multi
panel window.
mpanel must contain two numbers separated by a comma (col, row) or two ranges
indicated with a colon, separated by a comma.
Panels are numbered starting at 0, from top to bottom and from
left to right.
e.g. mpanel = '0,1' will plot to panel in the first column,
second row;
mpanel = '0:1,0' will create a plot that takes up both the first
and second columns in the first row.
You cannot plot to a panel if that panel has already been used.
Panels in a window are normally filled from left to right, top to bottom. You
can use mpanel to place a plot out of this standard sequence.
addpanel: set this keyword to make the procedure
move on to the next plot in window, if you have
previously set multi. If this is not set, it will
generate a new plot in a clear window, if this is
set and there are no more available spaces for
plots an error will be generated.
memsave: To allow replotting of the data when the
procedure is called with no arguments, the copies of
the data are stored in memory. If memsave is set
these copies will not be saved and you will be unable
to replot with a 0 argument call.
xmargin,ymargin: Set these keyword to a 2 element
array to set extra space around the plot. Margins are
measured proportionally(from 0.0 to 1.0) and are
separate for each plot(not global to the entire window).
The arrays store the [left,right] xmargin or
[bottom,top] ymargin. Default xmargin for xyz plots is
[.15,.15] and ymargin is [.1,.075].
xrange,yrange,zrange: Set these keywords to a 2 element
array to control the range of values to be displayed
for each axis.
title: set this to a string indicating the title at
the top of the plot
xtitle,ytitle,ztitle: set this to a string indicating
the title of the appropriate axis.
charsize: set this to a number to scale the character
size of writing on the plot. 1.0 is the default,
less than 1.0 decreases charsize, greater increases.
WARNING setting window, xsize, ysize or wtitle will
interfere with the creation of postscript
window: specify the window in which the plots should be
made. The default is the current window. If the window
number does not exist one will be made
xsize,ysize: Specify the number of pixels of the window you are
plotting in. This can be done ahead by the user if they
like, or just by stretching the window.
wtitle: Specify the title for the bar at the top of the
window as a string.
noticks: set this if you do not want ticks on the plot
(mutually exclusive with grid)
grid: set this if you want a grid on your plot
(mutually exclusive with noticks)
Use xticks and yticks to manipulate the
spacing of your grid
markends: This keyword is deprecated. You can use
all the normal options for plot to manipulate the
position of the ticks on the axes.
xtick_get,ytick_get: These behave exactly as the plot
command versions, but they had to be identified explictly
to ensure they would be passed through correctly.
zticks: this acts like the normal x,y ticks option in
idl plots. Set it to some number greater than 1 to set
the number of tick marks of the z axis. It is available
because draw color scale will sometimes supress all the
tick marks on the z axis.
ps_resolution: set the resolution, if you are using
postscript (default is 150 pts/cm)
no_color_scale: Set to not draw the z-axis color scale
get_plot_pos=get_plot_pos: Return the normalized position of your plot.
Output will be a 4-element array [x1,y1,,x2,y2]
Where (x1,y1) is the lower-left corner of your plot and
(x2,y2) is the top right corner of your plot.
You can also use many normal plot options.
NOTES:
All NaN's & INFs in the x and y axes will be removed from the data. All
NaN's in the z data will be replaced by the minimum value.
bin2d is VERY useful for preparing data for use in this routine
Be very careful when manually setting the ticks. While some options like [xy]ticks
are quite safe, others can inadvertently produce inaccurate labels as idl will sometimes
make assumptions about positioning of axes, by rounding off. If you plan on using [xy]tickv,
or [xy]style be careful to verify that the axis labeling is working correctly. This can best be done by
testing on a data set where the axes are irregularly spaced and where some of the values at the axes are
irrational.
SEE ALSO:
plotxy,tplotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz,bin2d,
plotxylib,plotxyvec
$LastChangedBy: pcruce $
$LastChangedDate: 2008-01-16 16:54:40 -0800 (Wed, 16 Jan 2008) $
$LastChangedRevision: 2283 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $
(See general/tplot/plotxyz.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 general/tplot/pmplot.pro)
PROCEDURE: skip
PURPOSE:
Shifts the tplot plotting window forward/backward by a number of
orbits, days, hours, minutes, seconds, or "pages". A page is
defined as the currently displayed time range.
USAGE:
skip, n
INPUTS:
n: Number of orbits, days, hours, minutes, seconds, or pages
(positive or negative) to shift. Default = +1. Normally,
this would be an integer, but it can also be a float.
KEYWORDS:
PAGE: (Default) Shift in units of the time range currently displayed.
This keyword and the next 5 define the shift units. Once you
set the units, it remains in effect until you explicitly select
different units.
DAY: Shift in days.
HOUR: Shift in hours.
MINUTE: Shift in minutes.
SEC: Shift in seconds.
ORB: Shift in orbits. Currently only works for MAVEN.
FIRST: Go to the beginning of the loaded time range and
plot the requested interval from there. Do not
collect $200.
LAST: Go to end of loaded time range and plot the requested
interval from there.
PERI: If keyword FIRST or LAST is set, then go to first or last
periapsis and plot the requested interval from there.
Shift units are assumed to be orbits.
APO: If keyword FIRST or LAST is set, then go to first or last
apoapsis and plot the requested interval from there.
Shift units are assumed to be orbits.
$LastChangedBy: dmitchell $
$LastChangedDate: 2020-03-21 14:50:22 -0700 (Sat, 21 Mar 2020) $
$LastChangedRevision: 28449 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/skip.pro $
CREATED BY: David L. Mitchell
(See general/tplot/skip.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.
DX_GAP_SIZE = Maximum time gap over which to interpolate the plot. Use this
keyword when overlaying spectra plots, allowing the underlying spectra to
be shown in the data gaps of the overlying spectra. Overrides value set
by DATAGAP in dlimits. Note: if either DX_GAP_SIZE or DATAGAP is set to
less than zero, then the 20 times the smallest delta x is used.
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: jimm $
$LastChangedDate: 2018-09-07 13:24:55 -0700 (Fri, 07 Sep 2018) $
$LastChangedRevision: 25744 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/specplot.pro $
(See 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:
inset: a string to be inserted in the new variable names before the suffix
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
display_object = Object reference to be passed to dprint for output.
OUTPUTS:
OPTIONAL OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
EXAMPLE:
LAST MODIFICATION: 12-mar-2007, jmm
CREATED BY: Frank V. Marcoline
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 15:01:41 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9619 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/split_vec.pro $
(See 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.
CLEAR: Set this keyword to erase the data structure but not the LIMITS or DLIMITS structures
TAGNAMES: Set this keyword to a string containing tagnames that are to be extracted from an array of
structures passed in through the DATA structure. Use TAGNAMES='*' to extract all tagnames.
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 (obsolete)
structures. The default is to transpose.
ERROR: if set returns error code for store_data, values are:
0=NO ERROR
1=INVALID HANDLE ERROR
2=OTHER ERROR
SEE ALSO: "GET_DATA", "TPLOT_NAMES", "TPLOT", "OPTIONS"
CREATED BY: Davin Larson
$LastChangedBy: davin-mac $
$LastChangedDate: 2020-04-03 17:11:34 -0700 (Fri, 03 Apr 2020) $
$LastChangedRevision: 28492 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/store_data.pro $
(See 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 general/tplot/strplot.pro)
NAME: timebar
PURPOSE:
plot vertical (or horizontal) lines on TPLOTs at specified times (or values)
CALLING SEQUENCE: timebar,t
INPUTS: t: dblarr of times at which to draw vertical lines,
seconds since Jan, 1, 1970. (Or a single datavalue at which to draw a horizontal
line in units of the TPLOT variable named in VARNAME).
KEYWORD PARAMETERS:
DATABAR: Set to plot horizontal lines. *** Must set VARNAME also (for the time being) ***.
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 names or indices indicating panel in which
to plot bar, can be an array or glob string, color, linestyle
thick should either be scalar or n_elements(varname) for
multiple varables
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: 2009/05/14, W.M.Feuerstein
FILE: timebar.pro
VERSION: 1.91
(See 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:
CURSOR set to 1 to use the cursor to set the timerange
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: jwl $
$LastChangedDate: 2016-02-03 17:03:41 -0800 (Wed, 03 Feb 2016) $
$LastChangedRevision: 19898 $
$URL: svn+ssh:$
(See 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 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 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 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,4,5 or 6 (3 is default) Uses a different labeling
scheme. Version 4 is for rocket-type time scales.
valid inputs for "version" (date annotation | tick annotations)
1: UTC date boundaries | # of hours or days
2: month:day | UTC time (fewer ticks)
3: year(left margin) month:day | UTC time (default)
4: seconds after launch
5: supress time labels
6: time displayed directly below last panel
7: time displayed directly below last panel (1 line date text only)
this option can also be set when calling tplot_options ( e.g. tplot, [variable], version=2 )
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.
GET_PLOT_POSITION: Returns an array containing the corners of each panel in the plot, to make it easier to overplot and annotate plots
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
QUESTIONS?
See the archives at: http://lists.ssl.berkeley.edu/mailman/listinfo/tplot
Still have questions:
Send e-mail to: tplot@ssl.berkeley.edu someone might answer!
$LastChangedBy: jimm $
$LastChangedDate: 2019-11-04 16:23:54 -0800 (Mon, 04 Nov 2019) $
$LastChangedRevision: 27973 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot.pro $
(See general/tplot/tplot.pro)
Procedure: tplot3d
Purpose: Takes an array of 3-d(Nx3 or MxNx3) vectors or tplot variable
holding these vectors and generates a 3d plot of them
Example: tplotxy,'thb_state_pos'
tplotxy,'thb_state_pos',/overplot
Inputs: vectors: an Nx3 or MxNx3 list of vectors or the name of a tplot
variable that stores an Nx3 or MxNx3 list of vectors
Keywords:
overplot(optional): overplot on an already existing 3d plot
noreset(optional): iplot changes some internal settings,
this procedure resets them to themis defaults, if you do not
want this done then set this option.
also takes all the other options that iplot takes
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 17:01:34 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9630 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot3d.pro $
(See general/tplot/tplot3d.pro)
Procedure: tplotxy
Purpose: Takes a tplot variable containing an array of 3-d(Nx3)
vectors or and plots them using 2-d plots to help visualize
them. It can also take a tplot variable storing an
MxNx3 array. This represents N times and M different
sets of 3-d vectors. (For example M different magnetic
field lines during some interval)
This routine will check the current timespan and only
display values within the specified range(this entails
clipping on the N dimension). If no range is specified
by argument or timespan it will use the entire interval.
If the noisotropic keyword is not used the plot will be made
so that one unit of x is the same length on the screen as
one unit of y
Can also accept an Nx2 or an MxNx2 element array(in a tvar)...if this
is done the versus argument should not use a custom
designation or the z-axis, as it assumes 2-d vectors are in
the x-y plane, and thus will distort the vectors upon projection.
plotxy/tplotxy plots can be interleaved on the same window
with plotxyz plots
Calling tplotxy with no arguments to redraw the entire
window(including plotxyz plots)
***************************************************
Using custom axes: If you use two vectors to define custom
axes, the procedure will generate a plot of the data vectors
projected into a plane defined by the span of the two custom
vectors. The x-axis will be the first vector, the y axis
will be the second vector. This means that if the custom
vectors are not orthogonal the plot will show a distortion.
You can think of this as plotting along a plane that slices
though the 3-d space.
********************************
Plot windows and panels:
using, /overplot,/addpanel,/noisotropic and multi=
To put multiple panels in a window first call
plotxy with the multi keyword. It will either
plot in which ever window is your current one, or
create a new one if no window exists or if you
request the use of a nonexistent window.
During this first call you may want to specify things
like wtitle,xsize,ysize,window...in addition to your normal
plotting options.
multi specifies the plot window panel layout.
So if you set multi='3,2' you will get 6 plots
in your window with a layout like:
-------
|x x x|
|x x x|
-------
Each panel will have dimensions x number of pixels = 1/3 *
xsize of window and y number of pixels = 1/2 * ysize of window.
Your first call should also specify the layout of your
first panel. To add to that panel use the /overplot keyword.
If you wish to add an overall title and/or margins to your multi panel
window your first call should also specify mtitle and/or mmargin.
When you use the /add keyword the program will move on to
the next panel within the plot window and you should add
options to specify the layout of that panel.
An entire plot window must be filled in sequence, if you move
on to a new window you will not be able to go back to the
previous panel without restarting.
It is possible use a panel out of sequence by setting mpanel.
mpanel also allows you to create non symmetric layouts by
creating plots that take up more than one panel.
If you set the xmargin or ymargin keyword the margin will be
relative to the overall size of that panel. When using the
not using the noisotropic keyword the procedure will make
each axis vary over the same range AND make the
largest possible square window given the size of the panel
and the sizes of the margins you have provided, if possible.
In some cases when ranges are set explictly the plot must
be rectangular.
This program will also set some options using the dlimits
and limits of the tplot variable, if they have not already
been explicitly set by the user.
If the tag 'colorsxy' is set to a color index in either
the limits or dlimits of a tplot variable, it will be read
to set a default line color.
The 'ytitle' tag from a dlimits or limits structure will
be used as the plot title
If the 'ysubtitle' tag is set, it will be used as the units
for the xtitle and ytitle of the tplotxy panel
If the 'labels' tag is set, then the appropriate dimension
lable will be used. For example 'Bx','By','Bz' labels for
FGM will be used if plotted
NOTE TO PROGRAMMERS:
Information about plotting for plotxy is stored in
the global variable !TPLOTXY, this includes
information about the layout of the plot window
which panel it is currently working on, and the
sequence of commands used to generate current plot window
so that it can regenerate the plotwindow when called
with no arguments. This variable also stores information
used by the plotxyz function so spectrographic xyz plots
can be interleaved with xy line plots.
Example: tplotxy,'thb_state_pos'
tplotxy,'thb_state_pos',versus='yzr'
tplotxy,'thb_state_pos',versus='cc',custom=transpose([[1,1,0],[0,0,1]])
tplotxy,'thb_state_pos',versus='xryz',xrange=[0,10],yrange=[0,10]
NOTE: This procedure can accept arguments that are documented only
in plotxy. It will pass them through when it calls that routine
using keyword inheritance. So if you can't find a useful option
here, I would recommend looking there.
Inputs: vectors: The name of a tplot variable that stores the list of vectors
versus(optional): specify the projection to be used, can be
'xx','xy','xz','yx','yy','yz','zx','zy','zz','cc' you can also
follow a letter with an 'r' to reverse the axis(goes from
positive to negative instead of from negative to positive)
if you specify 'cc','crc'...that indicate you want to use a
custom projection
example: 'xry' will be an xy plot with the maximum x value
listed on the left and the minimum on the right
(default:'xy')
custom(optional): set this variable to a
2x3 matrix whose columns define a plane in 3-d space, to define a
custom projection. In other words the 2-d plot will be a
plot of the vectors passed into tplotxy when they are
projected into a plane defined by
span(custom[0,*],custom[1,*]). (span is defined as the set
of all the linear combinations of two vectors, or
span(x,y) = {mx+ny:m = element of the reals, n = element of
the reals} The vectors used to define this plane will be
relative to whatever 3-d coordinate system the input vector
data is in.
So if the call:
tplotxy,'somedata',versus='cc',custom=transpose([[1,1,0],[0,0,1])
is made, the plot generated will be of the vectors closest
to the data vectors that are inside a vertical plane whose
intersection with the x-y plane forms a line y=x.
tplotxy,'somedata',versus='cc',custom=transpose([[1,0,0],[0,1,0])
is effectively the same as:
tplotxy,'somedata',versus='xy'
overplot(optional): set this keyword if you want to plot
on the last plot and panel that you plotted on
addpanel(optional): set this keyword if you want to plot on a new
panel within the same plot window as where you last
plotted. This will go to the next column first and if it is
at the end of a row, to the next row.
multi(optional): set this keyword to a string that
specifies the layout of panels within a plotwindow. Set
this keyword only the first time you call tplotxy for a
given plotwindow. Each time you set it, the previous
contents of the window will be erased. You can separate
the two elements with a variety of different delimiters
The first element is cols left to right, the second rows
top to bottom. Append an 'r' to the elements to have it
reverse the direction of panel application
Examples: multi= '2 3'
multi= '5r,7'
multi=' 1:6r'
.....
mmargin(optional, can only be used if multi is also specified):
set this keyword to a 4 element array specifying margins to be left
around a multipanel plot. Element order is bottom, left, top, right.
Margins are specified relative to the overall size of the window:
0.0 is no margin, 1.0 is all margin.
e.g. mmargin=[0.1,0.1,0.15.0.1]
mtitle(optional, can only be used if multi is also specified):
set this keyword to a string to display as a title for a multi panel
plot window. This is displayed in addition to any titles specified for
individual panels.
If the top mmargin = 0, or has not been set then it will be set at 0.05
to allow room for the title.
It is not possible to set your own font size for the mtitle. The size is
chosen so that as much as possible the title fits in the top margin and
is not too long for the window. Setting a larger top mmargin will
increase the font size. NB: Size is fixed you are saving your plot
to a postscript. If you require more control over the title format
try leaving space using mmargin and adding your own text with idl
procedure XYOUTS.
mpanel(optional, can only be used if multi is also specified):
set this keyword to a string to specify which panels in a multipanel window
to plot to. This allows you to create non symmetric plot layouts in a multi
panel window.
mpanel must contain two numbers separated by a comma (col, row) or two ranges
indicated with a colon, separated by a comma.
Panels are numbered starting at 0, from top to bottom and from
left to right.
e.g. mpanel = '0,1' will plot to panel in the first column,
second row;
mpanel = '0:1,0' will create a plot that takes up both the first
and second columns in the first row.
You cannot plot to a panel if that panel has already been used.
Panels in a window are normally filled from left to right, top to bottom. You
can use mpanel to place a plot out of this standard sequence.
noisotropic(optional): set this keyword if you don't want the
scaling of both axes to be the same and the space to
be perspective corrected so that a cm of y unit takes
up the same space on the screen as a cm of x unit
memsave(optional): set this keyword to request command
copies not be saved and redraws be done without maintaining
square isotropic plots. Setting this option can potentially
save quite a lot of memory.
linestyle(optional):set this to change the linestyle used
0 = default,1=dotted=,2=dashed,3=dash dot,4=dash dot
dot,5=long dashes
xrange(optional): set this to a 2 element array to specify
the min and max for the first axis(x) of the 2-d plot
yrange(optional): set this to a 2 element array to specify
the min and max for the second axis(y) of the 2-d plot
xmargin(optional):set this to a 2 element array to specify
the left and right margin for the plot
unlike tplot & plot this is specified in terms of the
proportion of available space given the plot layout not
number of characters. This also specified for each plot
in a panel individually, no for the whole panel to allow
the user more control over layout.
ymargin(optional):set this to a 2 element array to specify
the bottom and top margin for the plot
unlike tplot & plot this is specified in terms of the
proportion of available space given the plot layout not
number of characters. This also specified for each plot
in a panel individually, no for the whole panel to allow
the user more control over layout.
pstart(optional): set this keyword to a number representing
the symbol you would like to start lines with. (This works
like the idl psym keyword, but only for the first symbol
in a line being plotted)
pstop(optional): set this keyword to a number representing
the symbol you would like to end lines with. (This works
like the idl psym keyword, but only for the last symbol
in a line being plotted)
psym(optional): use this to plot using a symbol
rather than a line.
symsize(optional): specify the size of the start and end
symbol, or psym (default:1.0)
WARNING!!! Using any of the 4 windowing options
below will interfere with the creation of postscript
graphics
window(optional):specify the window for
output. (default:current)
xsize(optional):specify the xsize of the window in
pixels(default: current)
ysize(optional):specify the ysize of the window in pixels
(default: current)
wtitle(optional):the title you would like the window to have
usetrange(optional):set this keyword(ie /usetrange) if you want it
to prompt for a timerange if one is not provided by timespan
notrange(optional):set this keyword(ie /notrange) if you
want it to ignore the time range and use the entire sequence
of values regardless.
sort(optional): set this keyword(ie /sort) if you want it
to sort points on time
colors(optional): set this keyword to override the color
information stored in the limits or dlimits of the tplot
variable, if the tplot variable contains an Nx3 array
it should contain a single element, if it contains an
MxNx3 array it should contain one or M colors. If the
tplot variable contains wildcards or is composite
it will be ignored.
xlog(optional): set the x scale to be logarithmic
ylog(optional): set the y scale to be logarithmic
xtitle(optional): set the xtitle for the plot
ytitle(optional): set the ytitle for the plot
grid(optional): set this to 1 to have the procedure
generate a grid rather than normal tickmarks
markends(optional): set this if you want to mark the very
edges of your plot axis with data labels. This means the
numerical values of the maximum x tick,minimum x tick,
maximum y tick, and minimum y tick will be marked.Note that
an extra blank page may be created in any postscripts you
generate when using this option.
reverse_time(optional): set to have the function reverse
the data according to the time axis,this will only
really change which end is marked as stop and which as start
units(optional): set this if you want this unit label
appended to both axis titles.(This will be ignored if
you set the xtitle or ytitle explictly)
xtick_get,ytick_get: These behave exactly as the plot
command versions, but they had to be identified explictly
to ensure they would be passed through correctly.
get_plot_pos=get_plot_pos: Return the normalized position of your plot.
Output will be a 4-element array [x1,y1,,x2,y2]
Where (x1,y1) is the lower-left corner of your plot and
(x2,y2) is the top right corner of your plot.
This procedure also takes normal idl keywords that effect
plotting style
SEE ALSO:
plotxyz,plotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz,
plotxylib,plotxyvec
$LastChangedBy: egrimes $
$LastChangedDate: 2016-10-27 14:27:21 -0700 (Thu, 27 Oct 2016) $
$LastChangedRevision: 22223 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplotxy.pro $
(See general/tplot/tplotxy.pro)
NAME:
tplot_apply_databar
PURPOSE:
Plots horizontal lines (databars) for plotted tplot variables, if
there is a databar tag in the limits structure for those
variables. To set values, use the 'options' programs: e.g.,
options, 'tha_efs', 'databar', {yval:[-5., 0, 5.0]}
Then call
tplot_apply_databar
sets three vertical lines for the 'tha_efs' variable..
Color, linestyle and thick can be included, for each value, or one
scalar for all:
options, 'tha_efs', 'databar', {yval:[-5., 0, 5.0], color:[2,4,6], linestyle:2, thick:[2.0, 1.0, 2.0]}
The databar value only needs to be a structure if other options are set
options, 'tha_efs', 'databar', [6, 7, 8]
will work
Note that tplot needs to have been called previously
CALLING SEQUENCE:
tplot_apply_databar
INPUT:
none
OUTPUT:
none
KEYWORDS:
varname = if set, only do the databars for the named variable(s)
clear = if set, clear out the databar options for the affected variables
HISTORY:
2016-07-29, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: jimm $
$LastChangedDate: 2019-08-19 12:50:00 -0700 (Mon, 19 Aug 2019) $
$LastChangedRevision: 27620 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_apply_databar.pro $
(See general/tplot/tplot_apply_databar.pro)
NAME:
tplot_apply_timebar
PURPOSE:
Plots vertical lines (timebars) for plotted tplot variables, if
there is a timebar tag in the limits structure for those
variables. To set values, use the 'options' programs: e.g.,
options, 'tha_efs', 'timebar', {time:'2016-07-01 '+['06:22', '07:00']}
sets two vertical lines for the 'tha_efs' variable..
Then call
tplot_apply_timebar
options, 'tha_efs', 'timebar', {time:'2016-07-01/'+['06:22','07:00'], color:[3, 6], linestyle:2, thick:2.0}
Adds color for each of the lines. Linestyle and thick are also
options for the timebar; color, linestyle and thick can be arrays or scalars
The timebar value only needs to be a structure if other options are set
options, 'tha_efs', 'timebar', '2016-07-07/06:12'
will work
Note that tplot needs to have been called previously
CALLING SEQUENCE:
tplot_apply_timebar
INPUT:
none
OUTPUT:
none
KEYWORDS:
varname = if set, only do the timebars for the named variable(s)
clear = if set, clear the options for the affected variable
HISTORY:
2016-07-29, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: jimm $
$LastChangedDate: 2016-10-10 12:29:12 -0700 (Mon, 10 Oct 2016) $
$LastChangedRevision: 22074 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_apply_timebar.pro $
(See general/tplot/tplot_apply_timebar.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 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 general/tplot/tplot_file.pro)
NAME:
tplot_fill_color
PURPOSE:
Fills the area under a line in a tplot panel
INPUT:
vars: string or array of strings specifying which tplot variables to fill
colors: int or array of ints specifying the fill colors; must match the number
of elements in 'vars'
EXAMPLE:
>> tplot, 'kyoto_dst'
>> tplot_fill_color, 'kyoto_dst', spd_get_color('blue')
WARNING:
if you see strange results with a variable containing NaNs, run 'tdegap'
on the variable prior to creating the figure to remove the NaNs
$LastChangedBy: egrimes $
$LastChangedDate: 2020-02-12 12:40:17 -0800 (Wed, 12 Feb 2020) $
$LastChangedRevision: 28296 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_fill_color.pro $
(See general/tplot/tplot_fill_color.pro)
NAME:
tplot_fill_time_intv
PURPOSE:
Allow different background color, or other polyfill options for time
intervals for a tplot variable. Called only from tplot.pro, Do not
use this in any other environment
CALLING SEQUENCE:
tplot_fill_time_intv, routine, data, newlim
INPUT:
routine - thie is the plot routine for a given tplot variable,
typically 'mplot' or 'specplot' or 'bitplot'
data - the data structure for the input variable
newlim - the limits structure, this must contain a tag
'fill_time_intv' = {time:interval_times, color:color values}
The time intervals can be an array of 2, or 2Xntimes, color
values can be scalar, or an array of ntimes. Other polyfill
options, such as line_fill, orientation, thick, can be input
in the fill_time_intv structure,
time_offset - the plot start time needed for the correct position
EXAMPLES:
(see also crib_fill_time_intv.pro in spdsw/general/examples)
a solid background color, using options, for the variable 'sta_SWEA_mom_flux'
options, 'sta_SWEA_mom_flux', 'fill_time_intv', $
{time:['2008-03-23/02:00','2008-03-23/04:00'], color:2}
different intervals with different colors, using options, for the flux variable
2Xn_times intervals
t1 = '2008-03-23/'+[['02:00','04:00'],['07:00','09:00'],['16:24','22:00']]
c1 = 'rgb' ;you can use string color values in addition to absolute numbers
options, 'sta_SWEA_mom_flux', 'fill_time_intv', {time:t1, color:c1}
set line_fill:1,orientation:45 to use angled
parallel lines and not solid colors
2Xn_times intervals
t1 = '2008-03-23/'+[['02:00','04:00'],['07:00','09:00'],['16:24','22:00']]
c1 = [4,6,2]
options, 'sta_SWEA_mom_flux', 'fill_time_intv',
{time:t1, color:c1, line_fill:1, orientation:45.0}
See crib sheet for more options
HISTORY:
2019-11-04, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: jimm $
$LastChangedDate: 2019-11-08 11:30:01 -0800 (Fri, 08 Nov 2019) $
$LastChangedRevision: 27993 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_fill_time_intv.pro $
(See general/tplot/tplot_fill_time_intv.pro)
Procedure: tplot_force_monotonic
Purpose:
This routine checks tplot variables for sample time (abscissa: data.x) monotonicity
and forces them so through removal or replacement of non-monotonic segments, if requested;
the corresponding elements of data.y and data.v are also repaired.
Indices of consecutively repeated header times and piece-wise monotonic segment "negative jumps"
are identified and used to determine monotonicity of tplot variables. If checking,
the routine will report cause of failures (i.e. negative jumps, repeats).
Three repair methods are available: /forward, /reverse and /sort (see Keywords)
Inputs: [optional] tplot variable name(s) string/array or wild-card name string or tplot variable number(s); same as input for tnames()
Keywords:
forward: the recommended repair method, which keeps the older time elements of over-lapping time segments
reverse: repair method which keeps the newer time elements over-lapping time segments
sort: repair method which sorts time-lines chronologically, using bsort()
keep_repeats: [optional] do not remove consecutively repeated header times
replace_NaN: [optional] instead of removing 'bad' elements, replace them with NaN (only applied to data.y and data.v elements, data.x is not modified)
Outputs:
If checking, PASS/FAIL console message per tplot variable, including cause of failures
If repairing, PASS/FAIL console message per tplot variable and repaired tplot variable(s) (via store_data)
Examples:
tplot_force_monotonic ; check all tplot variables
tplot_force_monotonic,'*' ; check all tplot variables
tplot_force_monotonic,'var1' ; check tplot variable named var1
tplot_force_monotonic,['var1','var2'] ; check tplot variables named var1 and var2
tplot_force_monotonic,[6,7,9] ; check tplot variables 6, 7 and 9
tplot_force_monotonic,/forward ; repair all tplot variables using 'forward' method, discarding repeated sample times (recommended repair method)
tplot_force_monotonic,/reverse,/keep_repeats ; repair all tplot variables using 'reverse' method, keeping repeated sample times
tplot_force_monotonic,/sort ; repair all tplot variables using 'sort' method, discarding consecutively repeated sample times
tplot_force_monotonic,'var?',/forward,/replace_nan ; repair tplot variable(s) in var? using 'forward' method and replace bad elements with NaNs
Notes:
1. tplot variables repaired with the /replace_nan keyword will not pass a monotonicity check.
2. tplot variables repaired with the /keep_repeats keyword may not pass a monotonicity check.
3. A warning is issued if more than 10% of tplot variable elements are removed or replaced.
ToDo: nothing yet
$LastChangedBy: egrimes $
$LastChangedDate: 2016-04-25 12:07:51 -0700 (Mon, 25 Apr 2016) $
$LastChangedRevision: 20911 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_force_monotonic.pro $
(See general/tplot/tplot_force_monotonic.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 general/tplot/tplot_keys.pro)
Procedure:
tplot_multiaxis
Purpose:
This procedure functions as a workaround to allow
two y axes when creating line plots with tplot.
Calling Sequence:
tplot_multiaxis, left_names, right_names [,positions] [,_extra=extra]
Input:
left_names: String array or space separated list of tplot variables.
Each variable will be plotted in a separate panel with a
left-aligned y axis.
right_names: String array or space separate list of tplot variables.
Each variable will be added to the appropriate panel
with a righ-aligned y axis. If positions are not
specified then this must be the same size as left_names.
positions: Integer array specifying the vertical position [1,N] of
the correspond entry in right_names. This keyword must
be used if left_names has more entries than right_names.
_extra: Keywords to tplot can also be used here.
Output:
None, calls tplot with current settings.
Notes:
-Y axis graphical keywords set with "options, 'tvar', ..." should be applied.
-Existing "ystyle" and "axis" elements will be clobbered (from limits structure).
$LastChangedBy: egrimes $
$LastChangedDate: 2019-02-07 12:15:26 -0800 (Thu, 07 Feb 2019) $
$LastChangedRevision: 26569 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_multiaxis.pro $
(See general/tplot/tplot_multiaxis.pro)
Procedure: tplot_multiaxis_kludge Purpose: Apply workaround for simultaneous left/right y axes to list of tplot variables. Calling Sequence: tplot_multiaxis_kludge, names, [,/left] [,/right] [,/reset] Input: names: string array of tplot variables left: flag denoting left handed y axes right: flag denoting right handed y axes reset: flag to remove previous changes Output: None, alters limits structure of tplot variables Notes: -See tplot_multiaxis.pro -Existing "ystyle" and "axis" elements of limits struct will be clobbered. $LastChangedBy: egrimes $ $LastChangedDate: 2019-02-07 12:15:26 -0800 (Thu, 07 Feb 2019) $ $LastChangedRevision: 26569 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_multiaxis_kludge.pro $
(See general/tplot/tplot_multiaxis_kludge.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
$LastChangedBy: ali $
$LastChangedDate: 2020-03-05 13:17:11 -0800 (Thu, 05 Mar 2020) $
$LastChangedRevision: 28378 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_names.pro $
(See 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,2,3,4,5,6)
valid inputs for "version" (date annotation | tick annotations)
1: UTC date boundaries | # of hours or days
2: month:day | UTC time (fewer ticks)
3: year(left margin) month:day | UTC time (default)
4: seconds after launch
5: supress time labels
6: time displayed directly below last panel
this option can also be set when calling tplot ( e.g. tplot, [variable], version=2 )
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,verbose = 2 ; Set verbose level to 2
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.
tplot_options,'ygap',0.0 ;eliminate the vertical spacing between panels
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 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 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 general/tplot/tplot_positions.pro)
PROCEDURE: tplot_quant__define This procedure defines the tplot_quant structure.
(See general/tplot/tplot_quant__define.pro)
Procedure: tplot_quaternion_rotate, vectorname, quatname, name=name PURPOSE: Rotates a tplot vector using the tplot quaternion. Will create a new tplot variable. This function may be used with the "fit" curve fitting procedure. Written by: Davin Larson $LastChangedBy: davin-win $ $LastChangedDate: 2011-02-15 16:17:03 -0800 (Tue, 15 Feb 2011) $ $LastChangedRevision: 8224 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_quaternion_rotate.pro $
(See general/tplot/tplot_quaternion_rotate.pro)
PROCEDURE:
tplot_remove_panel
PURPOSE:
Remove panel(s) from the current tplot window
INPUT:
panel: int or array of ints containing panel #s
to remove from the current tplot window
(starts at 0 at the top)
also accepts string or array of strings
containing variable names to be removed
EXAMPLES:
IDL> tplot, ['var1', 'var2', 'var3']
to remove 'var2' from the figure:
IDL> tplot_remove_panel, 'var2'
or:
IDL> tplot_remove_panel, 1
$LastChangedBy: egrimes $
$LastChangedDate: 2019-07-10 13:21:07 -0700 (Wed, 10 Jul 2019) $
$LastChangedRevision: 27433 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_remove_panel.pro $
(See general/tplot/tplot_remove_panel.pro)
PROCEDURE: tplot_rename PURPOSE: Simple procedure to perform a rename of tplot variable without copy. Uses the store_data,newname= keyword to implement, but performs some checks to make it more user friendly. Inputs(required): old_name: current name of the variable or index.(string or integer) new_name: name the variable will have after procedure call.(string) $LastChangedBy: pcruce $ $LastChangedDate: 2013-09-06 14:36:07 -0700 (Fri, 06 Sep 2013) $ $LastChangedRevision: 12962 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_rename.pro $
(See general/tplot/tplot_rename.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 (or directory specified by directory keyword)
directory: specify a directory other than the current working dir for loading ALL tplot files
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
Changed the obsolete IDL routine str_sep to
strsplit. Also added additional output
text. 21-may-2008, cg
Removed additional output text - Use dprint,debug=3 to restore text. Nov 2008
Fixed bug on macOS when saving figures of restored data using makepng/makegif/makejpg, 24-jan-2019, egrimes
$LastChangedBy: ali $
$LastChangedDate: 2020-03-05 14:17:16 -0800 (Thu, 05 Mar 2020) $
$LastChangedRevision: 28383 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_restore.pro $
(See 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.
NO_ADD_EXTENSION: Set this to prevent the addition of the extension
SEE ALSO: "STORE_DATA", "GET_DATA", "TPLOT", "TPLOT_RESTORE"
CREATED BY: Peter Schroeder
LAST MODIFICATION: tplot_save.pro 97/05/14
$LastChangedBy: ali $
$LastChangedDate: 2020-03-05 13:17:11 -0800 (Thu, 05 Mar 2020) $
$LastChangedRevision: 28378 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_save.pro $
(See 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% $LastChangedBy: lbwilsoniii_desk $ $LastChangedDate: 2018-01-31 11:56:42 -0800 (Wed, 31 Jan 2018) $ $LastChangedRevision: 24612 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_sort.pro $
(See general/tplot/tplot_sort.pro)
PROCEDURE: tplot_var_labels
PURPOSE:
Helper routine for tplot. Formats var_labels
The var_label code in the body of tplot.pro was occupying 25% of the file. It needed to be abstracted.
Inputs:
def_opts: all the options need for variables labels
trg: time range for plotting
var_label: var_label setting from user
local_time: local time keyword from user
pos: plot position
chsize: desired character size
Outputs:
vtitle=vtitle: title for var labels
vlab=vlab: formatted var labels
time_offset=time_offset: Used by tplot, as the start time of the
plot in unix time
time_scale=time_scale: Used by tplot to scale the time variable,
typically 1.0, but larger for longer time
ranges
$LastChangedBy: crussell $
$LastChangedDate: 2019-10-23 10:21:50 -0700 (Wed, 23 Oct 2019) $
$LastChangedRevision: 27920 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/tplot_var_labels.pro $
(See general/tplot/tplot_var_labels.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 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
$LastChangedBy: ali $
$LastChangedDate: 2019-05-14 14:18:26 -0700 (Tue, 14 May 2019) $
$LastChangedRevision: 27232 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/ylim.pro $
(See 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 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
$LastChangedBy: ali $
$LastChangedDate: 2020-02-20 12:13:34 -0800 (Thu, 20 Feb 2020) $
$LastChangedRevision: 28324 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tplot/zlim.pro $
(See 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 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 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 general/tplot/_tplot_example.pro)