Marshall Perrin's IDL Routines

List Last updated: Mon Sep 17 17:04:02 2012.

Routines by Category

Categories: Astronomical Utility - Data Cubes - Database - I/O - Image Display - Image Processing - IRCAL Pipeline - Mathematics - Misc - Plotting - Programming

Astronomical Utility

FINDINGCHART - make a finding chart for an object on screen or PDF.
LASERTIMES - Compute the start and stop allowable times for the Lick Laser, in LST. These correspond to 11 pm and 5 am, local time (either PST or PDT)
LSTNOW - return current lst, for a given observatory
MAG_ERRPROP - Convert fluxes to magnitudes, with error propagation.
MULTIFINDINGCHART - call findingchart for a bunch of sources listed in a file.
SUNTIMES - compute APPROXIMATE sunrise and sunset times
ZD2AIRMASS - Compute airmass vs. zenith distance.

Data Cubes

CUBEDISP_GRIDSPEC - Overplot a grid of spectra on top of a greyscale image of a cube This was inspired by a figure in (I think) one of Tracey Beck's papers.
CUBE_COLLAPSE - Collapse a cube along the wavelength axis. The default is to average the cube, but there are options to median or total combine instead. There is some support for using quality flags to indicate bad pixels to skip when collapsing.
CUBE_GETWAVEAXIS - return which axis of a cube is the wavelength dimension
CUBE_READ - Read in a data cube into a standardized structure
CUBE_REBIN - Rebin a cube in the X and Y dimensions, while leaving the Z dimension unchanged.
CUBE_SUBTRACTCONTINUUM - Crude continuum subtraction for IFS datacubes Almost any algorithm will be better than this!
EXTAST3 - Extract ASTrometry parameters from a FITS image header. (3D version for datacubes)
PUTAST3 - Put WCS astrometry parameters into a given FITS header. (3D version for datacubes)
XYZ2ADL - Compute R.A., Dec, and Wavelength from X, Y, and Z and a FITS astrometry structure

Database

IS_MYSQL_PRESENT - Is there a mysql database here? This routine lets you run the code either with or without mysql, depending on the local machine functionality.
MYSQLCHECK - check that a connection to mysql is open; open one if it isn't
MYSQLQUERY2 - Submit MySQL query and get response as an array of structures.
QUERY_2MASS - Given a name, query the 2MASS catalog on Vizier for its J, H, and Ks magnitudes (and their errors).
QUERY_IRAS - Given a name, query the IRAS catalog on Vizier for its J, H, and Ks magnitudes (and their errors).
QUERY_USNOB -

I/O

APRINT - print something out formatted as an IDL array (i.e. in IDL source code syntax)
FITSLOADER - Loads a specified set of FITS files, locates appropriate bias and flat field files for them, applies these to calibrate them, and optionally scales the whole set to a fixed exposure time.
HDRCONCAT - Concatenates FITS headers into a 2D string array, doing intelligent things with axes sizes if needed.
HDRCOPY - copy keys from one header to another
PICKFITS - pick one or more fits files using the GUI and then load them.
READTEXT - read in a text file in its entirety into an array
SELECTFITS - The purpose of this program is to allow the user to select a FITS image file for reading. The image data is returned as the result of the function. The best feature of this program is the opportunity to browse the image before reading it.
SIGDISP - Like the IRCAL sigdisp, does a rough n-sigma linear stretch of an image.
SIXTY_STRING - Like the Goddard library's "sixty" but it returns strings of the format "DD:MM:SS". This is the inverse of ten_string.
STRC - Formats something as a string, removing the extra spaces and unnecessary zeros. Works on scalars or arrays.
SXPARARR - Like sxparr, but for an array of fits headers.
TEN_STRING - Does the same thing as the goddard IDL astro library's "ten" procedure (converts sexagesimal coords into decimal) but works on string arguments of the form "DD:MM:SS" or "DD MM SS".
TEXPRINT - print out an IDL array in LaTeX table syntax, suitable for pasting into your paper.

Image Display

