BASIC INSTRUCTIONS FOR HIIphot v5.1
-----------------------------------

David Thilker (dthilker@pha.jhu.edu)
14 July 2000


{INSTALLATION}

+++ Put the file HIIphot.pro into a special directory and define
+++ an environment variable 'HIIphot' pointing to this location
+++ (best done in your .cshrc file or the local equivalent)

+++ Make sure that the astronomy user's library and Eric Deutsch's
+++ IMGroam library are both installed globally on your system.  Go to
+++ http://www.astro.washington.edu/~deutsch for information on
+++ how to do this.

+++ If you are unsure if these libraries are installed... start IDL
+++ with 'idl' on command-line, and type 'astrolib' -- you should see:

IDL> astrolib
% Compiled module: ASTROLIB.
% ASTROLIB: Astronomy Library system variables have been added

+++ For The Deutsch library, start IDL, type 'imgroam' -- you should
+++ see:

IDL> imgroam
% Compiled module: IMGROAM.
Call: IDL> IMGROAM,image_array,[GEIS_header],[Returned_frame]
e.g.: IDL> IMGROAM,img1,h,frm


{REQUIRED DATA}

+++ At this point it is useful to gather your data and auxillary info.
+++ You need: (1) cont-sub, line-only image (preferably in EM, cm^-6 pc)
+++               ... at the very least you need to know how to scale the
+++                   supplied line-only image into EM, HIIphot will ask.
+++           (2) continuum and line+cont images with sky bkgd (in ADU)
+++		  ... sky bkgd is req'd for reliable S/N estimation,
+++               ... as for the line-only image, HIIphot will ask how
+++		  ... to scale the cont and line+cont images into ADU
+++           (3) A/D gain, number of images combined per frame, pixel scale,
+++               galaxy distance (Mpc), PSF FWHM on line-only image (pix) 


{BATCH USE DEMO}

+++ If the libraries work OK, then you are ready to go.  CD to your data
+++ directory, start IDL, and do the following... This example shows
+++ how to set up HIIphot for batch operation, you can also compile
+++ as in the first line below and then type HIIphot to run fully
+++ interactively.  Batch mode is recommended, as it will not pause
+++ for inputs after lengthy periods of execution.  I suppose the first
+++ time or two you run the program, interactive use might be more
+++ appropriate.

IDL> .comp $HIIphot/HIIphot
% Compiled module: INDEX2COORD.
% Compiled module: COORD2INDEX.
% Compiled module: COORD2COORD.
% Compiled module: HIIPHOT.
% Compiled module: HIIPHOT_BATCH.
% Compiled module: SELECT_IMAGES.
% Compiled module: PSEUDO_LINECONTINUUM.
% Compiled module: GET_REGIONS.
% Compiled module: GET_FIND_INPUTS.
% Compiled module: CORR_STATISTICS_2D.
% Compiled module: SYM_MODEL.
% Compiled module: DISTORT.
% Compiled module: UPDATE_MAP_FILES.
% Compiled module: CHANGE_FILENAMES.
% Compiled module: ESTIMATE_ERROR_BEG.
% Compiled module: ESTIMATE_ERROR_END.
% Compiled module: DRAWBORDERS.
% Compiled module: GROWTH_SET.
% Compiled module: ECHO_HELP.
% Compiled module: FIND_MOD.

IDL> HIIphot_batch
% Running HIIphot_batch:
% 
% You will be prompted for a number of parameters to use during
% execution of HIIphot.  If in doubt, accept the DEFAULTS.  They
% have been chosen conservatively or using the image header.
% 
% After this code is finished, you may use the resulting files
% in one of two ways:
% 
% 1 - within IDL
% 
%     scorpio[91]% idl
%     IDL> .comp $HIIphot/HIIphot
%     IDL> HIIphot, batch='______.HIIphot_batch'
% 
% 2 - from the command line
% 
%     scorpio[92]% ______.HIIphot_batch.scr > ______.HIIphot_batch.log &
% 
% Note: ______ specifies the root name you will soon provide.
% 
% 
% Press any key to begin...

