My IDL Library - Version 0.1 - On-Line Help

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.


List of Routines


Routine Descriptions

ASTROTV

[Next Routine] [List of Routines]
 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)


CLOSEPS

[Previous Routine] [Next Routine] [List of Routines]
 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)


DEC2SEX

[Previous Routine] [Next Routine] [List of Routines]
 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)


HISTOPLOT

[Previous Routine] [Next Routine] [List of Routines]
 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)


IMAGETRIM

[Previous Routine] [Next Routine] [List of Routines]
 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)


MAGERRSUM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	MAGERRSUM

 PURPOSE:
	Sum magnitude errors (companion routine to MAGSUM)

 MODIFICATION HISTORY:
	27 Jul 2007	Written by Mattia Vaccari

(See .//magerrsum.pro)


MAGSUM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	MAGSUM

 PURPOSE:
	Sum magnitudes (companion routine to MAGERRSUM)

 MODIFICATION HISTORY:
	27 Jul 2007	Written by Mattia Vaccari

(See .//magsum.pro)


MAKE_IMAGE

[Previous Routine] [Next Routine] [List of Routines]
 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)


MAKE_MY_IDL_HELP

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYALIAS

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYCOLORS

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYDBBUILD

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYFTAB_EXT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYIDLRC

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYJOURNAL

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYOPLOT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYPLOT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYPLOTCAT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYREADCAT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYREADCOL

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYREADDATA

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYREADFMT

[Previous Routine] [Next Routine] [List of Routines]
 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)


MYSAVEALL

[Previous Routine] [Next Routine] [List of Routines]
 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

[Previous Routine] [Next Routine] [List of Routines]
       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)


MY_MK_HTML_HELP

[Previous Routine] [Next Routine] [List of Routines]
 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)


NOINDS

[Previous Routine] [Next Routine] [List of Routines]
 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)


OORMO

[Previous Routine] [Next Routine] [List of Routines]
 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)


OPENPS

[Previous Routine] [Next Routine] [List of Routines]
 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)


PORM

[Previous Routine] [Next Routine] [List of Routines]
 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)


SCREEN_GRAB

[Previous Routine] [Next Routine] [List of Routines]
 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)


SEX2DEC

[Previous Routine] [List of Routines]
 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)