ALOGSCALE - intelligently logarithmicly scale an image for display.
ASINHSCL_COLOR - RGB asinh scaling, in the manner of Lupton et al.
ASINHSCL_CONTOURS - create contour colors for overplotting.
ASINH_DEMO - demonstrate use of asinh scaling routines

Image Processing

AORADNORM - Given an image (presumably an AO image), create an unsharp masked image. then compute a radial noise profile for it and divide by the profile.
APPHOT - program to do circular aperture photometry on an image given aperture location, size, and inner and outer radius for sky subtraction annulus.
AUTOREGISTER - Automagically register a bunch of images.
AVGMED - Median average a stack of FITS images, with optional median weighting.
BIAS - quick script for making a bias frame and displaying useful info
CALCPHOTNOISE - Given an image, and a map of the exposure times for that image, compute the photon noise as a function of position.
CENPSFSUB - centroiding psf subtraction routine.
CROP_BADMASK - Given an image and a mask, crop the image to the minimum size which contains the mask.
FFTREBIN - Rebins an image by adding zeros in between the FFT components as necessary.
FFTSHIFT - shifts an image by (dx,dy) pixels using fourier transforms.
FFTSHIFTCUBE -
FFT_FILT - High- or Low-pass filter an image in Fourier space.
FINDMAXSTAR - given an image, finds the x,y coords of the brightest object present.
FITPLANE - Fits a plane to an image
FIXNANFITS - given the name of a fits file, open that file, fix all the NaN pixels in it by interpolating from the nearest neighbors, then re-save the file
FIXNANS - fix NANs in an image, e.g. before cross correlating or something.
FIXPIX - given a image or stack of images and a bad pixel mask, will fill in bad pixels by finding the NPIX nearest good pixels, toss the highest and lowest ones of the bunch, and then arithmatically average.
FWCENTROID - Implements the robust floating-window centroid algorithm adopted for JWST target acquisitions.
HIMCUT - Like 'IMCUT', cut out a subregion from an image, and update FITS header. Very similar to HEXTRACT, but with different arguments
IMAGE_SHIFT_MASKEDGES - When shifting an image, manipulate the bad pixel mask appropriately such that the correct edges of the shifted image are declared bad.
IMCENTERF - program to calculate the center of mass of an image around the point (x,y), return the answer in (xcen,ycen).
IMCUT - Function to cut out a square subsection out of an image, with the user specifying the center of the subsection.
INDICES - like Python's indices command, returns coordinate indices for an array
MATCH_FILTER - Convolve an image with a normalized version of itself. Quick and dirty...
MATRIX_DFT - Matrix Discrete Fourier Transform, following Soummer et al. 2007. This is not as fast as an FFT, but allows you to arbitrarily choose the sampling and range covered in the Fourier domain.
MEANS - return the means for a stack of images
MEDARR2 - Like medarr, except you can specify a set of exposure times to scale the images by before taking their medians.
MKDOMEFLAT - makes a dome flat by loading a bunch of images, summing them, and then flattening. Optionally deals with polarization issues.
MKSKYFLAT - Median-combine a number of sky flat images into one master sky flat.
MKTWIFLAT - makes a flatfield from a series of images of the twilight sky using a iterative fitting technique for each pixels to measure the relative flatfield and to account for any constant (i.e. thermal) component. to be used for making infrared twiflats.
MOSF - routine to shift and stack a set of images to create a final mosaic, using masks to exclude bad pixels or cosmic rays
NEWSKYFLAT - Median-combine a number of sky flat images into one master sky flat.
OPTPSFSUB - Optimizing PSF subtraction routine.
OPTSUB - PSF Subtraction optimizer. Given two images already aligned, what scale factor optimizes their subtraction?
OPTSUBWITHOFFSET - PSF Subtraction optimizer. Given two images already aligned, what scale factor optimizes their subtraction? This version also solves for a constant shift between the two images.
RADGEN - Program to generate a 2-d image given 1-d profile (radial or elliptical) with a specified center and radial extent.
RADNOISE - plot radial noise profile
RADPLOTF - Program to calculate radial/elliptical profile of an image given aperture location, range of sizes, and inner and outer radius for sky subtraction annulus.
RECENTER - given an array of images and initial guesses for registration, calculate final offsets using IMCENTERF
REGISTER_DEMO - Demonstrate how to use subreg.pro and mosf.pro to register and mosaic images
SETSKY - Add offsets to images to make the background sky level equal to the background of the first image.
SKYSUB - subtract a 2d sky frame (or bias frame) from a 3d array of images by default, it will delete the input images unless /save
STAT - gives median, mean, min, max, and std deviation for a given image
STDDEVARR - compute the standard deviation for each pixel in a cube
STDDEVS - return the standard deviations for a stack of images
SUBMEDIAN - subtract the median from each slice of a data cube
SUBREG - subpixel registration of images
SUBREG_SHIFTSTOPEAKS - Given a shifts array created by subreg, convert this to an array of peak pixel locations in an image, as needed for input to the mosf function.
TUNEREGISTER - Tune up image registration. Takes an already-registered stack of images (possibly done by hand) then cuts out a subregion in it and runs subreg on that subregion.

