***** IRCAL reduction pipeline README file *****

code by Mike Liu, James Lloyd, and Marshall Perrin, et al.
approximately 1995-2006.

No warranties, use at your own risk, etc etc etc. ;-)


This directory contains the IRCAL pipeline; much of the guts of the code is in the "companions" directory
since it was developed for the Lick AO companion search - but of course most of it is generally applicable to
any sort of IRCAL project.

This isn't really a fully automated pipeline, but rather a mostly-automated series of reduction scripts which 
can be used to reduce IRCAL data, with plenty of opportunities for human decision making along the way.

IRCAL produces an automated logsheet file recording each event during a given night. The first step in the reduction
process is a Perl script that reads this log sheet file and then generates a list of IDL commands that will reduce
the data. You can then simply run all the IDL commands as-is for fully automated reduction, or you can modify the
IDL commands to, e.g., remove bad frames, select different mosaicing options, correct for other errors, etc.



Assumptions:

  Your working directory should have two subdirectories: 
	 ./calib	will contain calibration data produced by the pipeline (darks and flats)
	 ./data		contains the raw FITS files (or FITS.GZ) from IRCAL
  You need to make sure ./data is there yourself; the perl script will create ./calib if it needs to.
  Your working directory also should contain a copy of the logsheet file from IRCAL.

  The IDL code must all be in your IDL path, and the perl code should be in your shell's $PATH.

1. Log sheet parsing. 

  ircal-logparse.pl <logsheetfilename> <datadir> <outputdir>
  
	datadir is the directory containing the raw data; output dir is where the output should go.
  	Example: ircal-logparse.pl ircal041010.log ./data .

	The above script will produce a file named '<logsheetfilename>.reduce' containing a bunch of
	IDL commands, along with a .summary file containing a summary of the night's events. 

2. Dark frames:

	bias, <start>, <end>, /ircal,/auto

	start and end are single file numbers. 
	/auto is an optional switch: leave it off and the program will interactively show you what it's
	doing and ask for confirmation. Set it and it all happens automatically (recommended).

3. Flats

	There are two possible routines which create flat fields, using different algorithms.
	Which is best will depend on your input data - mktwiflat is only usable for exposures on the twilight
	sky with varying illumination levels. mkskyflat will work on twilight frames, dome lamp frames, or night
	sky frames. When in doubt, use mkskyflat. 


	mktwiflat, <start>, <end>, outname=<outfilename> ,/auto		the slope-fitting version
	mkskyflat, <start>, <end>, outname=<outfilename> ,/auto 	the median-combining version

		outputfilename should be something like "twiflat-Ks" or very similar to that.
		For the automatic flat detection to work in the reduction later, it MUST be named
		something matching the pattern "*flat*Ks" (or whatever the appropriate filter is if not Ks).

		start and end can either be single file numbers, or lists of file numbers. 

	Example: mktwiflat,[0119,0143,0167],[0126,0150,0174], outname="twiflat-H"

4. Reduction

	The main routine here is 'redircalsub', for Reduce IRCAL with Subpixel shifts. This will load raw
	frames; correct for bias, flat fielding, and bad pixels; correct for anamorphism; register frames;
	mosaic together; and correct for the 'pulldown' ghosts caused around very bright stars. 

	redircalsub, "<objname>", <start>, <end>, <fraction> ,   /subpixel, /fixpix, /satmask, ,/medsky, /auto

	objname is the name to use for the output file (overrides whatever is in the FITS header)
	fraction is the fraction (between 0 and 1.0) of the data files to keep
	/satmask	do saturation masking
	/subpixel	do subpixel registration	see mosf.pro and subreg.pro for more options on algorithms
	/fixpix		use bad pixel interpolator
	/medsky		compute the median frame of the stack and subtract it from each frame.
	/dewarp		correct anamorphic plate scale by interpolating from 0.078/0.075 mas/pixel to 0.040 mas/pixel 

	Alternatively, instead of using <start> and <end>, you can create a text file containing a list of filenames
	(including paths) and pass that in using the "listfile=" option. In this case, let start and end be 0 as a placeholder.
	
	Example:  redircalsub,"HD190771",0522,0611,0.8,outdir="./HD190771",/subpixel,/satmask,/fixpix,/auto ; H 30000:16:16
		  redircalsub,"HD_18803", 0, 0, 0.9, listfile="hd19903.txt', /subpixel, subshift="F", submethod="HF", /auto

	There will be several output files, including the original mosaic, the pulldown-ghost-corrected mosaic, the
	exposure map, and a 'radial-noise-normalized' mosaic (which flattens the dynamic range to aid detection of faint
	companions, using an algorithm bu Mike Liu)


###################################################
HISTORY

Original codebase by J. P. Lloyd and M. Liu, 1999-2002
Modified and expanded by M. D. Perrin 2002-2006

Tar file updates:
2006-12-08	misc refresh
2007-03-20	update for other IRCAL users
2007-06-18	add missing dependencies, thanks to N. McConnell

