Please find below automatically-generated documentation for "some" IDL software.
This "index" file is (hopefully correctly;-) hyperlinked to IDL source code.
Created by my_mk_html_help, which you can download as part of myidllib
Mattia Vaccari
Last modified : Mon Aug 30 11:39:32 2010.
NAME:
ASTROTV
PURPOSE:
Produce RA-DEC labelled "X" (800x800 pixel^2), Full-Size "Grabbed" JPG and "EPS"
(20x20 cm^2) plots of af image IM with an header HD, overplotting N-E arrows
INPUTS:
IM - Array containing some 2D image
HD - FITS header of IM
OUTPUTS:
None
KEYWORDS:
OUTDIR - in - output directory (defaults to '.')
PREFIX - in - filename prefix (defaults to 'idl')
TITLE - in - plot title (passed to imcontour)
MINVALUE - in - tvscale minvalue (passed to tvscale)
MAXVALUE - in - tvscale maxvalue (passed to tvscale)
EXAMPLES:
im=readfits('~/spitzer/swire/mips-ge/aal/mosaics_and_catalogues/70um_mosaics/mosaic_en2_70.fits.gz',hdr)
j0=where(finite(im) eq 0) & j1=where(finite(im) eq 1) & im[j0]=min(im[j1]) & astrotv,im,hdr
WRITTEN FILES:
PREFIX.jpg/eps (defaults to idl.jpg/eps)
SEE ALSO:
MAKE_IMAGE
HISTORY:
16 Nov 2004 Written by Mattia Vaccari
19 Apr 2005 Call to SCREEN_GRAB added and expanded doc
15 Aug 2009 TITLE, MINVALUE and MAXVALUE keywords added
06 Dec 2009 OUTDIR keyword and on_error,2 added
(See .//astrotv.pro)
NAME: CLOSEPS PURPOSE: Close a PS file with "suitable" plot parameters EXAMPLES: To be used together with closeps, e.g. openps ; Plot Commands... closeps MODIFICATION HISTORY: 11 May 2006 Adapted from Seb Oliver's ENDPS (Mattia Vaccari)
(See .//closeps.pro)
NAME: DEC2SEX PURPOSE: Convert Celestial Coordinates from Decimal to Sexagesimal Format RESTRICTIONS: !!! BEWARE !!! : no-frills routine. no checks on inputs! MODIFICATION HISTORY: 16 Jan 2005 Written by Mattia Vaccari
(See .//dec2sex.pro)
NAME: HISTOPLOT PURPOSE: Histogram Plotting Routine INPUTS: DATA data to be plotted BS data bin size ( optional, defaults to (max-min)/10 ) KEYWORDS: CUM Cumulative histogram (sums over increasing data values) INVCUM Inverse cumulative histogram (sums over decreasing data values) MIN Minimum value of data (or of alog10(data) if LOG is set) to be plotted MAX Maximum value of data (or of alog10(data) if LOG is set) to be plotted LOG Logarithmically bin data (if set, BS and MIN/MAX refer to the log-value while XRANGE refers to the lin-value) OVERPLOT Overplot FRACTION Plot fractional histogram values rather than numerical ones LINESTYLE Passed to PLOT, defaults to (2) 0 if OVERPLOT is (NOT) set XRANGE Passed to PLOT, defaults to [min,max] TITLE Passed to PLOT, defaults to '' XTITLE Passed to PLOT, defaults to '' YTITLE Passed to PLOT, defaults to '' ERRPLOT Plot +- SQRT(N) errors "around" histogram values FILL Fill Histogram (experimental and likely to break down on elaborate plots) COLOR Passed to PLOT, defaults to 255 (but overridden to 254 if EPS is set) EPS COLOR/THICK tuned for (E)PS output (works nicely with openps/closeps) PSYM Passed to PLOT, defaults to 10 (i.e. histogram) THICK Passed to PLOT, defaults to 1 (but overridden to 5 if EPS is set) S25 Plot histogram values / binsize * bincenter^2.5 (e.g. for astronomical source counts) YSF Y-axis Scale Factor (histogram values are multiplied by YSF) VERBOSE Print histogram values (and also values +- sqrt(values) if ERRPLOT is set) to terminal VARNAME Output histogram values (and also values +- sqrt(values) if ERRPLOT is set) to VARNAME FILENAME Print histogram values (and also values +- sqrt(values) if ERRPLOT is set) to FILENAME NOFIRSTBIN Suppress plotting of first (by default empty) bin NOLASTBIN Suppress plotting of last (by default empty) bin _EXTRA Extra keywords (passed to PLOT) NOTES: MIN : When MIN=0 is specified in calling the procedure things can get messy. Try and use a small MIN, instead! COLOR : When graphical output is being sent to the PS device, one must set COLOR=254 (i.e. black in the CURRENT version of MYCOLORS) in order for B&W effects to work properly. TODOS: Add BL (Bin Limits) keyword to specify bins exactly MODIFICATION HISTORY: 01 May 2001 Written by Mattia Vaccari 09 Oct 2003 Miscellaneous modifications: in particular, now handles logarithmically-binned histograms 14 Nov 2003 Minor debugging 04 Dec 2003 FRACTION keyword added and MIN/MAX debugging 19 Jan 2004 COLOR keyword added and LINESTYLE debugging 20 Jan 2004 COLOR keyword debugging 16 Nov 2004 Array containing histogram values is now zero-valued at extremes, and thus looks better in plot 29 Aug 2005 MIN and MAX keywords behaviour and other debugging 16 Jan 2006 S25 and YSF keywords added 19 Jan 2006 VERBOSE keyword added and LOG/MIN/MAX debugging 21 Jan 2006 INVCUM and PSYM keywords added 24 Jan 2006 XSTYLE, YSTYLE and ERRPLOT keywords added 06 Mar 2006 S25 debugging (Finally Correct!?) 14 Mar 2006 Contents of Output (to Screen & File) changed 31 Mar 2006 Error bars plotted the same color of data points 02 Apr 2006 Debugging of terminal output toggled by VERBBOSE keyword 15 Nov 2007 VARNAME keyword added 07 Dec 2007 THICK, NOFIRSTBIN and NOLASTBIN keywords added 14 Feb 2008 BS keyword made optional 14 Jun 2008 NODATA now also passed to ERRPLOT 01 Jul 2008 FILL keyword added 14 Jul 2008 PS keyword added 09 Feb 2009 FOR loop running index data type changed to LONG
(See .//histoplot.pro)
NAME: IMAGETRIM PURPOSE: Create/Write a (fits) trimmed version of an input (fits) image NB : input *can* be gzipped and output *is* gzipped INPUTS: FN (STRING) Input Filename KEYWORD PARAMETERS: FAC (INT) Trimming Factor SIDE EFFECTS: Writes file to disk MODIFICATION HISTORY: Written on 05 May 2010 by Mattia Vaccari
(See .//imagetrim.pro)
NAME: MAGERRSUM PURPOSE: Sum magnitude errors (companion routine to MAGSUM) MODIFICATION HISTORY: 27 Jul 2007 Written by Mattia Vaccari
(See .//magerrsum.pro)
NAME: MAGSUM PURPOSE: Sum magnitudes (companion routine to MAGERRSUM) MODIFICATION HISTORY: 27 Jul 2007 Written by Mattia Vaccari
(See .//magsum.pro)
NAME: MAKE_IMAGE PURPOSE: Make eps and png image of a sky field showing its coordinates and orientation INPUTS: IFN : Input File Name KEYWORDS: odir=odir ; Output Directory (default is './') ofn=ofn ; Output File Name without extension (default is 'idl') is=is ; Image Size i.e. size of larger side of eps file in cm (default is 20) ifr=ifr ; Image Fraction i.e. fraction of image covered by plot (default is 0.7) cm=cm : Color Map (default is 0) min=min ; (default is min(arr)) max=max ; (default is max(arr)) thick=thick ; axis/annotations/symbols thickness (default is 3) title=title ; Image Title (default is '') wc=wc ; Wild Card value for "no data" points invcols=invcols ; inverts color map noaxes=noaxes ; doesn't plot axes (or rather plots them outside EPS BB) EXAMPLES: ifn='~/spitzer/swire/mips-ge/aal/mosaics_and_catalogues/70um_mosaics/mosaic_en2_70.fits.gz' make_image,ifn WRITTEN FILES: ODIR/OFN.eps/png (defaults to ./idl.eps/png) SEE ALSO: ASTROTV MODIFICATION HISTORY: 07 Jul 2007 Written by Mattia Vaccari on 070707!;-) 11 Jul 2007 Variously tweaked by Mattia Vaccari
(See .//make_image.pro)
NAME: MAKE_MY_IDL_HELP PURPOSE: Generates HTML documentation to IDL software within a given directory defining hyperlinks to IDL source files CATEGORY: Help/Documentation KEYED INPUTS: DIR directory name (default is ".") FILE help file name (default is /my_idl_help.html") TITLE Title of the produced HTML file WRITTEN FILES: FILE DEPENDENCIES: Calls MY_MK_HTML_HELP MODIFICATION HISTORY: 02 Mar 2001 Written by Mattia Vaccari 07 May 2001 DIR and FILE keywords added (Mattia Vaccari) 25 Apr 2003 FILE default value changed and miscellaneous improvements: now calls MK_LARI_HTML_HELP, thus generating hyperlinks to software source (Mattia Vaccari) 05 Dec 2004 Refactored for general application. Now calls MY_MK_HTML_HELP (Mattia Vaccari) 12 Jan 2005 Debugging of DIR and FILE keywords (Mattia Vaccari)
(See .//make_my_idl_help.pro)
NAME: MYALIAS
NB : This is CIA's ALIAS procedure modified to allow its use
outside the CIA environment
!!! SEE BELOW FOR ORIGINAL ALIAS DOCUMENTATION AND CREDITS !!!
15 Apr 2008 - Adapted from ALIAS (Mattia Vaccari)
PURPOSE:
provides a lot of useful aliases to quit, delete, ... for a variety of
operation systems
CATEGORY: I-4 user
CALLING SEQUENCE:
look at the example section for the various functions
INPUTS: none
OPTIONAL INPUT PARAMETERS: none
KEYED INPUTS: none
OUTPUTS: none
OPTIONAL OUTPUT PARAMETERS: none
KEYED OUTPUTS: none
EXAMPLE:
quit
logout
bye
delete, filename
ls
h
hs, structure
hh, structure
pstat
pwd
lut, table
luts
display, image
disp, window=window
load, image
frame, cube, i
diso, im
load_cube, cube
clear
xblink, a, b, rate
spec, vector
eval, statement
pause, seconds
abort
top
man, command
info, table
setps
endps
ALGORITHM: straightforward
DEPENDENCIES:
none
COMMON BLOCKS:
none
SIDE EFFECTS: none
RESTRICTIONS: some commands are not supported under Mac OS Classic but
only under Mac OS X ( identified as !version.os='darwin' )
CALLED PROCEDURES AND FUNCTIONS:
quit
logout
bye
delete
ls
h
hs
hh
pstat
pwd
lut
luts
display
disp
load
frame
diso
load_cube
clear
xblink
spec
eval
pause
abort
top
man
info
setps
endps
widget_olh
SEE ALSO: none
MODIFICATION HISTORY:
13-Sep-1996 SO taken from anonymous unix source --- thanks!
28-JUL-1997 SO dealiased blink to avoid clash with generice blink function
05-Sep-1997 SO ciainfo as alias for widget_olh
25-mar-1998 SO put ciainfo as seperate routine
COPYRIGHT:
This routine belongs to the ISOCAM Interactive Analysis Package CIA.
CIA is a joint development by the ESA Astrophysics Division and the ISOCAM
Consortium led by the ISOCAM PI, C. Cesarsky, Direction des Sciences de la
Matiere, C.E.A., France.
Contributing ISOCAM Consortium institutes are Service d'Astrophysique (SAp,
Saclay, France) and Institut d'Astrophysique Spatiale (IAS, Orsay, France)
When publishing ISOCAM Data reduced with this analysis package, please
mention this in the acknowledgement the following way:
"The ISOCAM data presented in this paper was analysed using "CIA",
a joint development by the ESA Astrophysics Division and the ISOCAM
Consortium led by the ISOCAM PI, C. Cesarsky, Direction des Sciences de la
Matiere, C.E.A., France. "
Its use and distribution to authorised sites are free, as long as this header
text is not removed, or changed.
No warranties for installation/ support/ maintenance are given.
(See .//myalias.pro)
NAME:
MYCOLORS
PURPOSE:
Set up a few colors into low numbers on the LUT for use in graphs
NB : Black & White change roles when writing to PS!!!
Resulting colors
0: Black ( White if \INVBAW )
1: White ( Black if \INVBAW )
2: Red
3: Green
4: Blue
5: Yellow
6: Cyan
7: Magenta
8: Pink
9: Light Green
10: Blue-ish
11: Cyan-ish
12: Magenta-ish
13: Green-ish
14: Yellow-ish
15: Cyan-ish
16-253: Unchanged
254: Black ( White if \INVBAW )
255: White ( Black if \INVBAW )
CATEGORY:
Graphics - Color Handling
CALLING SEQUENCE:
MYCOLORS
KEYWORDS:
INVBAW (BIT) : Invert Black & White (i.e. Background & Foreground Colors) in Colormap
COMMON BLOCKS:
COLORS
SIDE EFFECTS:
Changes LUT
MODIFICATION HISTORY:
01 Jan 2001 Adapted from Seb Oliver's COLOURS by Mattia Vaccari
30 Oct 2004 Set color index 255 to white (Mattia Vaccari)
26 Jan 2006 Tinkered with 254 & 255 White/Black coloring (Mattia Vaccari)
05 Mar 2006 Tinkered with 254 & 255 White/Black coloring (Mattia Vaccari)
02 Jun 2008 Reworked (old and new) colors and \INVBAW added (Mattia Vaccari)
(See .//mycolors.pro)
NAME:
MYDBBUILD
NB : This is IDL astrolib's DBBUILD procedure modified to allow
its use on catalogues of up to 100 columns (rather than 30)
!!! SEE BELOW FOR ORIGINAL DBBUILD DOCUMENTATION AND CREDITS !!!
18 Nov 2006 - Extended to 100 columns by Mattia Vaccari
PURPOSE:
Build a database by appending new values for every item.
EXPLANATION:
The database must be opened for update (with DBOPEN) before calling
MYDBBUILD.
CALLING SEQUENCE:
MYDBBUILD, [ v1, v2, v3, v4......v100, /NOINDEX, /SILENT, STATUS = ]
INPUTS:
v1,v2....v100 - vectors containing values for all items in the database.
V1 contains values for the first item, V2 for the second, etc.
The number of vectors supplied must equal the number of items
(excluding entry number) in the database. The number of elements
in each vector should be the same. A multiple valued item
should be dimensioned NVALUE by NENTRY, where NVALUE is the number
of values, and NENTRY is the number of entries.
OPTIONAL INPUT KEYWORDS:
/NOINDEX - If this keyword is supplied and non-zero then MYDBBUILD will
*not* create an indexed file. Useful to save time if
MYDBBUILD is to be called several times and the indexed file need
only be created on the last call
/SILENT - If the keyword SILENT is set and non-zero, then MYDBBUILD
will not print a message when the index files are generated
OPTIONAL OUTPUT KEYWORD:
STATUS - Returns a status code denoting whether the operation was
successful (1) or unsuccessful (0). Useful when MYDBBUILD is
called from within other applications.
EXAMPLE:
Suppose a database named STARS contains the four items NAME,RA,DEC, and
FLUX. Assume that one already has the four vectors containing the
values, and that the database definition (.DBD) file already exists.
IDL> !PRIV=2 ;Writing to database requires !PRIV=2
IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file
IDL> dbopen,'stars',1 ;Open database for update
IDL> mydbbuild,name,ra,dec,flux ;Write 4 vectors into the database
NOTES:
Do not call DBCREATE before MYDBBUILD if you want to append entries to
an existing database
MYDBBUILD checks that each value vector matches the idl type given in the
database definition (..dbd) file, and that character strings are the
proper length.
REVISION HISTORY:
Written W. Landsman March, 1989
Added /NOINDEX keyword W. Landsman November, 1992
User no longer need supply all items W. Landsman December, 1992
Added STATUS keyword, William Thompson, GSFC, 1 April 1994
Added /SILENT keyword, William Thompson, GSFC, October 1995
Allow up to 30 items, fix problem if first item was multiple value
W. Landsman GSFC, July 1996
Faster build of external databases on big endian machines
W. Landsman GSFC, November 1997
Converted to IDL V5.0 W. Landsman 24-Nov-1997
Use SIZE(/TNAME) for error mesage display W.Landsman July 2001
Fix message display error introduced July 2001 W. Landsman Oct. 2001
(See .//mydbbuild.pro)
NAME:
MYFTAB_EXT
NB : This is IDL astrolib's FTAB_EXT procedure modified to allow
its use on files of up to 500 columns (rather than 9) and
!!! SEE BELOW FOR ORIGINAL READCOL DOCUMENTATION AND CREDITS !!!
06 Nov 2008 - Extended to 300 columns by Mattia Vaccari
14 Feb 2009 - NONFINITE keyword added by Mattia Vaccari
06 Mar 2009 - WILDCARD keyword added by Mattia Vaccari
13 Mar 2009 - WILDCARD keyword scope extended by Mattia Vaccari
17 Mar 2009 - Extended to 500 columns by Mattia Vaccari
PURPOSE:
Routine to extract columns from a FITS (binary or ASCII) table.
CALLING SEQUENCE:
MYFTAB_EXT, name_or_fcb, columns, v1, [v2,..,v500, ROWS=, EXTEN_NO=]
INPUTS:
name_or_fcb - either a scalar string giving the name of a FITS file
containing a (binary or ASCII) table, or an IDL structure
containing as file control block (FCB) returned by FITS_OPEN
If MYFTAB_EXT is to be called repeatedly on the same file, then
it is quicker to first open the file with FITS_OPEN, and then
pass the FCB structure to FTAB_EXT
columns - table columns to extract. Can be either
(1) String with names separated by commas
(2) Scalar or vector of column numbers
OUTPUTS:
v1,...,v500 - values for the columns. Up to 500 columns can be extracted
OPTIONAL INPUT KEYWORDS:
ROWS - scalar or vector giving row number(s) to extract
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned
EXTEN_NO - Extension number to process. If not set, then data is
extracted from the first extension in the file (EXTEN_NO=1)
NONFINITE - FLT(1) - if set, changes all numerical non-finite
input elements into NONFINITE
WILDCARD - FLT(N+1) if set, changes all numerical input elements equal to
WILDCARD[0:N-1] into WILDCARD[N] (done *after* NONFINITE)
NB : N must be at least 1, i.e.
EXAMPLES:
Read wavelength and flux vectors from the first extension of a
FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this
information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1
and 2). To read the data
IDL> myftab_ext,'spec.fit','wavelength,flux',w,f
or
IDL> myftab_ext,'spec.fit',[1,2],w,f
PROCEDURES CALLED:
FITS_READ, FITS_CLOSE, FTINFO, FTGET(), TBINFO, TBGET()
HISTORY:
version 1 W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
Improve speed processing binary tables W. Landsman March 2000
Use new FTINFO calling sequence W. Landsman May 2000
Don't call fits_close if fcb supplied W. Landsman May 2001
Use STRSPLIT to parse column string W. Landsman July 2002
Cleanup pointers in TBINFO structure W. Landsman November 2003
Avoid EXECUTE() if V6.1 or later W. Landsamn December 2006
(See .//myftab_ext.pro)
NAME: MYIDLRC PURPOSE: IDL StartUp File USE: Copy to ~/.idlrc ( or to otherwise defined defined $IDL_STARTUP ) RESTRICTIONS: Depends on (and initializes) NASA GSFC IDL "astrolib" MODIFICATION HISTORY: 01 Nov 2008 Written by Mattia Vaccari
(See .//myidlrc.pro)
NAME: MYJOURNAL PURPOSE: Opens a journal file named according to date & time of opening (e.g. journal_061225_210233.jou for 25 Dec 2006 21:02:33) CATEGORY: Journaling TODOS: Check whether a journal file is already open before issuing the JOURNAL command MODIFICATION HISTORY: 14 Mar 2001 Written by Mattia Vaccari 25 Dec 2006 Now checks whether a journal file is already open (Mattia Vaccari)
(See .//myjournal.pro)
NAME: MYOPLOT PURPOSE: Mattia's Very Own O-Plotting Routine INPUTS: X - abscissa/ordinate data points (if Y is/isnot set) Y (optional) - ordinate data points KEYWORDS: RED (SCL INT) - plotting reduction factor (one out of RED points is actually plotted) (e.g. for crowded plots and/or to speed up plotting) MODIFICATION HISTORY: 27 Nov 2007 Adapted from his own MYPLOT by Mattia Vaccari
(See .//myoplot.pro)
NAME: MYPLOT PURPOSE: Mattia's Very Own Plotting Routine INPUTS: X - abscissa/ordinate data points (if Y is/isnot set) Y (optional) - ordinate data points KEYWORDS: RED (SCL INT) - plotting reduction factor (one out of RED points is actually plotted) (e.g. for crowded plots and/or to speed up plotting) MODIFICATION HISTORY: 01 May 2007 Written by Mattia Vaccari
(See .//myplot.pro)
NAME:
MYPLOTCAT
PURPOSE :
Plot source catalogue as (RA,Dec) pairs onto a window (or eps file)
of the correct (x,y) size (ratio)
INPUTS:
RA & DEC (FLOAT) - RA and Dec of catalogue sources
PSYM (INT) - symbol code used in plotting sources (deafults to 3)
KEYWORDS:
EPS - writes to eps file rather than plotting window
OPENEPS - leave eps open after call (e.g. for overplotting)
RED (INT) - plotting reduction factor (one out of RED points is actually plotted)
(e.g. for crowded plots and/or to speed up plotting)
SIZE (INT) - size of larger side of the plotting window
(defaults to 800 and 20 for X and EPS)
NOARROWS if set, does NOT plot N-E arrows using ARROWS (default is to plot them)
ARRPOS [x,y] position of N-E arrows in /normal-ized device coordinates (defaults to [0.2,0.1])
_EXTRA - passed to PLOT
MODIFICATION HISTORY:
20 Jun 2008 Written by Mattia Vaccari
01 Aug 2008 EPS & OPENEPS keywords added (Mattia Vaccari)
14 Aug 2008 RA direction debugged and NOARROWS and ARRPOS keyword added (Mattia Vaccari)
10 Sep 2008 OPENEPS Debugging (Mattia Vaccari)
(See .//myplotcat.pro)
NAME:
MYREADCAT
PURPOSE:
Read tabulated data from FILENAME text file into DATA
structure containing all FILENAME columns as fields.
A 3-column catalogue would e.g. produce a structure
made up by the DATA.C0 , DATA.C1 and DATA.C2 fields
(Note the IDL-like 0-based indexing)
INPUTS:
FILENAME - Filename containing tabulated data (STRING)
OUTPUTS:
DATA - Structure whose fields array types are described by FORMAT
KEYWORDS:
SKIPLINE - # of leading lines to skip when reading DATA from FILENAME
NUMLINE - overall # of lines to be read into DATA from FILENAME
FORMAT - keyword passed to MYREADCOL
DELIMITER - identifies delimiter in counting columns and
keyword passed to MYREADCOL ( default to ' ' )
COMPRESS - if set, assumes input file is compressed using gzip
RESTRICTIONS:
NB : FILENAME must either contain numerical data only (see MYREADDATA),
or a combination of alphanumerical data suitably described by the
FORMAT keyword
DEPENDENCIES:
NB : !!! Works with IDL >= 5.6 only !!!
HISTORY:
29 Dec 2005 Adapted from his own MYREADDATA by Mattia Vaccari
15 May 2006 NUMLIME keyword added (Mattia Vaccari)
15 Jan 2007 on_error,2 added (Mattia Vaccari)
16 Jul 2007 DELIMITER keyword added and NUMLINE keyword debugged (Mattia Vaccari)
31 Jul 2007 SKIPLINE keyword debugged (Mattia Vaccari)
31 Oct 2009 COMPRESS keyword added (Mattia Vaccari)
(See .//myreadcat.pro)
NAME:
MYREADCOL
NB : This is IDL astrolib's READCOL procedure modified to allow
its use on files of up to 250 columns (rather than 25)
!!! SEE BELOW FOR ORIGINAL READCOL DOCUMENTATION AND CREDITS !!!
27 Oct 2004 - Extended to 50 columns by Mattia Vaccari
02 Dec 2004 - Extended to 250 columns by Mattia Vaccari
24 May 2008 - Added 'M' format for LONG64 by Mattia Vaccari
17 Mar 2009 - Extended to 500 columns by Mattia Vaccari
31 Oct 2009 - COMPRESS keyword added by Mattia Vaccari
EXTRA KEYWORDS:
COMPRESS - if set, assumes input file is compressed using gzip
PURPOSE:
Read a free-format ASCII file with columns of data into IDL vectors
EXPLANATION:
Lines of data not meeting the specified format (e.g. comments) are
ignored. Columns may be separated by commas or spaces.
Use READFMT to read a fixed-format ASCII file. Use RDFLOAT for
much faster I/O (but less flexibility). Use FORPRINT to write
columns of data (inverse of READCOL).
CALLING SEQUENCE:
MYREADCOL, name, v1, [ v2, v3, v4, v5, ... v500, COMMENT=
DELIMITER= ,FORMAT = , /DEBUG , /SILENT , SKIPLINE = , NUMLINE = ]
INPUTS:
NAME - Name of ASCII data file, scalar string. In VMS, an extension of
.DAT is assumed, if not supplied.
OPTIONAL INPUT KEYWORDS:
FORMAT - scalar string containing a letter specifying an IDL type
for each column of data to be read. Allowed letters are
A - string data, B - byte, D - double precision, F- floating
point, I - integer, L - longword, Z - longword hexadecimal,
and X - skip a column.
Columns without a specified format are assumed to be floating
point. Examples of valid values of FMT are
'A,B,I' ;First column to read as a character string, then
1 column of byte data, 1 column integer data
'L,L,L,L' ;Four columns will be read as longword arrays.
' ' ;All columns are floating point
If a FORMAT keyword string is not supplied, then all columns are
assumed to be floating point.
/SILENT - Normally, MYREADCOL will display each line that it skips over.
If SILENT is set and non-zero then these messages will be
suppressed.
/DEBUG - If this keyword is non-zero, then additional information is
printed as MYREADCOL attempts to read and interpret the file.
COMMENT - single character specifying comment signal. Any line
beginning with this character will be skipped. Default is
no comment lines.
DELIMITER - single character specifying delimiter used to separate
columns. Default is either a comma or a blank.
SKIPLINE - Scalar specifying number of lines to skip at the top of file
before reading. Default is to start at the first line.
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
OUTPUTS:
V1,V2,V3,...,V250 - IDL vectors to contain columns of data.
Up to 250 columns may be read. The type of the output vectors
are as specified by FORMAT.
EXAMPLES:
Each row in a file position.dat contains a star name and 6 columns
of data giving an RA and Dec in sexigesimal format. Read into IDL
variables. (NOTE: The star names must not include the delimiter
as a part of the name, no spaces or commas as default.)
IDL> FMT = 'A,I,I,F,I,I,F'
IDL> MYREADCOL,'position.dat',F=FMT,name,hr,min,sec,deg,dmin,dsec
The HR,MIN,DEG, and DMIN variables will be integer vectors.
Alternatively, all except the first column could be specified as
floating point.
IDL> MYREADCOL,'position.dat',F='A',name,hr,min,sec,deg,dmin,dsec
To read just the variables HR,MIN,SEC
IDL> MYREADCOL,'position.dat',F='X,I,I,F',HR,MIN,SEC
RESTRICTIONS:
This procedure is designed for generality and not for speed.
If a large ASCII file is to be read repeatedly, it may be worth
writing a specialized reader.
Columns to be read as strings must not contain the delimiter character
(i.e. commas or spaces by default). Either change the default
delimiter with the DELIMITER keyword, or use READFMT to read such files.
Numeric values are converted to specified format. For example,
the value 0.13 read with an 'I' format will be converted to 0.
PROCEDURES CALLED
GETTOK(), NUMLINES(), REPCHR(), STRNUMBER()
MINIMUM IDL VERSION:
V5.3 (Uses STRSPLIT)
REVISION HISTORY:
Written W. Landsman November, 1988
Modified J. Bloch June, 1991
(Fixed problem with over allocation of logical units.)
Added SKIPLINE and NUMLINE keywords W. Landsman March 92
Read a maximum of 25 cols. Joan Isensee, Hughes STX Corp., 15-SEP-93.
Call NUMLINES() function W. Landsman Feb. 1996
Added DELIMITER keyword W. Landsman Nov. 1999
Fix indexing typos (i for k) that mysteriously appeared W. L. Mar. 2000
Hexadecimal support added. MRG, RITSS, 15 March 2000.
Default is comma or space delimiters as advertised W.L. July 2001
Faster algorithm, use STRSPLIT if V5.3 or later W.L. May 2002
(See .//myreadcol.pro)
NAME: MYREADDATA PURPOSE: Read tabulated data from FILENAME text file into *one* double (by default, or single if SINGLE keyword is set) precision DATA array in a straightforward way, suitable e.g. for large catalogues. INPUTS: FILENAME - Filename containing tabulated data (STRING) OUTPUTS: DATA - double (by default, or single if SINGLE keyword is set) precision floating array containing data KEYWORDS: SKIPLINE - # of leading lines to skip when reading DATA from FILENAME NUMLINE - overall # of lines to be read into DATA from FILENAME SINGLE - if set, uses single rather than (default) double precision COMPRESS - if set, assumes input file is compressed using gzip RESTRICTIONS: NB : FILENAME must contain numerical data only, without any leading or trailing lines including data description or comments (apart from those skipped by using SKIPLINE) DEPENDENCIES: NB : !!! Works with IDL >= 5.6 only !!! HISTORY: 27 Oct 2004 Written by Mattia Vaccari 05 Nov 2004 Debugging (Mattia Vaccari) 09 Nov 2004 Debugging (Mattia Vaccari) 11 Nov 2004 Debugging (Mattia Vaccari) 14 Sep 2005 FREE_LUN,LUN added (Mattia Vaccari) 06 Mar 2006 Missing FREE_LUN,LUN added (Mattia Vaccari) 15 May 2006 NUMLIME keyword added (Mattia Vaccari) 15 Jan 2007 on_error,2 added (Mattia Vaccari) 06 Dec 2007 SINGLE keyword added (Mattia Vaccari) 31 Oct 2009 COMPRESS keyword added (Mattia Vaccari)
(See .//myreaddata.pro)
NAME:
MYREADFMT
NB : This is IDL astrolib's READFMT procedure modified to allow
its use on files of 1-250 or 300/400/500 (rather than 25) columns
!!! SEE BELOW FOR ORIGINAL READCOL DOCUMENTATION AND CREDITS !!!
03 Mar 2009 - Extended to 1-100 columns by Mattia Vaccari
17 Mar 2009 - Extended to 1-150 and 200/300/400/500 columns by Mattia Vaccari
17 Mar 2009 - Extended to 1-250 and 300/400/500 columns by Mattia Vaccari
31 Oct 2009 - COMPRESS keyword added by Mattia Vaccari
EXTRA KEYWORDS:
COMPRESS - if set, assumes input file is compressed using gzip
PURPOSE:
Quickly read a fixed format ASCII data file into IDL variables.
EXPLANATION:
Lines of data not meeting the specified format (e.g. comments) are
ignored.
To read a free format ASCII data file use the procedures
READCOL or RDFLOAT. To print (formatted or free) columns of data
use the procedure FORPRINT.
CALLING SEQUENCE:
READFMT, name, fmt, v1,[ v2, v3, v4, ..., v250,
/SILENT, /DEBUG, SKIPLINE= , NUMLINE =]
INPUTS:
NAME - Name of ASCII data file. An extension of .DAT is assumed,
if not supplied.
FMT - scalar string containing a valid FORTRAN read format.
Must include a field length specification. Cannot include
internal parenthesis. A format field must be included for
each output vector. Multiple format fields are allowed, but
the repetition factor must be less than 100, (.i.e. 19X is
allowed but 117X is illegal)
Examples of valid FMT values are
FMT = 'A7,3X,2I4' or FMT = '1H ,5I7,2A7'
Examples of INVALID FMT values are
FMT = 'A7,B3' ;'B' is not a valid FORTRAN format
FMT = 'A7,2(I3,F5.1)' ;Internal parenthesis not allowed
FMT = 'A7,F,I' ;Field length not included
OUTPUTS:
V1,V2,V3,...,V250 - IDL vectors to contain columns of data.
Up to 250 output vectors may be read. The type of the output
vectors are specified by FMT.
OPTIONAL KEYWORD INPUTS:
/SILENT - If this keyword is set and non-zero, then certain terminal
output is suppressed while reading the file
/DEBUG - Set this keyword to display additional information while
reading the file.
SKIPLINE - Scalar specifying number of lines to skip at the top of
file before reading. Default is to start at first line
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
EXAMPLES:
Each row in a fixed-format file POSITION.DAT contains a 5 character
star name and 6 columns of data giving an RA and Dec in sexigesimal
format. A possible format for such data might be
IDL> FMT = 'A5,2I3,F5.1,2x,3I3'
and the file could be quickly read with
IDL> READFMT,'POSITION', fmt, name, hr, min, sec, deg, dmin, dsec
NAME will be a string vector,SEC will be a floating point vector, and
the other vectors will be of integer type.
RESTRICTIONS:
This procedure is designed for generality and not for speed.
If a large ASCII file is to be read repeatedly, it may be worth
writing a specialized reader.
NOTES:
When reading a field with an integer format I<n>, the output vector is
byte - if n = 1
integer*2 - if 1 < n < 5
integer*4 - in all other cases
Octal ('O') and hexadecimal ('Z') formats are read into longwords
PROCEDURE CALLS:
GETTOK(), REMCHAR, ZPARCHECK
REVISION HISTORY:
Written W. Landsman November, 1988
Added SKIPLINE and NUMLINE keywords March 92
Allow up to 25 columns to be read June 92
Call NUMLINES() function Feb 1996
Converted to IDL V5.0 W. Landsman September 1997
Recognize 'O' and 'Z' formats W. Landsman September 1997
(See .//myreadfmt.pro)
NAME: MYSAVEALL PURPOSE: Save "all" current session in a straightforward and safe way CATEGORY: Utility - Saving WRITTEN FILES: SAVEFILE defined as in program listing MODIFICATION HISTORY: 01 Feb 2007 Adapted from hiw own MYSAVE & MYSAVECOM by Mattia Vaccari 25 May 2007 Changed from procedure into batch file to actually allow saving of variables!;-) (Mattia Vaccari)
(See .//mysaveall.pro)
MYSTAT
NB : This is CIA's STAT procedure modified to allow its use
outside the CIA environment
!!! SEE BELOW FOR ORIGINAL STAT DOCUMENTATION AND CREDITS !!!
10 Apr 2008 - Adapted from CIA's STAT by Mattia Vaccari
06 Nov 2008 - Keyword check debugging and MEAN and MEDIAN and
RMS and NPIX keywords added (Mattia Vaccari)
PURPOSE:
Give a set of frequently used statistical quantities
CATEGORY: III-3, internal
CALLING SEQUENCE:
MYSTAT, image, each=each, undef=undef
INPUTS:
image -- array or cube : IDL 2 or 3 dimensional image
OPTIONAL INPUT PARAMETERS: none
KEYED INPUTS:
each -- flag : to do statistics in each plane of a cube
undef -- float : an "undefined" value (excluded from computation)
out_tab -- strarr : puts results into a string array rather than printing them out to screen
mean -- float : mean
median -- float : median
rms -- float : rms
npix -- int : # of pixels
KEYED OUTPUTS:
out_tab -- strarr : standard output of MYSTAT
OPTIONAL OUTPUT PARAMETERS:
none
EXAMPLE:
ALGORITHM:
DEPENDENCIES:
COMMON BLOCKS:
SESSION_BLOCK, SESSION_MODE, ERROR_CURRENT, STATUS_BOOL
SIDE EFFECTS:
RESTRICTIONS:
CALLED PROCEDURES AND FUNCTIONS:
MODIFICATION HISTORY:
1-Sep-1995 Koryo Okumura written with template_gen
22-Jan-1996 Marc Sauvage added the out_tab keyword
02-Sep-1998 SO make the out_tab keyword work if it is not defined
beforehand
COPYRIGHT:
This routine belongs to the ISOCAM Interactive Analysis Package CIA.
CIA is a joint development by the ESA Astrophysics Division and the ISOCAM
Consortium led by the ISOCAM PI, C. Cesarsky, Direction des Sciences de la
Matiere, C.E.A., France.
Contributing ISOCAM Consortium institutes are Service d'Astrophysique (SAp,
Saclay, France) and Institut d'Astrophysique Spatiale (IAS, Orsay, France)
When publishing ISOCAM Data reduced with this analysis package, please
mention this in the acknowledgement the following way:
"The ISOCAM data presented in this paper was analysed using "CIA",
a joint development by the ESA Astrophysics Division and the ISOCAM
Consortium led by the ISOCAM PI, C. Cesarsky, Direction des Sciences de la
Matiere, C.E.A., France. "
Its use and distribution to authorised sites are free, as long as this header
text is not removed, or changed.
No warranties for installation/ support/ maintenance are given.
(See .//mystat.pro)
NAME: MY_MK_HTML_HELP PURPOSE: Generates HTML documentation to IDL software defining hyperlinks to IDL source files CATEGORY: Help/Documentation SEE ALSO: MK_HTML_HELP (IDL) MODIFICATION HISTORY: 28 Apr 2003 Adapted from MK_HTML_HELP by Mattia Vaccari to generate HTML help file with hyperlinks to IDL source files for "LARI Package" routines 05 Dec 2004 Refactored for general application (Mattia Vaccari) 10 Mar 2006 Changed author's contact info (Mattia Vaccari) 05 Sep 2006 Changed author's contact info (Mattia Vaccari)
(See .//my_mk_html_help.pro)
NAME: NOINDS PURPOSE: Find indices which are NOT in an index list, thus returning a "complementary" index list INPUTS: INDS - Index array ( e.g. [1,4,5,7,9] ) NELS - # of elements ( e.g 10 ) OUTPUTS: NOINDS - No-Index array ( e.g. [0,2,3,6,8] ) MODIFICATION HISTORY: 27 Oct 2006 Written by Mattia Vaccari 28 Feb 2009 on_error,2 added
(See .//noinds.pro)
NAME: OORMO PURPOSE: Returns "One OR Minus One" Integer Array RESTRICTIONS: If an element of ARG is neither '+' nor '-' RES will be 0 SEE ALSO: OORMO MODIFICATION HISTORY: 03 Mar 2009 Written by Mattia Vaccari
(See .//oormo.pro)
NAME: OPENPS PURPOSE: Open a PS file with "suitable" plot parameters KEYWORDS: _EXTRA Extra keywords (passed to DEVICE) EXAMPLE: To be used together with closeps, e.g. openps ; Plot Commands... closeps MODIFICATION HISTORY: 11 May 2006 Adapted from Seb Oliver's SETPS & SET_PLOT_PS (Mattia Vaccari) 27 Sep 2006 _EXTRA keyword added
(See .//openps.pro)
NAME: PORM PURPOSE: Returns "Plus OR Minus" String SEE ALSO: OROMO MODIFICATION HISTORY: 26 Jul 2007 Written by Mattia Vaccari 07 Dec 2007 Debugging
(See .//porm.pro)
NAME: SCREEN_GRAB PURPOSE: Write current window contents to file CATEGORY: Procedure - Utility - Send output to file INPUTS: None OPTIONAL INPUTS: file file name (defaults to pickfile) KEYED INPUTS: format format for image file jpg specfies jpg format (default) gif specfies gif format (may not be supported by some IDL licenses due to patent reasons) png specifies png format tiff specfies tiff format bmp specfies bmp format ps specifies ps format (not recommended!) back change "background" pixels to white and "foreground" pixels to black. In so doing, it is assumed that background color in the original image is indexed as "255" and foreground color as "0", pixels having these colors are pickes and thir colors are inverted, while other colors are left untouched, even if any color "combination" will change as well as a side effect. While this should work if one runs "COLOURS" first, these defaults may not reflect your color table of choice, therefore use BACK with care! COMMON BLOCKS: COLORS colour look-up table EXAMPLES: screen_grab,$ [file, format=format, gif=gif, bmp=bmp, jpg=jpg,$ tiff=tiff, png=png, ps=ps, back=back] SIDE EFFECTS: Writes file to disk MODIFICATION HISTORY: 01 Apr 2001 Adapted from Seb Oliver's SCREEN_GRAB by Mattia Vaccari by adding support for PS and PNG outout 11 Jun 2001 JPEG support added and BACK keyword removed (Mattia Vaccari) 06 Aug 2004 JPG & JPEG equivalent keywords now both supported (Mattia Vaccari) 21 Oct 2004 JPEG keyword dropped (Use JPG instead!) and BACK keyword reintroduced (Mattia Vaccari)
(See .//screen_grab.pro)
NAME: SEX2DEC PURPOSE: Convert Celestial Coordinates from Sexagesimal to Decimal Format RESTRICTIONS: !!! BEWARE !!! : no-frills routine. no checks on inputs! MODIFICATION HISTORY: 16 Jan 2005 Written by Mattia Vaccari
(See .//sex2dec.pro)