IRCAL Pipeline

GETIRCALFILTER - Given a FITS header, returns a string describing the current IRCAL filter.
IRCALADDWCS - Add WCS coordinates to a FITS header for IRCAL
IRCALSTREHL - Compute Strehl for an IRCAL image.
IRCAL_BADPIXELS - Mark persistently bad ircal pixels as NANs usage: ircal_badpixels,imgs This isn't ALL the bad pixels, just ones that I can tell are bad but the automated stuff doesn't pick up for some reason.
IRCAL_BADPIXFROMLIST - Read bad pixel list from file and apply to an image stack
IRCAL_DEGHOST - remove annoying negative ghosts caused by channel crosstalk.
IRCAL_DEWARP - Remove distortion from an IRCAL image
IRCAL_DEWARP_SHIFTS - convert a list of image shifts from raw IRCAL coords to dewarped coords
IRCAL_FIXPIX - This is a front-end to ns_fixpix.pro which knows about the IRCAL bad corners and preserves them in the bad pixel mask.
IRCAL_GETJ2000 - Convert the current-epoch IRCAL coords into J2000 coords
IRCAL_REGRID - resample IRCAL images to compensate for anamorphic magnification
IRCAL_SATMASK - Determine saturated regions in IRCAL data and mask to NaN Also handles IRCAM and NIRC2 images.
IRCAL_ZEROPT - front-end routine for photometric calibration of IRCAL data
REDIRCALSKY - Version of IRCAL code for making sky files to input to redircalsub.
REDIRCALSUB - Reduction of IRCAL data with subpixel registration and mosaicing.

Mathematics

GAUSSIAN2D - Compute the 2-d Gaussian function and optionally the derivative based on Goddard IDL Astro's "Gaussian.pro" RESTRICTION: Right now only circularly symmetric gaussians
GRIDEVAL - Evaluates a function, supplied as a string, for all points of a supplied grid in x and y.
MAXES - return the maximums of each image for a stack of images
MODE - Calculate the mode (most common element in an array) optionally with binning
MONTECARLO_MEAN - given a set of numbers, uses monte-carlo methods to determine both the mean and the standard deviation of the mean.
MONTECARLO_MEDIAN - given a set of numbers, uses monte-carlo methods to determine both the median and the standard deviation of the median.
POISS - Computes the Poisson distribution as a function of X and M.
PRODUCT_ERRPROP - Implements the error propagation formula for the product of two numbers, assumed to have no correlation

Misc

ATV - Interactive display of 2-D or 3-D images.
ATVMAKEMOVIE - create a movie from an image stack in ATV.
FINDLOCALMAX - Find local maximum near given position in image
FIND_CLOSEST - Given an array, find the index whose value in that array is closest to a given number.
FIND_FWXM - Find the full width at X*max. i.e. X = 0.5 for FWHM.
MRECENTER - Find precise center for a star, like RECENTER, but using MPFITPEAK to do the peak fitting.
WHEREIS - Given the 1-d index of a pixel in an array, return the x and y coordinates corresponding to that pixel.
WHEREISMAX - Given an array, returns location and value of max pixel

Plotting