+++ At this point a series of pop-up windows lead you through
+++ selection of the continuum-sub image, the continuum image,
+++ and the line+continuum image.  You also have the option of
+++ supplying a 'blanking' image, which can be used to ignore
+++ polygonal regions in the subsequent photometry.

+++ Give a 'root' name for the scripts and setup files.  This rootname
+++ will also be applied to the output files when HIIphot is executed.

+++ Next, you will be given the option to inspect the continuum-sub
+++ image either at full resolution or regridded to fit in a 512^2
+++ window.  The purpose of this step is to select BLC, TRC pixel
+++ coordinates for a box containing all regions of interest.  (If you
+++ want to analyze the entire frame, just check out the image and
+++ then continue by exiting IMGroam (the image viewer) and then
+++ accepting the defaults for BLC, TRC.)  Instead of utilizing
+++ a rectangular region of interest, you may wish to draw a polygon
+++ containing all the objects.  This is accomplished with IMGroam's
+++ 'Define ROI' interface.  Follow the directions which pop-up on
+++ the terminal window for this tool.  If your image and desired ROI
+++ is large (initially bigger than 512^2) you need to select
+++ to inspect the regridded image rather than the data at full
+++ resolution.  NOTE: The 'Define ROI' instructions indicate that
+++ you are 'defining a new HII region'-- ignore this, it's a
+++ a carryover from a borrowed subroutine which is built-in to
+++ IMGroam.  ALSO NOTE: It is VERY wise to select a smallish ROI
+++ for analysis when you are first learning to use HIIphot!

+++ Define the sky region in a similar manner based on the line+cont
+++ image...  Make sure to pick a region containing enough pixels so
+++ that there are an appreciable number of independent samples even
+++ at low resolution.

+++ Answer the sequence of questions which comes next... a few
+++ comments are probably in order: (1) the first scale factor should
+++ be given as unity (the default) if images are supplied in the
+++ preferred manner (continuum-sub line-only image in EM), (2) the
+++ percent contribution is just the estimated percentage of H-alpha
+++ represented by [NII] emission which leaks through the bandpass,
+++ so I'm talking the intrinsic ratio modified by bandpass shape.
+++ If [NII]6548+6583 is intrinsically 0.4 x H-alpha and each [NII]
+++ line makes it through at the 50% level, then the appropriate
+++ percent contribution would be 20%., (3) the next scale factor
+++ is the factor applied to the cont-sub image to go from ADU to EM -
+++ if the image is still in ADU, then use unity -- normally this
+++ factor will be different from unity (if the input image is
+++ provided in EM), (4) the last two scale factors
+++ are unity if the continuum and line+cont images are supplied in
+++ ADU.

+++ One of the last questions asks if you want to use the DEFAULT
+++ parameters involving footprints, seeds, and growth.  Although the on-line
+++ instructions strongly recommend to accept the defaults, you may choose
+++ not to do so if you'd like several versions of region boundaries
+++ corresponding to different terminal surface brightness gradients.
+++ Accept the DEFAULTS for everything EXCEPT the TERMINAL gradient.  For this
+++ you might instead supply  "10,3,2,1.5,1" or something like that.
+++ This takes longer to run than the default "1.5,0,0,0,0", since
+++ there is much more work in terms of growth.

+++ To actually run the code, exit IDL, then issue the
+++ following command at the command-line:

______.HIIphot_batch.scr > ______.HIIphot_batch.log &

+++ where _____ signifies your rootname.

+++ The OUTPUT:  the photometry file is called '_____.catalog.dat'
+++ where _____ signifies your rootname.  There are also many images
+++ written in FITS format, reflecting the FOOTPRINT, SEED, and GROW
+++ stages of the program.  Of this variety there are '+BORDER' images
+++ which show the data frames with borders marked (all at 2x scale)
+++ and 'MAP' images which are just integer masks (with the region
+++ ID numbers indicated).