Interactive Trace and Aperture Definition

By selecting "Interactive / User Defined" on the Object Finding section of the Extraction preferences, you will be presented with a GUI to aid in setting extraction parameters as the pipeline runs.  Depending on the type of data being used, you may set an object trace center and aperture for simple boxcar style extraction, or you may fit an object profile to a particular emission line and use this as the weighting function for optimal extraction.
The selection of boxcar versus optimal is an either/or choice, you can't run both together.  But they are launched from the same GUI.  The PRELIMINARIES section below describes this GUI and then you can refer to the relevant section for your particular choice of extraction method. 

PRELIMINARIES

For each exposure, FIREHOSE first performs a crude first-pass sky subtraction to assist in locating the object in the 2D frame.  A display GUI will pop up showing the sky-subtracted frame.  Below I show an example of this GUI for an object showing a single emission line near the center of the display but no continuum.

A summary of key commands may be obtained using the Help -> Aperture Def Help menu on the menubar. 

SET APERTURES FOR BOXCAR EXTRACTION (see below for interactive object profile fitting/optimal extraction)

To define the trace location using the GUI, center the cursor over the emission line (or any location on the image) and press the space bar.  A cross will appear to indicate the location of your choice.  You may define many crosses and the software will use the median spatial location for the aperture.

If you are not happy with your location, press "C" to clear and start over.  However if you are happy, press "O" to extend your trace location to all wavelengths/slits.  FIREHOSE uses the map of the order boundaries to define the shape of the trace.  A black line indicates where the center of the trace has been defined, as shown below.

Now you must define the extent of the extraction aperture.  For boxcar extraction this is simply the width of the boxcar function.  For optimal extraction we approximate the user-defined width as +/- 2 sigma for a Gaussian weighting function.

Press "A" or select "Apertures -> Define Center/Width" and the following dialog box should appear:

This box allows you to tweak the center location of the trace, and enter the extraction width by hand.  The aperture center is defined as the fractional location from the left edge of the slit to the right edge, with 0 being the left slit boundary and 1 being the right boundary.  The reason for this is that FIRE's prisms introduce optical distortions that make the plate scale non-uniform across the detector, but the fractional position is preserved.

The aperture radius is defined in pixels for software compatibility reasons.  This could be changed to match the fractional positions if there is an outcry from the user community.

When you enter in the desired values and click OK, the aperture boundaries are added to the GUI as dotted lines.

You may return to the aperture dialog box to readjust your values if you wish.  When you are happy, click "done" or type "q" to exit the aperture definition GUI and return to the pipeline.  Another xatv GUI may pop up immediately after to confirm your object placement; you can ignore this instance and quit out to proceed with the object extraction.

PROFILE FITTING FOR OPTIMAL EXTRACTION

As an alternative to boxcar/aperture extraction, it is also possible to trim a small region around an emission line to fit a spatial profile to the object for optimal extraction.  This feature is in the beta+ stage but appears to work stably.  At present, one can only fit to the profile of a single wavelength region from a single order (i.e. around a bright emission line like H alpha).  The profile fit in this way is then applied to the entire spectrum.  It is not possible to fit profiles on an order-by-order individual basis (it would require some extreme patience anyway).

To start this process, in the Extraction preferences, select Object Finding: Interactive/User Defined and Extraction Method: Optimal.  Then, as in the boxcar case FIREHOSE will solve for the wavelength map and present you with a first-pass sky subtracted frame as shown here: 

In this case I have zoomed in to the line of interest, an H alpha profile of a z = 1.7 galaxy.  Now, rather than defining the center of the aperture in spatial coordinates, you must define the bounds of the wavelength region of interest where you want to fit the profile. Since wavelengths run vertically in FIREHOSE frames, this means you need to set the bottom and top of the bounding region.  You do this by hovering the mouse over the desired bounds and pressing capital "B" and "T".  The display will show black lines indicating where it interpreted your top and bottom bounds to be drawn.

Once you have set the top and bottom bounds, the software will sum up the flux from pixels in that wavelength region and present the normalized pixel profile in a new window, where you can interactively fit a parametric model to the pixel values:

This GUI allows you to change the fitting function, order, and add and delete points. The x-axis runs from 0 to 1 where 0 represents the left boundary of the slit, and 1 represents the right boundary.  The object counts have been normalized by the total profile flux so as to provide a properly normalized profile for optimal extraction.  The default fitting function is a bspline, but you may use a number of choices including chebyshev and legendre polynomials.  

There is a small help menu indicating the range of commands one may use to control the fit.  Common options are to delete/undelete bad points (right mouse button) force a point to be added in a desired location (left mouse button), increase the fit order ('u') or decrease the fit order ('d').  You can also select a particular region for fitting using the combination "s-s" on the left and right bounds of the region of interest.  When you are satisfied with the fit, press 'q' or click "done" and the software will return you to the image GUI.  For reasons I don't understand, the colormap gets messed up when you do this, but do not worry, this is normal.

Press "q" again in the image GUI to move on to extraction.  The software will then create a 2D profile image based on the fit you just completed.  It will present you with another view of the 2D crude-sky-subtraction, this time showing the profile peak position, and the +/- 1 * FWHM boundary.

If your object is close to the edge of the slit (as in the example shown), one of the bounds sometimes lies outside of the order: do not worry.  This aperture is only used to run a quick boxcar prior to optimal extraction, for determining in what sequence the individual orders will be extracted.  The optimal extraction will not use any "aperture" per se, it only uses the profile weighting function that you have specified, and does not extend outside of the slit.  Generally, if the center trace lands on the middle of your object, you are good to go. 

If this plot does not look crazy, then you can hit "q" and then the optimal extraction begins.  For this sequence, FIREHOSE still makes local adjustments to the sky model during extraction, but it does not simultaneously update its estimate of the object profile model - i.e. it keeps the one that you fit.

PLEASE KEEP IN MIND: When you do interactive profile fitting like this, the extracted errors are only as good as your object profile model.  Check the error vector that comes out when you finish combining your spectra to 1D to see that they are sensible!