This page was created by the IDL library routine
mk_html_help2.
Last modified: Tue Feb 13 09:58:54 2007.
PROCEDURE: append_array, a0, a1
PURPOSE:
Append an array to another array. Can also copy an array into a
subset of another.
INPUT:
a0: Array to modify.
a1: Array to append to, or copy into, a0.
KEYWORDS:
index: Index of a0 at which to append or copy a1. If index is
greater than the number of elements of a0, then
a0 is enlarged to append a1. Returns the index of the first
element of a0 past the section copied from a1.
done: If set, make a0 equal to the first index elements of a0.
CREATED BY: Davin Larson
LAST MODIFIED: @(#)append_array.pro 1.6 98/08/13
(See ssl_general/misc/append_array.pro)
FUNCTION: average_str(data, res) PURPOSE: Average data in res second time segments. INPUTS: DATA: array of structures. One element of structure must be TIME. RES: resolution in seconds. KEYWORDS: NAN: If set, treat the IEEE NAN value as missing data. CREATED BY: Davin Larson LAST MODIFIED: %W% %E%
(See ssl_general/misc/average_str.pro)
FUNCTION: bytescale(array)
PURPOSE: Takes an array or image and scales it to bytes
INPUT: array of numeric values.
KEYWORDS:
RANGE: Two element vector specifying the range of array to be used.
Defaults to the min and max values in the array.
ZERO: Forces range(0) to zero
TOP: Maximum byte value (default is !d.table_size-2)
BOTTOM: Minimum byte value (default is 1)
MIN_VALUE: autoranging ignores all numbers below this value
MAX_VALUE: autoranging ignores all numbers above this value
MISSING: Byte value for missing data. (values outside of MIN_VALUE,
MAX_VALUE range) If the value is less than 0 then !p.background is used.
LOG: sets logrithmic scaling
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)bytescale.pro 1.22 02/04/17
(See ssl_general/misc/bytescale.pro)
PROCEDURE: cart_to_sphere, x, y, z, r, theta, phi
PURPOSE:
transform from cartesian to spherical coordinates
INPUTS: x, y, z (array or scalor)
OUTPUTS: r, theta, phi (same as x,y,z)
KEYWORDS: ph_0_360: if positive, 0<=phi<=360, if zero, -180<=phi<=180,
***if negative, best guess phi range returned***
ph_hist: a two element array of max and min values for phi.
eg: if ph_0_360 is not set, and ph_hist=[-220,220]
then if d(phi)/dt is positive near 180, then
phi => phi+360 when phi passes the 180/-180
discontinuity until phi reaches 220.
CO_LATITUDE: If set theta will be in co-latitude. (0<=theta<=180)
MIN_VALUE:
MAX_VALUE:
CREATED BY: Davin Larson
LAST MODIFICATION: @(#)cart_to_sphere.pro 1.13 02/04/17
NOTES:
-90 < theta < 90 (latitude not co-lat)
(See ssl_general/misc/cart_to_sphere.pro)
FUNCTION: cdf_file_names
PURPOSE:
Returns an array of filenames within a timerange.
USAGE:
files=cdf_file_names(FORMAT,trange=trange,/verbose)
INPUT:
FORMAT is a string that will be interpreted as one of two things:
CASE 1:
e.g. FORMAT = '/home/wind/dat/wi/3dp/k0/????/wi_k0_3dp*.cdf'
if FORMAT contains * or ? then filenames are returned that match that
pattern and for which YYYYMMDD falls within the specified timerange.
for example:
(UNIX only)
CASE 2:
e.g. FORMAT = 'fa_k0_ees_files'
The name of an indexfile that associates filenames with start and
end times. If his file is not found, then the environment variable
getenv('CDF_INDEX_DIR') is prepended and searched for.
See "make_cdf_index" for information on producing this file.
SPECIAL NOTE:
If strupcase(FORMAT) is the name of an environment varible. Then
the value of that environment variable is used instead.
KEYWORDS:
TRANGE:
Two element array specifying the time range for which data files should
be returned. If not provided then "timerange" is called to provide
the time range. See also "timespan".
NFILES:
Named variable that returns the number of files found.
VERBOSE:
Set to print some useful info.
FILEINFO: OBSOLETE!
Set to a named variable that will return a table of file info.
NOTES:
UNIX only!
(See ssl_general/misc/cdf_file_names.pro)
COMMON BLOCK colors_com WARNING! Don't rely on this file to remain stable! USE "get_colors" to get color information. SEE ALSO: "get_colors","bytescale","loadct2" CREATED BY: Davin Larson File: 96/08/30 Version: 1.2 Last Mod: colors_com.pro
(See ssl_general/misc/colors_com.pro)
NAME: day_to_year_doy PURPOSE: determines year and day of year given day since 0000 AD USAGE: day_to_year_doy,daynum,year,doy INPUT: daynum: (long int) day since 0 AD OUTPUT: year: year (0 <= year <= 14699 AD) doy: day of year (1 <= doy <= 366) NOTES: This procedure is reasonably fast, it works on arrays and works from 0 AD to 14699 AD CREATED BY: Davin Larson Oct 1996 FILE: day_to_year_doy.pro VERSION: 1.2 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/day_to_year_doy.pro)
FUNCTION: dimen(x) PURPOSE: Returns the dimensions of an array as an array of integers. INPUT: matrix RETURNS: vector of dimensions of matrix. If the input is undefined then 0 is returned. if the input is a scaler then 1 is returned. SEE ALSO: "dimen", "data_type", "dimen1", "dimen2" CREATED BY: Davin Larson LAST MODIFICATION: @(#)dimen.pro 1.6 96/12/16
(See ssl_general/misc/dimen.pro)
FUNCTION: dimen1 INPUT: matrix RETURNS: scaler int: size of first dimension (1 if dimension doesn't exist) CREATED BY: Davin Larson LAST MODIFICATION; @(#)dimen1.pro 1.3 95/08/24
(See ssl_general/misc/dimen1.pro)
FUNCTION: dimen2 INPUT: matrix RETURNS: scaler int: size of second dimension (1 if dimension doesn't exist) CREATED BY: Davin Larson LAST MODIFICATION; @(#)dimen2.pro 1.3 95/08/24
(See ssl_general/misc/dimen2.pro)
FUNCTION: dimen_shift(x,shift) NAME: dimen_shift PURPOSE: Rotate dimensions of a multidimensional array. This function is very similar to transpose but works on multi-dimensional arrays to shift the dimensions around. It has no effect on scalars and one dimensional arrays. INPUT: x multi-dimensional array of any type shift: 1 or -1 direction of shift. CREATED BY: Davin Larson LAST MODIFICATION: @(#)dimen_shift.pro 1.4 98/07/09
(See ssl_general/misc/dimen_shift.pro)
PROCEDURE: divide_data
PURPOSE:
Divides successive channels of SST data by powers of 'factor', to
separate the traces. Also, optionally, multiplies data by an overall factor,
'conv_factor', to convert units.
INPUT: in_name (string), the name of the input TPLOT variable
structure.
out_name (string), the name of the output TPLOT variable
structure.
KEYWORDS: factor (float), by which fluxes in successive channels are
divided.
conv_factor (optional float), by which fluxes in all channels
are multiplied.
CREATED BY: Ted Freeman
FILE: divide_data.pro
LAST MODIFIED: @(#)divide_data.pro 1.2 99/09/01
NOTES: "LOAD_3DP_DATA" and "GET_SPEC" must be called first.
(See ssl_general/misc/divide_data.pro)
PROCEDURE: doy_to_month_date, year, doy, month, date NAME: doy_to_month_date PURPOSE: Determines month and date given the year and day of year. fast, vector oriented routine that returns the month and date given year and day of year (1<=doy<=366) CREATED BY: Davin Larson Oct 1996 FILE: doy_to_month_date.pro VERSION: 1.2 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/doy_to_month_date.pro)
PROCEDURE: extract_tags, newstruct, oldstruct
PURPOSE: takes the named tag elements from oldstruct and puts them into
newstruct. This procedure is very useful for creating a structure that
can be passed onto the PLOT or OPLOT subroutines using the _EXTRA keyword.
If no tag keywords are included then all tag elements of oldstruct are
added to newstruct. The mode keyword PRESERVE is used to prevent the
overwritting of an existing keyword.
INPUTS:
newstruct: new structure to be created or added to.
oldstruct: old structure from which elements are extracted.
KEYWORDS: Only one of the following should be given:;
(TAG KEYWORDS)
TAGS: array of strings. (tag names) to be taken from oldstruct and put in
newstruct
EXCEPT: array of strings. Tag names not to be copied from old to new.
OPLOT: (flag) If set, then TAGS is set to an array of valid keywords
for the OPLOT subroutine.
PLOT: (flag) If set, then TAGS is set to an array of valid keywords
for the PLOT subroutine.
CONTOUR: (flag) If set, then TAGS is set to an array of valid keywords
for the CONTOUR procedure. (might not be complete)
If no KEYWORDS are set then all elements of oldstruct are put into newstruct
(MODE KEYWORDS)
PRESERVE: (flag) Prevents the overwritting of an existing, non-null keyword.
Adds tags to newstruct that were not already there, or if they were there
and their values were either "" or 0.
CREATED BY: Davin Larson
FILE: extract_tags.pro
VERSION 1.21
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/extract_tags.pro)
FUNCTION file_retrieve(pathnames) $LastChangedBy: davin-win $ $LastChangedDate: 2007-02-07 04:33:51 -0800 (Wed, 07 Feb 2007) $ $LastChangedRevision: 314 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/misc/file_retrieve.pro $
(See ssl_general/misc/file_retrieve.pro)
Procedure: FIND_CONST_INTERVALS Purpose: Find intervals within the input array where the data are constant to some tollerance, and return the begin and end indices into the original array for those intervals. Calling Sequence: x = [ 1, 1, 3, 3, 4, 1, 1, 1, 1] ctol = 0.01 find_const_intervals, x, nint=nint, ibeg=ibeg, iend=iend, ctol=ctol Arguements: X, ARRAY or any type; will be cast to FLOAT for comparison. NINT, LONG, number of intervals of constantcy found in X. IBEG, IEND, LONG[ nint], arrays of array indices to the begin and end of each constant interval. CTOL, FLOAT, tollerance for constancy of data; ABS(dX) lt CTOL for data to be "constant". Notes: None. $LastChangedBy: kenb-mac $ $LastChangedDate: 2007-02-08 10:02:45 -0800 (Thu, 08 Feb 2007) $ $LastChangedRevision: 329 $ $URL $
(See ssl_general/misc/find_const_intervals.pro)
**** OBSOLETE!!! Please use "str_element"instead! *** FUNCTION: find_str_element PURPOSE: find an element within a structure Input: struct, generic structure name, string (tag name) Purpose: Returns index of structure tag. Returns -1 if not found Returns -2 if struct is not a structure KEYWORDS: If VALUE is set to a named variable then the value of that element is returned in it. CREATED BY: Davin Larson LAST MODIFICATION: @(#)find_str_element.pro 1.6 95/10/06
(See ssl_general/misc/find_str_element.pro)
PROCEDURE: fname_to_time, fname, time PURPOSE: To translate the name of a standard WIND data file into the starting time of the data. INPUT: fname: filename (string) to be translated time: variable in which to return time (double) CREATED BY: Peter Schroeder LAST MODIFICATION: %W% %E%
(See ssl_general/misc/fname_to_time.pro)
FUNCTION: get_colors PURPOSE: returns a structure containing color pixel values INPUT: none KEYWORDS: NOCOLOR: forces all colors to !d.table_size-1. Written by: Davin Larson 96-01-31 FILE: get_colors.pro VERSION: 1.2 LAST MODIFICATION: 99/04/07
(See ssl_general/misc/get_colors.pro)
PROCEDURE: get_file_names, fnames
PURPOSE:
Gets an array of filenames within a time range
INPUT:
fnames: named variable in which the output array of filenames is placed.
KEYWORDS:
TIME_RANGE: Two element vector (double or string) specifying the time range.
If time range is not set, then "GET_TIMESPAN" will be called
to get a time range.
MASTERFILE: Use this keyword to pass in one of the following:
1) Name of a masterfile that contains times and associated
filenames. The file should have the format:
yyyy-mm-dd/hh:mm:ss yyyy-mm-dd/hh:mm:ss fullpathfilename
with one line for each file.
(Hint: for CDF files, the masterfile can be created using the
UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
2) Full path/file names with wildcard characters to search for
relevant files. Input should be in the form:
/path/xxx* for files of form /path/xxx_date.
3) The name of a previously defined environment variable containing
data in the form of 1 or 2 above.
ROOT_DIR: Optional root_directory of the masterfile. This will properly
manage operating system dependancies.
CREATED BY: Davin Larson
MODIFIED BY: Peter Schroeder
VERSION: 1.26 00/10/04 get_file_names.pro
(See ssl_general/misc/get_file_names.pro)
PROCEDURE: get_file_names_ind, fnames
PURPOSE:
Gets an array of filenames within a masterfile within a time range
INPUT:
fnames: named variable in which the output array of filenames is placed.
KEYWORDS:
TIME_RANGE: Two element vector (double or string) specifying the time range.
If time range is not set, then "GET_TIMESPAN" will be called
to get a time range.
MASTERFILE: Name of a masterfile that contains times and associated
filenames. The file should have the format:
yyyy-mm-dd/hh:mm:ss yyyy-mm-dd/hh:mm:ss fullpathfilename
with one line for each file.
(Hint: for CDF files, the masterfile can be created using the
UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
ROOT_DIR: Optional root_directory of the masterfile. This will properly
manage operating system dependancies.
NO_DUPLICATES: (N; integer)
when set the first N characters of file names are compared and only
the highest version is returned.
CREATED BY: Davin Larson
VERSION: @(#)get_file_names_ind.pro 1.1 97/06/23
(See ssl_general/misc/get_file_names_ind.pro)
FUNCTION: interp(y,x,u)
PURPOSE:
Linearly Interpolates vectors with an irregular grid.
INTERP is functionally the same as INTERPOL, however it is typically
much faster for most applications.
USAGE:
result = interp(y,x,u)
INPUTS:
Y: The input vector can be any type except string.
X: The absicissae values for Y. This vector must have same # of
elements as Y. The values MUST be monotonically ascending
or descending.
U: The absicissae values for the result. The result will have
the same number of elements as U. U does not need to be
monotonic.
KEYWORDS:
NO_CHECK_MONOTONIC: set this keyword to skip the check for monotonic data.
INDEX: Set to named variable to return the index of the closest x less than u.
(same dimensons as u)
NO_EXTRAPOLATE: Set this keyword to prevent extrapolation.
INTERP_THRESHOLD: Set to minimum allowed gap size.
CREATED BY: Davin Larson 4-30-96
FILE: interp.pro
VERSION: 1.15
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/interp.pro)
PROCEDURE: makegif, filename NAME: makegif PURPOSE: Creates a GIF file from the currently displayed image. NOTES: extension '.gif' is added automatically Restrictions: Current device should have readable pixels (ie. 'x' or 'z') Created by: Davin Larson FILE: makegif.pro VERSION: 1.11 LAST MODIFICATION: 02/11/06
(See ssl_general/misc/makegif.pro)
PROCEDURE: makepng, filename NAME: makepng PURPOSE: Creates a GIF file from the currently displayed image. NOTES: extension '.png' is added automatically Restrictions: Current device should have readable pixels (ie. 'x' or 'z') Created by: Davin Larson FILE: makegif.pro VERSION: 1.11 LAST MODIFICATION: 02/11/06
(See ssl_general/misc/makepng.pro)
FUNCTION: minmax,array PURPOSE: returns a two element array of min, max values INPUT: array KEYWORDS: MAX_VALUE: ignore all numbers greater than this value MIN_VALUE: ignore all numbers less than this value POSITIVE: forces MINVALUE to 0 CREATED BY: Davin Larson LAST MODIFICATION: @(#)minmax.pro 1.2 02/04/17
(See ssl_general/misc/minmax.pro)
NAME:
MK_HTML_HELP2
PURPOSE:
Creates a html document from a list of IDL procedures.
Given a list of IDL procedure files (.PRO), VMS text library
files (.TLB), or directories that contain such files, this procedure
generates a file in the HTML format that contains the documentation
for those routines that contain a DOC_LIBRARY style documentation
template. The output file is compatible with World Wide Web browsers.
This version is enhanced over the routine supplied by IDL, It will
also cross reference, print the purpose, and add links to the source
code.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
MK_HTML_HELP, Sources, Outfile
INPUTS:
Sources: A string or string array containing the name(s) of the
.pro or .tlb files (or the names of directories containing
such files) for which help is desired. If a source file is
a VMS text library, it must include the .TLB file extension.
If a source file is an IDL procedure, it must include the .PRO
file extension. All other source files are assumed to be
directories. If not provided, searches down directory tree
from current directory for files.
Outfile: The name of the output file which will be generated without
HTML extension.
If no inputs are given: All directories in the current directory tree
are used with the exception of: directories named: 'obsolete'
or 'SCCS.' (UNIX only)
KEYWORDS:
TITLE: If present, a string which supplies the name that
should appear as the Document Title for the help.
FILENAME: Alternative method of specifying Outfile (see above)
VERBOSE: Normally, MK_HTML_HELP does its work silently.
Setting this keyword to a non-zero value causes the procedure
to issue informational messages that indicate what it
is currently doing. !QUIET must be 0 for these messages
to appear.
STRICT: If this keyword is set to a non-zero value, MK_HTML_HELP will
adhere strictly to the HTML format by scanning the
the document headers for characters that are reserved in
HTML (",&,"). These are then converted to the appropriate
HTML syntax in the output file. By default, this keyword
is set to zero (to allow for faster processing).
CROSSLINK:If this keyword is set MK_HTML_HELP will create a cross
reference between library files.
CLTURBO: If this keyword is set to a single character string, then the
cross reference procedure will only cross reference lines that
contain the character given in CLTURBO. This greatly increases
the speed of the routine. By default the double quote (") is
used
PRINT_PURPOSE: If this keyword is set then the first line after PURPOSE:
is printed in the output file.
MASTLIST: If set, create master list only. Do not create subdirectory
file listings.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A help file with the name given by the Outfile argument is
created.
RESTRICTIONS:
The following rules must be followed in formatting the .pro
files that are to be searched.
(a) The first line of the documentation block contains
only the characters ";+", starting in column 1.
(b) There must be a line which contains the string "NAME:",
which is immediately followed by a line containing the
name of the procedure or function being described in
that documentation block. If this NAME field is not
present, the name of the source file will be used.
(c) The last line of the documentation block contains
only the characters ";-", starting in column 1.
(d) Every other line in the documentation block contains
a ";" in column 1.
Note that a single .pro file can contain multiple procedures and/or
functions, each with their own documentation blocks. If it is desired
to have "invisible" routines in a file, i.e. routines which are only
for internal use and should not appear in the help file, simply leave
out the ";+" and ";-" lines in the documentation block for those
routines.
No reformatting of the documentation is done.
MODIFICATION HISTORY:
July 5, 1995, DD, RSI. Original version.
July 13, 1995, Mark Rivers, University of Chicago. Added support for
multiple source directories and multiple documentation
headers per .pro file.
July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
At the end of each description block in the HTML file,
added a reference to the source .pro file.
July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
Changed calling sequence to accept .pro filenames, .tlb
text librarie names, and/or directory names.
Added code to set default subject to name of file if NAME
field is not present in the doc header.
September, 1995, D. Larson. SSL Berkeley. Added crosslink, print_purpose
clturbo.
October 4, 1995, D. Larson. SSL Berkeley. Added link to source file.
October 3, 1996, F. Marcoline. SSL Berkeley. Added Alphabet Jumpline.
October 10, 1996, D. Larson. Added Listing by Directory.
FILE: mk_html_help2.pro
VERSION 1.26
LAST MODIFICATION: 99/04/22
(See ssl_general/misc/mk_html_help2.pro)
FUNCTION: ndimen PURPOSE: Returns the number of dimensions in an array. INPUT: array RETURNS number of dimensions (0 for scalers,-1 for undefined) SEE ALSO: "dimen", "data_type" CREATED BY: Davin Larson LAST MODIFICATION: @(#)ndimen.pro 1.6 97/03/10
(See ssl_general/misc/ndimen.pro)
NAME: nn
PURPOSE: Find the index of the data point(s) nearest to the specified time(s)
CALLING SEQUENCE: ind=nn(data,time)
INPUTS: data: a data structure, a tplot variable name/index,
or a time array
time: (double) seconds from 1970-01-01, scalar or array
if not present, "ctime" is called to get time(s)
OPTIONAL INPUTS: none
KEYWORD PARAMETERS: x, y, & v: set to named keywords to return the values
of the x, y, & v arrays, if applicable
OUTPUTS: a long scalar index or long array of indicies
on failure, returns: -2 if bad inputs,
-1 if nearest neighbor not found
EXAMPLE: ctime,times,npoints=2
inds=nn('Np',times)
get_data,'Np',data=dens & get_data,'Tp',data=temp
plot,dens.y(inds(0):inds(1)),temp(inds(0):inds(1))
LAST MODIFICATION: @(#)nn.pro 1.8 02/04/17
CREATED BY: Frank Marcoline
(See ssl_general/misc/nn.pro)
PROCEDURE: oplot_err, x, low, high PURPOSE: Plot error bars over a previously drawn plot.
(See ssl_general/misc/oplot_err.pro)
PROCEDURE: pclose INPUT: none PURPOSE: Close postscript file opened with popen, and change device back to default. If common block string 'printer_name' is set, then file is sent to that printer. SEE ALSO: "print_options" "popen" CREATED BY: Davin Larson LAST MODIFICATION: @(#)pclose.pro 1.10 99/02/18
(See ssl_general/misc/pclose.pro)
FUNCTION: plot_positions PURPOSE: Procedure that will compute plot positions for multiple plots per page. Created by Davin Larson
(See ssl_general/misc/plot_positions.pro)
PROCEDURE: popen, filename PURPOSE: Change plot device to postscript. INPUT: optional; if: string : string used as filename, '.ps' extension is added automatically integer X: filename set to 'plotX.ps'. value of x is incremented by 1. none: filename set to 'plot.ps' KEYWORDS: See print_options for info. COPY: pass COPY keyword to set_plot INTERP: pass INTERP keyword to set_plot (default is to have interp off) SEE ALSO: "pclose", "print_options", "popen_com" CREATED BY: Davin Larson LAST MODIFICATION: @(#)popen.pro 1.21 98/06/23
(See ssl_general/misc/popen.pro)
COMMON BLOCK: popen_com PURPOSE: Common block for print routines SEE ALSO: "popen","pclose", "print_options" CREATED BY: Davin Larson LAST MODIFICATION: @(#)popen_com.pro 1.10 97/12/05
(See ssl_general/misc/popen_com.pro)
PROCEDURE: printdat,x, [name]
PURPOSE:
Displays information and contents of a data variable.
This routine is most useful for displaying contents of complex
data structures.
If printdat is called without arguments then information on all variables
within the calling routine are displayed.
Keywords:
WIDTH: Width of screen.
MAX: Maximum number of array elements to print. (default is 5)
NSTRMAX Maximum number of structure (or pointer) elements to print.
(default is 3)
OUTSTRING=outstring : named variable in which the output is dumped.
Written by Davin Larson, May 1997.
(See ssl_general/misc/printdat.pro)
PROCEDURE: print_options PURPOSE: controls postscript printing options KEYWORDS: PORT: print pages in portrait format (default) LAND: print pages in landscape format BW: Use black and white mode (untested) COLOR: Use Color postscript (default) FUTURE OPTIONS: Ecapsulated postscript format changing plotting area SEE ALSO: "popen","pclose" CREATED BY: Davin Larson LAST MODIFICATION: @(#)print_options.pro 1.16 97/05/30
(See ssl_general/misc/print_options.pro)
FUNCTION: PTRACE()
PURPOSE: Returns a string that provides the current program location.
KEYWORDS:
OPTION: The value of the option is retained in a common block
OPTION=0 : returns null string
OPTION=1 : returns highest level routine name.
OPTION=2 : returns highest level routine name (indented).
OPTION=3 : returns all levels
Usage: Generally useful for debugging code and following code execution.
Example:
if keyword_set(verbose) then print,ptrace(),'X=',x
Written: Jan 2007, D. Larson
(See ssl_general/misc/ptrace.pro)
NAME: ptr_extract Function: ptrs = ptr_extract(p,EXCEPT=EXCEPT) Purpose: Recursively searches the input (of any type) and returns an array of all pointers found. This is useful for freeing pointers contained within some complicated structure heirachy or pointer list. if no pointers are found then a scaler null pointer is returned. This routine ignores object pointers! Keywords: EXCEPTPTRS = an array of pointers that should not be included in the output. Created by Davin Larson. May 2002.
(See ssl_general/misc/ptr_extract.pro)
PROCEDURE:
share_colors
PURPOSE:
Procedure that allows multiple IDL sessions to share the same color table.
The procedure should be called in each session before any
windows are created.
USAGE:
Typically this procedure will be put in a startup routine. such as:
share_colors,first=f
if f then loadct,39
KEYWORDS:
FIRST Named variable that will be set to 1 if this is the
first session, and set to 0 otherwise.
SIDE EFFECTS:
Creates a temporary file with the name 'idl_cmap:NAME' on the users home
directory where NAME is the name of the display machine.
This file is deleted upon exiting IDL.
The procedure is only useful on UNIX for users with a common home directory.
(See ssl_general/misc/share_colors.pro)
FUNCTION:
res = strfilter(stringarray,searchstring)
PURPOSE:
Returns the subset of stringarray that matchs searchstring
'*' will match all (non-null) strings
'' will match only the null string
Output can be modified with keywords
NOTE: this routine is very similar to the STRMATCH routine introduced in IDL 5.3
it has some enhancements that make it useful.
(i.e.: filterstring can also be an array)
INPUT:
stringarray: An array of strings to be filtered
searchstring: A string that may contain wildcard characters ("*")
(If searchstring is an array then results are OR'd together)
RETURN VALUE:
Either:
Array of matching strings.
or:
Array of string indices.
or:
Byte array with same dimension as input string.
Depends upon keyword setting (See below)
KEYWORDS:
FOLD_CASE: if set then CASE is ignored. (only IDL 5.3 and later)
STRING: if set then the matching strings are returned. (default)
INDEX: if set then the indices are returned.
BYTES: if set then a byte array is returned with same dimension as input string array (similar to STRMATCH).
NEGATE: pass only strings that do NOT match.
COUNT: A named variable that will contain the number of matched strings.
Limitations:
This function still needs modification to accept the '?' character
July 2000; modified to use the IDL strmatch function so that '?' is accepted for versions > 5.4
EXAMPLE:
Print,strfilter(findfile('*'),'*.pro',/negate) ; print all files that do NOT end in .pro
AUTHOR:
Davin Larson, Space Sciences Lab, Berkeley; Feb, 1999
VERSION: 01/10/08
(See ssl_general/misc/strfilter.pro)
FUNCTION:
STRIPPATH
DESCRIPTION:
Function that strips off any directory components from a full
file path, and returns the file name and directory components
seperately in the structure:
{file_cmp_str,file_name:'file',dir_name:'dir'}
This is only implemented for UNIX at this time.
USAGE (SAMPLE CODE FRAGMENT):
; find file component of /usr/lib/sendmail.cf
stripped_file = STRIPPATH('/usr/lib/sendmail.cf')
The variable stripped_file would contain:
stripped_file.file_name = 'sendmail.cf'
stripped_file.dir_name = '/usr/lib/'
REVISION HISTORY:
$LastChangedBy: kenb-mac $
$LastChangedDate: 2006-12-15 08:13:48 -0800 (Fri, 15 Dec 2006) $
$LastChangedRevision: 97 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/misc/strippath.pro $
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Oct. '92
Updated to use IDL 6.0 features for cross-platform usability.
(See ssl_general/misc/strippath.pro)
FUNCTION: struct_value(struc,name,default=default,index=index) PURPOSE: Returns the value of a structure element. Function equivalent to the procedure: "STR_ELEMENT" if "name" is an array then a new structure is returned with only the named values. Author: Davin Larson, 2006
(See ssl_general/misc/struct_value.pro)
PROCEDURE: str_element, struct, tagname, value
PURPOSE:
Find (or add) an element of a structure.
This procedure will not
Input:
struct, generic structure
tagname, string (tag name)
Output:
value, Named variable in which value of the structure element is returned.
Purpose:
Retrieves the value of a structure element. This function will not produce
an error if the tag and/or structure does not exist.
KEYWORDS:
SUCCESS: Named variable that will contain a 1 if the element was found
or a 0 if not found.
INDEX: a named variable in which the element index is returned. The index
will be -2 if struct is not a structure, -1 if the tag is not found,
and >= 0 if successful.
ADD_REPLACE: Set this keyword to add or replace a structure element.
DELETE: Set this keyword to delete the tagname.
CLOSEST: Set this keyword to allow near matchs (useful with _extra)
VALUE: (obsolete) alternate method of returning value. (Will not work with recursion)
Notes:
Value remains unchanged if the structure element does not exist.
If tagname contains a '.' then the structure is recursively searched and
index will be an array of indices.
If struct is an array then results may be unpredictable.
Modifications:
5/7/97: Added recursive searching of structure hierarchy. D. Larson
CREATED BY: Davin Larson
FILE: str_element.pro
VERSION 1.10
LAST MODIFICATION: 01/10/08
(See ssl_general/misc/str_element.pro)
NAME:
tclip
PURPOSE:
wapper for xclip.pro allowing input of tplot variable names
CALLING SEQUENCE:
tclip, varnames, amin, amax, _extra=_extra
INPUT:
varnames = an array (or scalar) of tplot variable names
amin, amax = the minumum and maximum values
KEYWORDS:
flag = the value that clipped data are set to, the default is
6.8792e28
new_varnames = if set,give these names to the clipped data, the
default is to append '_clip' to the input names and
pass out the names in the new_varnames variables,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variables, do not set this with new_varnames
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tclip.pro)
NAME:
tdeflag
PURPOSE:
wapper for xdeflag.pro allowing input of tplot variable names
CALLING SEQUENCE:
tdeflag, varnames, method, new_varnames=new_varnames, $
overwrite = overwrite, _extra=_extra
INPUT:
varnames = an array (or scalar) of tplot variable names
method = set to "repeat", this will repeat the last good value.
set to "linear", then linear interpolation is used, but for
the edges, the closest value is used, there is no
extrapolation
KEYWORDS:
flag = the value that deflagged data will be set to, the default is
6.8792e28, Nan's, Inf's are also deflagged
maxgap = the maximum number of rows that can be filled? the default
is n_elements(t)
new_varnames = if set,give these names to the deflagged data, the
default is to append '_deflag' to the input names and
pass out the names in the new_varnames variables,
Unless /overwrite is set
overwrite = if set, write the new data back to the old tplot
variables, do not set this with new_varnames
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/tdeflag.pro)
FUNCTION: time_double(time) NAME: time_double PURPOSE: A fast, vectorized routine that returns the number of seconds since 1970. INPUT: input can be of type: double(s) seconds since 1970 (returns the input) string(s) format: YYYY-MM-DD/hh:mm:ss see "time_string" structure(s) format returned in "time_struct" long array (MUST be 2 dimensional!) PB5 time (req. by CDF) OUTPUT: double, number of seconds since 1970 (UNIX time) KEYWORDS: EPOCH: if set, it implies the input is double precision EPOCH time. SEE ALSO: "time_string", "time_struct", "time_epoch", "time_pb5" NOTE: This routine works on vectors and is designed to be fast. Output will have the same dimensions as the input Out of range values are interpreted correctly. ie. 1994-13-1/12:61:00 will be treated as: 1995-1-1/13:01:00 CREATED BY: Davin Larson Oct 1996 FILE: time_double.pro VERSION: 1.9 LAST MODIFICATION: 01/07/12
(See ssl_general/misc/time_double.pro)
NAME: time_epoch PURPOSE: Returns the EPOCH time required by CDF files. USAGE: epoch = time_epoch(t) NOT TESTED!!! CREATED BY: Davin Larson Oct 1996 FILE: time_epoch.pro VERSION: 1.1 LAST MODIFICATION: 96/10/16
(See ssl_general/misc/time_epoch.pro)
NAME: time_pb5 PURPOSE: Returns the PB5 time required by CDF files. USAGE: pb5 = time_pb5(t) OUTPUT: 2 dimensional long integer array with dimensions: (n,3) Where n is the number of elements in t Not fully TESTED!!!! CREATED BY: Davin Larson Oct 1996 FILE: time_pb5.pro VERSION: 1.3 LAST MODIFICATION: 97/01/27
(See ssl_general/misc/time_pb5.pro)
PROCEDURE: time_stamp,charsize=charsize
PURPOSE:
Prints a time stamp along the lower right edge of the current plot box
KEYWORDS:
CHARSIZE: The character size to be used. Default is !p.charsize/2.
ON: if set, then timestamping is turned on. (No other action taken)
OFF: if set, then timestamping is turned off. (Until turned ON)
(See ssl_general/misc/time_stamp.pro)
FUNCTION: time_string(TIME)
NAME:
time_string
PURPOSE:
Converts time to a date string.
INPUTs:
TIME input can be a scaler or array of any dimension of type:
double(s) seconds since 1970
string(s) format: YYYY-MM-DD/hh:mm:ss
structure(s) format: given in "time_struct"
float(s)
longs(s)
values outside normal range will be corrected.
TFORMAT: a format string such as: "YYYY-MM-DD/hh:mm:ss.ff DOW TDIFF"
the following tokens are recognized:
YYYY - 4 digit year
yy - 2 digit year
MM - 2 digit month
DD - 2 digit date
hh - 2 digit hour
mm - 2 digit minute
ss - 2 digit seconds
MTH - 3 character month
DOW - 3 character Day of week
DOY - 3 character Day of week
TDIFF - 5 character, hours different from UTC (useful with LOCAL keyword)
if TFORMAT is defined then the following keywords are ignored.
KEYWORDS:
LOCAL_TIME ; if set then local time is displayed.
FORMAT: specifies output format.
FORMAT=0: YYYY-MM-DD/hh:mm:ss
FORMAT=1: YYYY Mon dd hhmm:ss
FORMAT=2: YYYYMMDD_hhmmss
FORMAT=3: YYYY MM dd hhmm:ss
FORMAT=4: YYYY-MM-DD/hh:mm:ss
FORMAT=5: YYYY/MM/DD hh:mm:ss
FORMAT=6: YYYYMMDDhhmmss
SQL: produces output format: "YYYY-MM-DD hh:mm:ss.sss"
(quotes included) which convenient for building SQL queries.
PRECISION: specifies precision
-5: Year only
-4: Year, month
-3: Year, month, date
-2: Year, month, date, hour
-1: Year, month, date, hour, minute
0: Year, month, date, hour, minute, sec
>0: fractional seconds
AUTOPREC If set PREC will automatically be set based on the array of times
DELTAT: (float) PREC set based on this precision.
DATE_ONLY: Same as PREC = -3
MSEC: Same as PREC = 3
OUTPUT:
string with the following format: YYYY-MM-DD/hh:mm:ss (Unless
modified by keywords.)
See Also: "time_double" , "time_struct" or "time_ticks"
NOTE:
This routine works on vectors and is designed to be fast.
Output will have the same dimensions as the input.
CREATED BY: Davin Larson Oct 1996
FILE: time_string.pro
VERSION: 1.14
LAST MODIFICATION: 02/11/01
(See ssl_general/misc/time_string.pro)
FUNCTION: time_struct(time) NAME: time_struct PURPOSE: A fast, vectorized routine that returns a time structure. INPUT: input can be of type: double(s) seconds since 1970 string(s) format: YYYY-MM-DD/hh:mm:ss structure(s) similar to format below. OUTPUT: structure with the following format: ** Structure TIME_STRUCT, 11 tags, length=40: YEAR INT 1970 ; year (0-14699) MONTH INT 1 ; month (1-12) DATE INT 1 ; date (1-31) HOUR INT 0 ; hours (0-23) MIN INT 0 ; minutes (0-59) SEC INT 0 ; seconds (0-59) FSEC DOUBLE 0.0000000 ; fractional seconds (0-.999999) DAYNUM LONG 719162 ; days since 0 AD (subject to change) DOY INT 0 ; day of year (1-366) DOW INT 3 ; day of week (subject to change) SOD DOUBLE 0.0000000 ; seconds of day See Also: "time_double", "time_string", "time_epoch", "time_pb5" NOTE: This routine works on vectors and is designed to be fast. Output will have the same dimensions as the input CREATED BY: Davin Larson Oct 1996 FILE: time_struct.pro VERSION: 1.15 LAST MODIFICATION: 02/11/01
(See ssl_general/misc/time_struct.pro)
FUNCTION: time_tk_str = time_ticks(timerange,offset)
NAME:
time_ticks
PURPOSE:
Returns a structure that can be used to create time ticks for a plot.
See "timetick" for more info
INPUT:
timerange: Two element vector specifying the time range of the plot
this input can be obtained from: "time_double", "time_struct"
or "time_string"
offset: named variable in which offset time is placed.
KEYWORDS:
NUM_LAB_MIN: minimum number of labels for bottom axis.
OUTPUT:
a structure that can be used with the _EXTRA keyword of the PLOT routine
See Also: "box", "tplot"
NOTES:
The returned time_tk_str has tags named so that it can be used
with the special _EXTRA keyword in the call to PLOT or OPLOT.
The offset value that is returned from timetick must be
subtracted from the time-axis data values before plotting.
This is to maintain resolution in the PLOT routines, which use
single precision floating point internally. Remember that if
the CURSOR routine is used to read a cursor position from the
plot, this offset will need to be added back to the time-axis
value to get seconds since 1970-01-01/00:00:00.
NOTE:
This routine is an enhanced version of the routine "timetick"
See this routine for more info on usage
WARNING!:
This routine does not yet work on very small time scales.
CREATED BY: Davin Larson Oct 1996
FILE: time_ticks.pro
VERSION: 1.16
LAST MODIFICATION: 02/04/17
(See ssl_general/misc/time_ticks.pro)
FUNCTION: trange_str,t1,t2 INPUT: t1,t2 doubles, seconds since 1970 OUTPUT: string with the format: 'YYYY-MM-DD/HH:MM:SS - HH:MM:SS' CREATED BY: Davin Larson LAST MODIFICATION: @(#)trange_str.pro 1.10 97/12/22
(See ssl_general/misc/trange_str.pro)
PROCEDURE: wi, wnum PURPOSE: Switch or open windows. INPUT: wnum - the window number. CREATED BY: REE, 95-10-23 completely rewritten by DEL 2006 FILE: wi.pro VERSION: 1.6 LAST MODIFICATION: 97/06/03
(See ssl_general/misc/wi.pro)
xclip
PURPOSE:
Replaces with FLAGs the values of the array that are BEYOND
the limits specified.
CALLING SEQUENCE:
xclip, amin, amax, y, flag=flag, _extra=_extra
INPUT:
amin, amax = the minumum and maximum values
y = the input array
OUTPUT:
y = set to flag for points less than amin or greater than amax
KEYWORDS:
flag = the value that clipped data will be set to, the default is
6.8792e28
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis'
clip_deflag.pro
9-feb-2007, change big value to Nan
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/xclip.pro)
xdeflag
PURPOSE:
Replaces FLAGs in arrays with interpolated or other values
CALLING SEQUENCE:
xdeflag, method, t, y, flag=flag, _extra=_extra
INPUT:
method = set to "repeat", this will repeat the last good value.
set to "linear", then linear interpolation is used, but for
the edges, the closest value is used, there is no
extrapolation
t = time array, in any useable tplot format
y = the input array, n_elements(t) by n
OUTPUT:
y = either interpolated or repated, where the value is > 0.98*flag,
or NaN
KEYWORDS:
flag = the value that flagged data are set to, the default is
6.8792e28
maxgap = the maximum number of rows that can be filled? the default
is n_elements(t)
HISTORY:
2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis' clip_deflag.pro
$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$
(See ssl_general/misc/xdeflag.pro)