List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
ADD_SEPARATOR
PURPOSE:
Adds a pathname separator to the last character of
a file name or path name.
CATEGORY:
General
CALLING SEQUENCE:
NEWPATH = ADD_SEPARATOR( PATH )
INPUTS:
PATH -> Path name to append the separator character
to. If Unix, will append a "/" character. If
Windows, will append a "/" character. If
Macintosh, will append a ":" character.
KEYWORD PARAMETERS:
None
OUTPUTS:
NEWPATH -> Path name with separator appended to
the last character.
SUBROUTINES:
None
REQUIREMENTS:
Supports Unix, Windows, and Macintosh platforms.
NOTES:
None
EXAMPLE:
(1)
PATH = '/scratch/bmy'
NEWPATH = ADD_SEPARATOR( PATH )
/scratch/bmy/
; Adds a separator to the path "/scratch/bmy".
(2)
SEP = ADD_SEPARATOR()
PRINT, SEP
/
; Returns the default separator string
; (here we have assumed a Unix environment).
MODIFICATION HISTORY:
bmy, 03 May 2002: TOOLS VERSION 1.50
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/add_separator.pro)
NAME:
CHOICE
PURPOSE:
Allows user to choose interactively from several options.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = CHOICE( VALUES [,options] )
INPUTS:
VALUES -> a string array containing the selectable options
KEYWORD PARAMETERS:
TITLE -> title to be displayed on top of the selection menu
DEFAULT -> a default selection (to allow user to simply
press enter)
BY_INDEX -> return selection index rather than value
/NOABORT -> prevents addition of 'ABORT' to selection
OUTPUTS:
CHOICE returns a string containing the selected value or
the index of the selection if keyword /BY_INDEX is set.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
CHOICE automatically adds 'ABORT' to the list of selections.
If keyword BY_INDEX is set then ABORT will return -1
(unless /NOABORT keyword is set)
EXAMPLE:
DIRNAMES = [ '~my/dir/','~your/dir/','~any/dir']
DIR = CHOICE( DIRNAMES, TITLE='Select Directory' )
IF (DIR ne 'ABORT') THEN BEGIN
OPENR, U1, DIR+FILE, /GET_LUN
READF, U1, DATA
CLOSE, U1
FREE_LUN,U1
ENDIF ELSE PRINT,'ABORTED !'
; Allow user to pick a directory and then
; read a file from that directory.
MODIFICATION HISTORY:
mgs, 26 Sep 1997: VERSION 1.00
mgs, 17 Nov 1998: - added DEFAULT and NOABORT keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/choice.pro)
NAME:
CODE_TREE
PURPOSE:
This routine produces a tree structure for Fortran programs.
It will scan a directory for FORTRAN files and gather all
SUBROUTINE names and CALL statements. FUNCTIONS are not
parsed.
CATEGORY:
General
CALLING SEQUENCE:
CODE_TREE [, DEFAULT_PATH, DEFAULT_MAIN ] [ , /FILENAMES ]
INPUTS:
DEFAULT_PATH -> the default search path to look for FORTRAN files
DEFAULT_MAIN -> the default name of the main program file. Note
that code_tree will not work properly if the main file
contains subroutine definitions.
KEYWORD PARAMETERS:
/FILENAMES -> display the filename where each routine can be
found together with the routine name.
OUTPUTS:
A calling tree is generated on the screen or dumped into a file.
SUBROUTINES:
Several
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
CODE_TREE
MODIFICATION HISTORY:
99/5/18 Philip Cameron-Smith, Harvard
Initial code.
99/5/21 Philip Cameron-Smith, Harvard
Have included some of my utilities to allow easy distribution.
Added '1' to names to ensure no future conflicts.
99/5/24 Philip Cameron-Smith, Harvard
Now removes tabs and strings.
Various other improvements.
99/5/25 Philip Cameron-Smith, Harvard
Reversed order of path and filename arguments
Converted a "print" to a "printf,lun" to stop lines running
on when printing to a file.
Improved check for ENTRY before SUBROUTINE.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/code_tree.pro)
NAME:
CONVERT_INDEX
PURPOSE:
Converts a 1-D array index (such as is returned from
WHERE, UNIQ, etc) to the appropriate 1-D, 2-D, or 3-D
array indices
CATEGORY:
General
CALLING SEQUENCE:
RESULT = CONVERT_INDEX( Index, Dim )
INPUTS:
INDEX -> The 1-D array index to be converted to
multi-dimensional indices. INDEX is returned
to the calling program unchanged.
DIM -> A vector containing the dimensions of the array
for which multi-dimensional indices are required.
KEYWORD PARAMETERS:
FORTRAN -> Interpret array indices as FORTRAN indices, i.e.
starting from 1 instead of 0. This applies to INPUT
and OUTPUT indices!
OUTPUTS:
RESULT -> Returns either a vector index or a vector of
multi-dimensional array indices as the value of the
function. If INDEX is a 1-dimensional parameter, the
result will have n_elements(dim) dimensions. If INDEX
is a multidimensional parameter, the result will be
a scalar.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Right now only works for 3-D arrays and smaller. Will
eventually do the general case...
EXAMPLES:
(1)
PRINT, CONVERT_INDEX( [1,1], [2,2] )
3
(2)
PRINT, CONVERT_INDEX( [2,2], [2,2] )
% CONVERT_INDEX: Index[0] greater than Dim[0]
% CONVERT_INDEX: Index[1] greater than Dim[1]
6
(3)
PRINT, CONVERT_INDEX( [2,2], [2,2], /FORTRAN )
4 ; <<<-- shifted by 1 !
(4)
PRINT, CONVERT_INDEX( 72, [72,46,20] )
0 1 0
(5)
PRINT, CONVERT_INDEX( 72, [72,46,20], /FORTRAN )
72 1 1
MODIFICATION HISTORY:
bmy, 07 Oct 1998: VERSION 1.00
mgs, 07 Oct 1998: VERSION 1.20
- made result etc LONG arrays
- allow sany dimensions now
- added reverse operation if index is multidimensional
- added FORTRAN keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/convert_index.pro)
NAME:
CONVERT_LON
PURPOSE:
Convert longitudes from -180..180 to 0..360
or vice versa.
CATEGORY:
General
CALLING SEQUENCE:
CONVERT_LON, DATA, NAMES, [, KEywords ]
INPUTS:
DATA -> A data array (lines,vars) or vector containing
longitude data. If DATA is a 2D array, the NAMES
parameter must be given to identify the LONgitude variable.
NAMES -> A string list of variable names. The longitude data
must be labeled 'LON', unless specified with the LONNAME
keyword. The NAMES parameter is not needed, if a data
vector is passed.
KEYWORD PARAMETERS:
PACIFIC -> Convert longitudes from -180..180 to 0..360
ATLANTIC -> Convert from 0..360 to -180..180
LONNAME -> Name of the longitude variable if a name other
than 'LON' is used.
OUTPUTS:
The longitude column in the data array will be changed.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
LONDAT = [ -180.,-179.,-0.1,0.1,179.,180.,270.,359.]
CONVERT_LON, LONDAT, /PACIFIC
PRINT, LONDAT
180.000 181.000 359.900 0.100000
179.000 180.000 270.000 359.000
; Convert longitudes to 0..360
(2)
CONVERT_LON,londat,/Atlantic
PRINT, LONDAT
180.000 -179.000 -0.100006 0.100000
179.000 180.000 -90.0000 -1.00000
; Convert back to -180..180
MODIFICATION HISTORY:
mgs, 25 Aug 1998: VERSION 1.00
mgs, 19 May 1999: - now makes sure that longitude range does
not exceed -180..180 or 0..360
mgs, 24 Jun 1999: - bug fix: choked at missing values
bmy, 24 May 2007: TOOLS VERSION 2.06
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
phs, 19 Nov 2007: GAMAP VERSION 2.11
- now accept scalar
(See /n/home09/ryantosca/IDL/gamap2/general/convert_lon.pro)
NAME:
DATATYPE
PURPOSE:
Returns the number (or name) of the data type
of an IDL scalar, array, structure, or object.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = DATATYPE( Data [, Keywords ] )
INPUTS:
DATA -> A variable (scalar, array, structure, or object)
whose data type is desired.
KEYWORD PARAMETERS:
/NAME -> If set, will return the name of the data type
instead of the type number.
OUTPUTS:
The IDL data type number or data type name will be
contained in RESULT.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The IDL data type numbers are:
-----------------------------------------
0 : undefined 6 : complex
1 : byte 7 : string
2 : int 8 : structure
3 : long 9 : double complex
4 : float 10 : pointer
5 : double 11 : object reference
EXAMPLES:
PRINT, DATATYPE( 0d0 )
5
; Double precision data is type 5
PRINT, DATATYPE( 0d0, /Name )
DOUBLE
; Returns the name of the data type
MODIFICATION HISTORY:
bmy, 26 Jul 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/datatype.pro)
NAME:
DEFAULT_DIRS
PURPOSE:
Define a couple of system variables to facilitate
file searching across or in multiple platforms.
The settings are made depending on the host name which
is queried with getenv().
This file is meant to be modified for your own computing
environment and directory structure. It's probably a good
idea to include a call to Default_Dirs in your startup file.
A string (or string array) argument allows individual users
to add their own default settings for individual projects
(see INPUTS).
CATEGORY:
General
CALLING SEQUENCE:
DEFAULT_DIRS [,projectlist [,searchpath=searchpath] ]
INPUTS:
PROJECTLIST -> A string or string array containing the names
of projects of individual users for which additional
settings shall be made. For each entry for which a procedure
named default_.pro exists, this procedure
will be called with the host name (lower case) as argument.
If the procedure is not found, a warning message is issued.
KEYWORD PARAMETERS:
SEARCHPATH -> A string that will be inserted at the beginning
of the !PATH variable to look for the default_
procedures. This keyword is only evaluated when a
PROJECTLIST is present. For simplicity, the user must make sure
that SEARCHPATH adheres to the syntax of the curent OS. Since
DEFAULT_DIRS is usually caled from the startup file, this
shouldn't be too much of a problem.
/PRINT -> print all system variables ending in 'DIR' after
the definition.
OUTPUTS:
Various system variables are created. As a minimum, these are
!RootDir = the root of the file system
!HomeDir = the user's home directory
!DataDir = a general data depository
!TmpDir = a temporary directory
!FNSep = filename seperator ('/' for unix and '\' for windows)
Further project-specific directories should also end in 'Dir',
this allows an easy query of all default directories:
help,/system_variables,output=o
print,o[ where(strpos(o,'DIR') gt 0) ]
(see PRINT keyword).
******* NEED TO WORK THAT OUT !! ****** it's not that easy !!! *********
SUBROUTINES:
none.
REQUIREMENTS:
none.
NOTES:
This routine uses a common block (yes!) to remember whether
the user had already been warned about non-exisiting project
procedures. Therefore, when you add projects on the fly,
you can probably call default_dirs safely every time you wish
to compose a search mask.
EXAMPLE:
default_dirs ; set platform dependent default directories
default_dirs,['GTE','CTM'],searchpath='~/myprogs',/PRINT
; as above, but add definitions from default_gte.pro and
; default_ctm.pro which may be in ~/myprogs or the regular
; IDL search !PATH. Print all !...DIR system variables upon
; exit. See attached default_gte procedure for an example.
MODIFICATION HISTORY:
mgs, 12 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/default_dirs.pro)
NAME:
DEFAULT_GTE
PURPOSE:
Define default system variables for GTE data directories
and GTE programs. Specific entries are made for the
PEM-Tropics A and B projects.
This procedure is caled from DEFAULT_DIRS when 'GTE' is
added as an argument.
CATEGORY:
General
CALLING SEQUENCE:
DEFAULT_GTE,host
INPUTS:
HOST -> the name of the host computer which is running IDL.
In our environment these are sol or cyclope or now.
KEYWORD PARAMETERS:
OUTPUTS:
Additional system variables are created:
!GTE_Dir = home of GTE data on current platform
!PEMTA_Dir = PEM-Tropics A data
!PEMTB_Dir = PEM-Tropics B data
!GTE_Filetypes = list of fiel extensions used with GTE data
SUBROUTINES:
REQUIREMENTS:
It is assumed that this routine is called from DEFAULT_DIRS
although it should be working stand-alone as well.
NOTES:
EXAMPLE:
see default_dirs
MODIFICATION HISTORY:
mgs, 12 May 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/default_gte.pro)
NAME:
DEFAULT_RANGE (function)
PURPOSE:
Make sure a RANGE argument or keyword is a valid vector with
at least two elements. Can also be used to limit RANGE to
two elements. The argument may be a string containing one or
more numeric values delimited by almost any character
combination (including '..' and '-'). A '-' will be treated
as a separator if it is preceeded by a digit or not followed
by a digit. The resulting range will be sorted and spans the
minimum and maximum of the "data" given in the argument.
CATEGORY:
General
CALLING SEQUENCE:
RANGE = DEFAULT_RANGE( ARG, DEFAULT [,/LIMIT2] )
INPUTS:
ARG -> The range argument or keyword as passed into
a procedure or function. This can be an undefined
variable or a variable with 1 or more elements.
If ARG contains 1 element, it will be repeated
to range from and to the same number.
DEFAULT -> A 2-element vector containing the default range
if ARG is undefined. This argument is mandatory
although it is not used if ARG contains at least
1 element.
KEYWORD PARAMETERS:
/LIMIT2 -> Limit the resulting RANGE vector to 2 elements.
Default is to return *at least* 2 elements.
RANGE -> Limit the RANGE vector to minimum and maximum
value given by this keyword.
/NOSORT -> Do not sort the output. This can be useful for
longitude vectors spanning the Pacific ;-)
OUTPUTS:
RANGE -> A two (or more) element vector that can be used in
statements like WHERE(x ge RANGE[0] AND x lt RANGE[1]).
SUBROUTINES:
External Subroutines Required:
============================================
ISALGEBRAIC (function) ISDIGIT (function)
STRBREAK (function) STRREPL (function)
REQUIREMENTS:
None
NOTES:
This function is meant for argument checking in procedures
or functions, hence it will generally not be called from the
command line.
EXAMPLE:
LATRANGE = DEFAULT_RANGE( LATRANGE, [-90.,90.] )
; Suppose a procedure has a keyword parameter named
; LATRANGE. Before we use LATRANGE in any form, we
; should test it (as above). This ensures that we have
; at least 2 elements in LATRANGE and it defaults
; LATRANGE to the whole globe if nothing was passed
; in the LATRANGE keyword.
MODIFICATION HISTORY:
mgs, 29 Sep 1998: VERSION 1.00
mgs, 17 Nov 1998: - added string handling
- added RANGE and NOSORT keywords
bmy, 13 Jul 2001: TOOLS VERSION 1.48
- now uses new STRREPL function from mgs
bmy, 16 Jul 2001: - bug fix: only call STRREPL if there are
non-algebraic characters to be replaced
- eliminate call to obsolete STR_SEP function
bmy, 17 Jan 2002: TOOLS VERSION 1.50
- now call STRBREAK wrapper routine from
the TOOLS subdirectory for backwards
compatiblity for string-splitting
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/default_range.pro)
NAME:
DISTRIBUTE
PURPOSE:
Collect all the routine names and file names that are
used in a given program.
CATEGORY:
General
CALLING SEQUENCE:
DISTRIBUTE [, ROUTINENAME ]
INPUTS:
ROUTINENAME -> (OPTIONAL) The name of the routine to be
searched. If omitted, then the user will be prompted
to supply a file name via a dialog box.
KEYWORD PARAMETERS:
OUTFILE -> Name of file where output will be sent. If
OUTFILE is omitted then DISTRIBUTE will print the
information to the screen.
/NO_IDL -> Set this switch to exclude IDL library routines
from the search process.
OUTPUTS:
A list of filenames with full pathnames and a list of
routinenames together with the filenames where they can
be found. Sorry, for local files, no pathname is provided.
SUBROUTINES:
External Subroutines Required:
===============================
OPEN_FILE
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
Unfortunately there is no way to figure out which routines
really belong to a given ROUTINENNAME, so DISTRIBUTE will
always return too many routinenames and filenames, including
itself and FILE_EXIST, as well as a couple of IDL standard
library routines (The latter can be left out with the keyword
NO_IDL). In order to get the closest results, run DISTRIBUTE
only at the start of an IDL session.
EXAMPLE:
DISTRIBUTE, 'iterate'
; Get all routines that belong to "iterate.pro".
; A subsequent call with routinename 'create_master'
; will return both, the routines for "create_master.pro"
; and the routines for "iterate.pro".
MODIFICATION HISTORY:
mgs, 16 Nov 1997: VERSION 1.00
mgs, 20 Nov 1997: - added OUTFILE and NO_IDL keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use IDL routine RESOLVE_ALL
- Now use OPEN_FILE instead of OPENW
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/distribute.pro)
NAME:
EXTRACT_COMMENTS
PURPOSE:
Split a string returned from READDATA.PRO into
items of a string array.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = EXTRACT_COMMENTS( COMMENTS, INDEX, DELIM=' ' )
INPUTS:
COMMENTS -> String array of comment lines returned from
readdata.pro
INDEX -> line number of comments to be analyzed
KEYWORD PARAMETERS:
DELIM -> delimiter character between items. Default: 1 blank.
OUTPUTS:
RESULT -> A string array containing the single "words"
of 1 comment line.
SUBROUTINES:
External Subroutines Required:
===============================
STRBREAK (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
UNITS = EXTRACT_COMMENTS( comments, 2, delim=' ' )
MODIFICATION HISTORY:
mgs, 10 Nov 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now use version-independent STRBREAK
routine instead of older STR_SEP routine
(See /n/home09/ryantosca/IDL/gamap2/general/extract_comments.pro)
NAME:
GETDATABLOCK
PURPOSE:
Retrieve information stored in a DATA block somewhere
within an IDL routine. The DATA block must be "hidden"
as comment lines for the IDL compiler. The data will be
returned as string array.
CATEGORY:
General
CALLING SEQUENCE:
GETDATABLOCK, DATA [, FILENAME=FILENAME, ,LABEL=LABEL ]
INPUTS:
KEYWORD PARAMETERS:
FILENAME -> optional filename. Normally, the data block is
read from the file that contains the current procedure
LABEL -> a unique identifier for the start of the data block.
Default is '/DATA/'. The end of the data block is reached
at the end of file or if the block of comment lines ends.
OUTPUTS:
DATA -> a string array with the information contained in the
data block
SUBROUTINES:
External Subroutines Required:
======================================
FILE_EXIST (function) ROUTINE_NAME
REQUIREMENTS:
None
NOTES:
The file with the datablock is always searched in !PATH
EXAMPLE:
GETDATABLOCK, SDATA
; This will retrieve a data block labeled '/DATA/'
; from the file of the current IDL routine
MODIFICATION HISTORY:
mgs, 22 Apr 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/getdatablock.pro)
NAME:
IND_COMB
PURPOSE:
Combine two index arrays that result from different
WHERE calls to the same data set.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IND_COMB( INDEX1, INDEX2, TYPE [, keywords ] )
INPUTS:
INDEX1, INDEX2 --> the two index arrays (may be single
integers or -1, but must be given)
TYPE --> a string containing the type of index combination:
The result will contain an index value if the index is
contained in ...
type eq "OR": ... at least one of INDEX1 or INDEX2
type eq "AND": ... INDEX1 and INDEX2
type eq "NOR": ... neither INDEX1 nor INDEX2
type eq "XOR": ... only one of INDEX1 or INDEX2
type eq "NAND": ... not in both
The default combination is "OR".
KEYWORD PARAMETERS:
TOTALN --> optional: number of elements in the data set.
If not given, this value is calculated as
max([index1,index2]). If this argument is passed,
the user has full responsibility that array indices
are not exceeded. ATTENTION: types NAND and NOR may
give wrong results if TOTALN is not specified
(see example).
OUTPUTS:
RESULT -> An array of type lon that contains the combined
indices and can be used as an array subscript.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
DATA = FINDGEN(100)+1
IND1 = WHERE(DATA le 50)
IND2 = WHERE(DATA ge 50 AND DATA lt 80)
RES = IND_COMB(IND1,IND2,"OR")
print,'1:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"AND")
print,'2:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NOR") ; <------ WRONG !!
print,'3:',res
RES = IND_COMB(IND1,IND2,"NOR",TOTALN=100)
print,'4:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"XOR")
print,'5:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NAND") ; <------ WRONG !!
print,'6:',min(data(res)),max(data(res))
RES = IND_COMB(IND1,IND2,"NAND",TOTALN=100)
print,'7:',min(data(res)),max(data(res))
IDL will print:
1: 1 79
2: 50 50
3: -1 <------ WRONG !!
4: 80 100
5: 1 79
6: 1 79 <------ WRONG !!
7: 1 100
MODIFICATION HISTORY:
mgs, 04 Dec 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/ind_comb.pro)
NAME:
INV_INDEX
PURPOSE:
Find the indices that do NOT match a WHERE condition
CATEGORY:
General
CALLING SEQUENCE:
RESULT = INV_INDEX( INDEX, TOTALN )
INPUTS:
INDEX -> An index array, e.g. previously generated by a
WHERE command (may be -1)
TOTALN -> the number of elements in the reference data
set, i.e. totaln = n_elements(index)+n_elements(result)
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> an integer array with all indices that were NOT
in index or -1 if index was complete
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
The function returns -1 if one of the following errors occurs:
- invalid number of arguments
- index variable is undefined
- totaln is less than n_elements(index)
- totaln less or equal 1, i.e. no associated data
The last error does not produce an error message, since this
feature was found to be very useful (in EXPLORE, the widget based
interactive data explorer)
EXAMPLE:
DATA = FINDGEN( 50 )
INDEX = WHERE( DATA ge 25 )
INVERS = INV_INDEX( INDEX, N_ELEMENTS( DATA ) )
PRINT, INVERS
0 1 2 3 4 5 6 7 8 9
10 11 12 13 14 15 16 17 18 19
20 21 22 23 24
; Find the elements of DATA that are greater than 25
; and then print the inverse condition
MODIFICATION HISTORY:
mgs, 10 May 1997: VERSION 1.00
mgs, 18 Aug 1997: - added template and check if n_elements(index) eq 0
mgs, 05 Apr 1999: - bug fix: needed to make sure result is type long
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/inv_index.pro)
NAME:
IN_RANGE
PURPOSE:
IN_RANGE checks to see if an input value lies
between a minimum value and a maximum value.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IN_RANGE(VALUE, MINVAL, MAXVAL)
INPUTS:
VALUE -> The value to be checked
MINVAL -> The minimum value
MAXVAL -> The maximum value
KEYWORD PARAMETERS:
OUTPUTS:
If MINVAL <= VALUE <= MAXVAL, IN_RANGE returns 0
If VALUE < MINVAL, IN_RANGE returns 1
If VALUE > MAXVAL, IN_RANGE returns 1
SUBROUTINES:
None
REQUIREMENTS:
None
EXAMPLE:
IF ( NOT IN_RANGE( VALUE, 0, 100 ) ) $
THEN PRINT, 'VALUE is not in between 0-100'
; Print a message if VALUE lies outside
; of the range 0-100
MODIFICATION HISTORY:
bmy, 24 Sep 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments
(See /n/home09/ryantosca/IDL/gamap2/general/in_range.pro)
NAME:
IS_DEFINED
PURPOSE:
Tests if a program argument is defined (i.e. if it
was passed any value(s) from the calling program).
CATEGORY:
General
CALLING SEQUENCE:
RESULT = IS_DEFINED( ARG )
INPUTS:
ARG -> The argument to be tested.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, IS_DEFINED( ARG )
0
; Because ARG has not been yet assigned a value,
; IS_DEFINED( ARG ) returns 0.
(2)
ARG = 1
PRINT, IS_DEFINED( ARG )
1
; Because ARG now has not been yet assigned a value,
; IS_DEFINED( ARG ) now returns 1.
MODIFICATION HISTORY:
D.Fanning, 02 Jul 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/general/is_defined.pro)
NAME:
IS_SELECTED (function)
PURPOSE:
Return a boolean vector with 1 for each element of VAR
that is contained in SELECTION. This is a generalization
of WHERE(VAR eq value) in that value can be an array
instead of a single value.
CATEGORY:
General
CALLING SEQUENCE:
INDEX = IS_SELECTED(VAR,SELECTION)
INPUTS:
VAR -> The data vector
SELECTION -> A vector with chosen values. If no selection
is given, the function returns a vector with all entries
set to zero.
KEYWORD PARAMETERS:
none
OUTPUTS:
INDEX -> An integer vector of length n_elements(VAR)
that contains 1 for each element of VAR that has
one of the SELECTION values.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
A = [ 1, 1, 1, 2, 2, 3 ]
B = [ 2, 3 ]
PRINT, IS_SELECTED( A, B )
0 0 0 1 1 1
(2)
PRINT, WHERE( IS_SELECTED( A, B ) )
3 4 5
; (i.e. indices of A that correspond to a value of 2 or 3)
; equivalent to:
print,where(A eq 2 or A eq 3)
MODIFICATION HISTORY:
mgs, 19 Aug 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/is_selected.pro)
NAME:
LITTLE_ENDIAN (function)
PURPOSE:
Determines if the computer system on which we are
running IDL has little-endian byte ordering.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = LITTLE_ENDIAN
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
RESULT -> Returns 1 if the machine on which you are running IDL
is a little endian machine, or 0 otherwise.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
PRINT, LITTLE_ENDIAN
1
; Returns 1 if we are running IDL on a
; little-endian machine, or zero otherwise
MODIFICATION HISTORY:
R.Mallozi, 02 Jul 1998: INITIAL VERSION
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/little_endian.pro)
NAME:
LOOP
PURPOSE:
This routine provides a wrapper for function calls that accept
only scalars so that they can operate on arrays.
CATEGORY:
General
CALLING SEQUENCE:
RESULT = LOOP( name, arg, p1, p2, p3, p4)
INPUTS:
NAME -> the name of the function (string)
ARG -> the argument (array)
P1 .. P4 -> optional function parameters
KEYWORD PARAMETERS:
Unfortunately None. Would be nice if _EXTRA would work.
OUTPUTS:
RESULT -> Vector with the same number of elements as ARG.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
A = [ 0.05, 0.01, 0.001 ]
PRINT, LOOP( "CHISQR_CVF", A, 17 )
27.5871 33.4087 40.7903
; Define a vector of arguments and then then loop
; thru the vector, calling CHISQR_CVF each time.
; Then display the vector of results.
MODIFICATION HISTORY:
mgs, 05 Dec 1997: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/loop.pro)
NAME:
MAKE_SELECTION (function)
PURPOSE:
Convert an array of selected values to an index array that
identifies the selected values in a list or data array.
CATEGORY:
General
CALLING SEQUENCE:
INDEX = MAKE_SELECTION( NAMES, SELNAMES [,keywords] )
INPUTS:
NAMES -> A list or array of values to choose from
SELNAMES -> A list of selected values
KEYWORD PARAMETERS:
ONLY_VALID -> Return only indices of found values. Values not
found are skipped. Default is to return 1 index value for
each SELNAME, which is -1 if SELNAME is not contained in
NAMES. If ONLY_VALID is set, the -1 values will be deleted,
and a value of -1 indicates that no SELNAME has been found
at all.
REQUIRED -> Normally, MAKE_SELECTION will return indices for
all values that are found, simply ignoring the selected
values that are not in the NAMES array (although an error
message is displayed). Set this keyword to return with
-1 as soon as a selected value is not found.
QUIET -> Suppress printing of the error message if a
selected value is not found (the error condition will
still be set).
OUTPUTS:
INDEX -> A (long) array with indices to reference the
selected values in the NAMES array.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If the NAMES array contains multiple entries of the same value,
only the index to the first entry will be returned.
A selection can contain multiple instances of the same value.
The index array will contain one entry per selected item
(See example below)
EXAMPLES:
(1)
NAMES = [ 'Alfred','Anton','Peter','John','Mary']
INDEX = MAKE_SELECTION( NAMES, ['Peter','Mary'] )
PRINT, INDEX
2 4
(2)
VALS = INDGEN(20)
INDEX = MAKE_SELECTION( VALS, [9,-5,8,7,7,8,9] )
PRINT, INDEX
9 -1 8 7 7 8 9
(3)
INDEX = MAKE_SELECTION( VALS,[9,-5,8,7,7,8,9], /ONLY_VALID )
PRINT, INDEX
9 8 7 7 8 9
(4)
INDEX = MAKE_SELECTION( vals, [9,-5,8,7,7,8,9], /REQUIRED )
PRINT, INDEX
-1
MODIFICATION HISTORY:
mgs, 28 Aug 1998: VERSION 1.00
mgs, 29 Aug 1998: - changed behaviour and added ONLY_VALID keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/make_selection.pro)
NAME:
N_UNIQ (function)
PURPOSE:
Returns the number of unique elements in an array.
CATEGORY:
General
CALLING SEQUENCE:
Result = N_UNIQ( Arr )
INPUTS:
ARR -> The array to be searched for unique values.
KEYWORD PARAMETERS:
None
OUTPUTS:
Returns the number of unique values in ARR as the value
of the function
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
PRINT, N_UNIQ( [10, 20, 30] )
3
(2)
PRINT, N_UNIQ( [10,10] )
1
MODIFICATION HISTORY:
bmy, 17 Nov 1998: VERSION 1.00
mgs, 17 Nov 1998: - little streamlining
mgs, 16 Mar 1999: - don't print out warning for empty argument
and return 0 instead of -1
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/n_uniq.pro)
NAME:
PAUSE
PURPOSE:
Halts program execution until the user presses RETURN.
CATEGORY:
General
CALLING SEQUENCE:
PAUSE
INPUTS:
MSG -> Specify a message to be displayed before pausing
program execution. MSG may be omitted.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
PRINT, DATA
PAUSE
; Prints a data array and then pauses to allow
; the user time to examine the results.
PRINT, DATA
PAUSE, 'look at data'
; Same as above exmaple, but this time, print an
; informational message before pausing.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/pause.pro)
NAME:
PWD
PURPOSE:
Print current working directory
CATEGORY:
General
CALLING SEQUENCE:
PWD [,result]
INPUTS:
none
KEYWORD PARAMETERS:
none
OUTPUTS:
RESULT -> (optional) string containing the current directory
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Set !QUIET to 1 if you only want to return the working directory
but no screen output.
EXAMPLE:
PWD
; Prints current directory.
MODIFICATION HISTORY:
mgs, 23 Dec 1998: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/pwd.pro)
NAME:
RESOLVE_EVERY
PURPOSE:
Resolve (by compiling) all procedures and functions.
This is useful when preparing .sav files containing all the IDL
routines required for an application.
CATEGORY:
General
CALLING SEQUENCE:
RESOLVE_EVERY
INPUTS:
None.
KEYWORD PARAMETERS:
QUIET = if set, produce no messages.
SKIP_ROUTINES = an optional string array containing the names
of routines to NOT resolve. This is useful when a library
file containing the designated routines will be later included.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None
RESTRICTIONS:
Will not resolve procedures or functions that are called via
CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE. Only explicit calls
are resolved.
If an unresolved procedure or function is not in the IDL
search path, an error occurs, and no additional routines
are resolved.
PROCEDURE:
This routine iteratively determines the names of unresolved calls
to user-written or library procedures and functions, and then
compiles them. The process stops when there are no unresolved
routines.
EXAMPLE:
RESOLVE_EVERY.
MODIFICATION HISTORY:
Written by:
DMS, RSI, January, 1995.
DMS, RSI, April, 1997, Added SKIP_ROUTINES keyword.
mgs, Harvard, 21 Apr 1998: use findfile before trying to resolve
a routine
bmy, 28 May 2004: TOOLS VERSION 2.02
- Now use MFINDFILE which will call FILE_SEARCH
for IDL 5.5+ or FINDFILE for IDL 5.4-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/resolve_every.pro)
NAME:
UNDEFINE
PURPOSE:
The purpose of this program is to delete or undefine
an IDL program variable from within an IDL program or
at the IDL command line. It is a more powerful DELVAR.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1642 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
General
CALLING SEQUENCE:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted. Up to 10 variables may be specified as arguments.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97, from an original program
given to me by Andrew Cool, DSTO, Adelaide, Australia.
Simplified program so you can pass it an undefined variable. :-) 17 May 2000. DWF
Simplified it even more by removing the unnecessary SIZE function. 28 June 2002. DWF.
Added capability to delete up to 10 variables at suggestion of Craig Markwardt. 10 Jan 2008. DWF.
(See /n/home09/ryantosca/IDL/gamap2/general/undefine.pro)
NAME:
YESNO
PURPOSE:
Query user for decisions with only two possible answers.
CATEGORY:
General
CALLING SEQUENCE:
ANSWER = YESNO( QUESTION [,DEFAULT=DEFAULT ,/STRING ] )
INPUTS:
QUESTION -> A string containing the query. The following
will automatically be added to QUESTION: ' (Y/N) [x] : '
where x is replaced by the default selection.
KEYWORD PARAMETERS:
DEFAULT -> either 0 (for 'NO') or 1 (for 'YES'). Default is 0.
/QUIT_OPTION -> if set, the user can quit with 'Q'. This
option is appended to the (Y/N) string. YesNo returns
-1 if quit was selected.
/STRING -> set this keyword to return a 'Y' or 'N' instead
of the numerical values 0 or 1.
OUTPUTS:
ANSWER -> An integer 0 or 1 that can be used in boolean
expressions, or a 1 character string if /STRING is set.
-1 is returned if /QUIT was allowed and used.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
'0' or '1' are also accepted as input. Everything but
'y', 'Y', '1' is treated as 'N'. 'Q' or 'C' can both
be used to quit.
EXAMPLES:
(1)
IF ( YESNO( 'Shall we meet today?', DEFAULT=1) ) $
THEN GOTO, MEETING
(2)
ANS = YESNO( 'Do you really want to quit?' )
if ( ans ) then return
(3)
ANS = YESNO( 'Save data ?', /QUIT, default=1 )
IF ( ANS LT 0 ) THEN RETURN
MODIFICATION HISTORY:
mgs, 22 Jan 1999: VERSION 1.00
mgs, 23 Mar 1999: - added /QUIT option
- bug fix: '0' was recognized as 'Y'
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/general/yesno.pro)