ALLSKYPLOT - plot some points on the whole sky
ARROWS2 - overplot an arrow on an image at a given position and angle.
DRAWSCALEBAR - Draw a scalebar on an image.
DRDPIX - Interactively display the X position, Y position, and pixel value of the cursor.
GETWHITE - return color table index for white, in either X or postscript mode.
HOR - Plot a horizontal line on a graph at specified y value.
IMCONTOUR - Make a contour plot labeled with astronomical coordinates.
IMDISP_GETAXES - create arrays with axes values for use with IMDISP
IMDISP_WITH_CONTOURS - imdisp an image, and overplot contours using subtle colors a la Tufte
LABELOPLOT - Like oplot, but labels the plot with some text string as well.
LOGHIST2D - Wrapper for hist2d which allows logarithmic bins and some other options
MULTIPLOT - Create multiple plots with shared axes.
PLOT_DRAWZOOMBOX - Draw zoom-in lines for a plot cutout.
PLOT_RECTANGLE - Draws a rectangle in data coordinates, optionally rotated
PLOT_RESTORECOORDS - counterpart to plot_savecoords
PLOT_SAVECOORDS - Save the current axis setup.
PPLOT - produce a pretty plot for postscript.
RADECGRID - draw a grid of lines of constant RA and Dec.
RAINBOW - Return a vector of color indices, from fsc_color.
SAVEPLOT - save a plot to disk in PNG format
VER - Plot a vertical line on a graph at specified x value.
WIN - create IDL plot windows displayed in rows in a nice tiled fashion.

Programming

CHECKDIR - Check whether a given directory exists
GETMYNAME - Returns the name and file path to the source code of the calling procedure
GETNUM - print a string and then let user enter a number just like READ command, except can enter to choose default and will re-prompt if user doesn't enter a number
GETYN - get a reply to a yes/no question, allowing the user to hit to select the default respone
HASNANS - does an array have NaNs in it?
STACKPOP - pops a variable off of a stack. NOTE If the stack only contains one item it becomes undefined after the item is popped off. see also stackpush.pro
STACKPUSH - pushes a variable onto a stack. If the stack is undefined, it is created.
STRUCT_MERGE - Given two structures, A and B, each of which may be an array, and which may have different tag names, create a new structure C which is the union of both A and B.
TIMEIT - test how long a given IDL command takes to execute.
WHICH - Prints full filenames in IDL !path search order for a particular routine.

Routine Descriptions

Category: Astronomical Utility

[List of Routines]

ZD2AIRMASS - Compute airmass vs. zenith distance.
LSTNOW - return current lst, for a given observatory
SUNTIMES - compute APPROXIMATE sunrise and sunset times
LASERTIMES - Compute the start and stop allowable times for the Lick Laser, in LST. These correspond to 11 pm and 5 am, local time (either PST or PDT)
FINDINGCHART - make a finding chart for an object on screen or PDF.
MULTIFINDINGCHART - call findingchart for a bunch of sources listed in a file.
MAG_ERRPROP - Convert fluxes to magnitudes, with error propagation.

ZD2AIRMASS

[Next Routine] [List of Routines]
(See sources/zd2airmass.pro)

 NAME: airmass

 PURPOSE:
 	Compute airmass vs. zenith distance.

 ALGORITHM:
 	Formula from John Huchra'a Harvard Ay192 notes, 1999.

 INPUTS:
 	zd	zenith distance, in degrees
 KEYWORDS:
 OUTPUTS:

 HISTORY:
 	Began 2004-10-18 19:36:56 by Marshall Perrin

(See sources/zd2airmass.pro)

LSTNOW

[Previous Routine] [Next Routine] [List of Routines]
(See sources/lstnow.pro)

 NAME: lstnow

 PURPOSE:
 	return current lst, for a given observatory

 INPUTS:
 KEYWORDS:
 OUTPUTS:

 HISTORY:
 	Began 2005-07-14 17:30:20 by Marshall Perrin

(See sources/lstnow.pro)

SUNTIMES

[Previous Routine] [Next Routine] [List of Routines]
(See sources/suntimes.pro)

 NAME: suntimes

 PURPOSE:
 	compute APPROXIMATE sunrise and sunset times

 NOTES:
 	Uses algorithms from the
 	Buie Lowell IDL library.

 	This is not likely to be the most accurate thing in the world.

 	Particularly since it doesn't account for the motion of the sun
 	during the day in question.


 USAGE:
 	suntimes,jd,rise,set, [/today, /lst, obsname="lick", degrees=12]

 INPUTS:
 KEYWORDS:
		degrees=	how many degrees below the horizon? 
					Default is 0.25, so the sun is just tangent to the horizon
 		/lst		return results in LST, not CT
 
 OUTPUTS:

 HISTORY:
 	Began 2005-07-14 16:07:24 by Marshall Perrin 
 		see 'obsplan.pro' from the Buie library for algorithm source.

(See sources/suntimes.pro)

LASERTIMES

[Previous Routine] [Next Routine] [List of Routines]
(See sources/lasertimes.pro)

 NAME: lasertimes

 PURPOSE:
 	Compute the start and stop allowable times for the Lick Laser, in LST.
 	These correspond to 11 pm and 5 am, local time (either PST or PDT)

 USAGE:
 	suntimes,jd,rise,set, [/date, /lst]

 INPUTS:
 KEYWORDS:
 OUTPUTS:

 BUGS:
 		Not daylight savings time aware. It assumes that the entire year
 		uses whatever the current timezone setting is. (i.e. if it's
 		PDT when you run the program, it assumes it's -always- PDT, and
 		vice versa for PST)

 HISTORY:
 	Began 2005-07-14 16:07:24 by Marshall Perrin 
 		see 'obsplan.pro' from the Buie library for algorithm source.

(See sources/lasertimes.pro)

FINDINGCHART

[Previous Routine] [Next Routine] [List of Routines]
(See sources/findingchart.pro)

 NAME: findingchart.pro
 PURPOSE:
 	make a finding chart for an object on screen or PDF. 

 NOTES:
 	For Lick, you want to call this as
 		
		findingchart,"Vega", /ps

	This script requires the "skvbatch" and "webquery" perl scripts to 
	access SkyView at Goddard. Get them from here:
		http://skyview.gsfc.nasa.gov/downloads/software/batch/skvbatch
	It also requires a version of the Goddard IDL Astronomy library more
	recent than 2003-07-14, incorporating bug fixes to hrotate.pro and
	imcontour.pro which were added then.

 INPUTS:
 	objectname	a name or coordinates for an object suitable for SIMBAD.
 	
 KEYWORDS:
 	filename	File to use. If set, This file is used and labelled as
      		 	"objectname". If not set, the field containing 
     			objectname is downloaded from SkyView at Goddard. Once 
      			the data is downloaded, it is saved in the current 
 	         	directory for future use.
 	/noflip		don't flip the direction of the RA axis. Default is to 
 				flip it so as to match the geometry of the Lick display.
 	rotangle	Angle to rotate the image by, clockwise. If /flip is 
 	    		set, that happens first. Default is 23 degrees, which 
 	    		is the angle for the Lick guider camera.
 	/ps  		Output to a postscript file as well as to the screen.
        	 	The file will be named find_.ps
 	/forcedl	Force the download of data even if it wouldn't happen otherwise.
 				i.e. You can use this to re-download the image for a source
 				even if it's been saved already.
 OUTPUTS:

 HISTORY:
 	Began 2003-07-04 13:01:34 by Marshall Perrin 
 	Documentation added 2003-07-11   Marshall Perrin
 	2003-07-20		Added guider FOV outline. Marshall Perrin
 	2003-11-02		Lick finding camera is now rotated 180 degrees from where
					it used to be in July...

(See sources/findingchart.pro)

MULTIFINDINGCHART

[Previous Routine] [Next Routine] [List of Routines]
(See sources/multifindingchart.pro)

 NAME: multifindingchart
 PURPOSE:
 	call findingchart for a bunch of sources listed in a file.

 INPUTS:
 KEYWORDS:
 	/coords		use coords from the target file, not just names.
 				Useful for targets not in SIMBAD
 	wait=#		wait # seconds between images
 	/ps			write to PS
 OUTPUTS:

 HISTORY:
 	Began 2005-07-14 18:16:08 by Marshall Perrin 
 	2005-09-29	add