NAME

hstpolpoints -- Reduce linear polarization data for HST instruments for a set of apertures
USAGE hstpolpoints imalis errlis instpoltab pointab iterej sigsky outtab

PARAMETERS

imalis = "" [list of file names]
The list of input sky-subtracted images to be reduced. Upto 64 images can be input. They must all be of the same dimensions and are assumed to be aligned.
errlis = "" [list of file names]
The list of input error files corresponding to the sky-subtracted images. They must be of the same dimensions and the same as the input sky-subtracted images.
instpoltab = "" [table file name]
Name of STSDAS table file giving the parameters for polarization determination for the instrument corresponding to the input images. The table lists the polarizer filter name, the polarizer angle, the transmission for the components parallel and perpendicular to the polarizer axis, the transmission of the s and p rays (parallel and perpendicular to the pick-off mirror surface for the WFPC2 case) and the retardation of the s ray relative to the p ray, the instrumental polarization and its instrumental position angle.
pointab = "" [table file name]
Name of the STSDAS table detailing the input apertures for summing flux and sky. The table lists the aperture name, X and Y pixel centre, radius of object aperture, gap radius between object circle and sky annulus and width of sky annulus.
iterej = "" [integer]
Number of iterations for sigma clipping of mean sky.
sigsky = "" [real]
Factor times rms on mean for rejecting points from inclusion in the mean for the sky aperture.
outtab = "" [name]
Name of the STSDAS table for the output results. A 13 column table is produced listing the aperture names, X and Y positions (from the input pointab table) together with the normalised Stokes I, Q and U parameters and errors, the linear polarization and position angle and errors.

DESCRIPTION

This task is a tool for performing aperture polarimetry for data from those HST instruments with imaging polarizer facilities (currently FOC, WFPC2 and NICMOS). A non-HST instrument can also be handled - called 'SPECIAL'. The error frames are required to produce output error files and should contain all sources of error (photon noise, systematics (e.g. flat fielding errors) and read-out noise).
All instrument specific parameters are picked up from the header and the telescope rotation angle is read from the PA_V3 or ORIENTAT descriptor (see below for details and also examples). The polarizer and or colour filter name in the header is matched with values found in the instpoltab table file and these are used to set the instrument specific polarization parameters required to compute the Stokes parameter and linear polarization data. The correction for polarizer transmission and pick-off mirror induced polarization follows closely the treatment for WFPC2 by Biretta and McMaster (WFPC2 ISR 97-11). The instrumental polarization is included for effects that are not collected by these physically based parameters. If the values of the polarizer efficiencies for calculating each Stokes parameter are equal for all input images (such as by specifying the same polarizer orientation and instrument position angle), then no calculation of polarization is possible. The task exits with an error in this case.
All errors are computed by Gaussian error propagation. To correct for the bias in linear polarization values which occurs when the Stokes parameter errors are large and the determination of linear polarization is no longer Gaussian error dominated, the method advocated by Wardle & Kronberg (ApJ, 194, 249, 1974) is employed, using the solution of the Rice distribution (see also Simmons & Stewart, A&A, 142, 10, 1985 for a discussion). Tests with synthetic data show that this correction does an adequate job to pol/sigma(pol) of about 2. Below that value it is best to use Monte Carlo methods which are not directly dealt with here. The method of computing the errors on the polarization position angle depends on the polarization signal-to-noise (i.e. pol/sigma(pol)). If pol/sigma(pol) is greater than 8 then the simple method (sigma(theta) = 28.65*sigma(pol)/pol) is employed (Serkowski, Adv. in Astron. & Astrophys. 1, 289, 1962); if pol/sigma(pol) is less than 8 then the distribution function of the position angle errors is integrated to derive the 1 sigma error (see Naghizadeh-Khouei & Clarke, A&A, 274, 968, 1993).
The parameters of the apertures for performing polarimetry are read from an input STSDAS table. Circular apertures are specified by an X and Y centre (currently only pixel coordinates are supported), the radius of the circle over which to sum counts for the object, the distance between the outer radius of the object circle and the inner radius of the sky annulus and the width of the sky annulus. A name for identification purposes can be given for each aperture.
The mean value of the sky/background per pixel is calculated and subtracted from the object signal. The mean sky can be determined by sigma clip iterations where values differing by greater than SIGSKY*rms on the mean are excluded at each iteration.
The following header keywords are required in order that the instrumental polarization parameters can be matched against the instrument table files:
for FOC - INSTRUME, FILTNAM1, FILTNAM2, ORIENTAT
for NICMOS - INSTRUME, FILTER, ORIENTAT
for WFPC2 - INSTRUME, FILTNAM1, FILTNAM2, DETECTOR, PA_V3
for SPECIAL - INSTRUME, FILTER, POLANG, ORIENTAT

EXAMPLES

1. To reduce a set of FOC aperture polarimetry data:

cl> hstpolpoints imalis="@focim.lis" errlis="@focer.lis" instpoltab="foc-pol-filt-001.tab" pointab="focap1.tab" nrej=3 sigsky=2.5 outtab="focapol1"

FOC polarization data usually consist of a set of three images taken at the three rotation angles of the polarizer of 0, 60 and 120 degrees at approximately the same ORIENTAT. See the HST Data Handbook, Section 8-7).

2. To reduce a set of NICMOS polarimetry images in a set of apertures:

cl> hstpolpoints imalis="@nicim.lis" errlis="@nicer.lis" instpoltab="nicmos-pol-filt-001.tab" pointab="nicap1.tab" nrej=7 sigsky=3.0 outtab="nicpolap"

NICMOS polarization data usually consist of a set of three images taken at the three rotation angles of the polarizer which are close to 0, 120 and 240 degrees (depending on the polarizer used short (S) or long wavelength (L)) at a similar ORIENTAT. See the HST Data Handbook Section 18-12 and Hines, D. C., 1998, NICMOS and the VLT Workshop proceedings, eds. Freduling, W. & Hook, R., p. 63.

3. To reduce the aperture polarization for a set of WFPC2 polarimetry images:

cl> hstpolpoints imalis="@wfpcim.lis" errlis="@wfpcer.lis" instpoltab="wfpc2-pol-filt-001.tab" pointab="wfpcap2" nrej=1 sigsky=2.7 outtab="wfpc_1.tab"

WFPC2 polarization data can consist of three or four images taken with three or four rotation angles of the polarizer quad filter at a given PA_V3, or three or more images taken on the same chip at differing values of PA_V3 and covering a range of rotation of at least 90 degrees. See the HST Data Handbook Section 28-16 and Biretta, J. & McMaster, M., WFPC2 Instrument Science Report 97-11. The header parameters FILTNAM1 and FILTNAM2 are translated to provide the polarizer position angle in conjunction with the chip number (for POLQ only).

4. To reduce a set of polarimetry images originating from a non-HST instrument and determine the polarization for a set of sources:

cl> hstpolpoints imalis="@specim.lis" errlis="@specer.lis" instpoltab="special-pol-001" pointab="specaper.tab" nrej=0 sigsky=0.0 outtab="specpol_2"

If the parameter INSTRUME is set to SPECIAL then non-HST imaging polarimetry data can be reduced. The filter name given by the header parameter FILTER must match the name in the instrument table file. The polarizer angle is indicated by the header parameter POLANG. The instrument rotation is indicated by the ORIENTAT parameter which may need to be translated into the instrumental system.

Format of the instrument specific table file

The STSDAS table file is a nine column file with the following columns: Name of colour/polarizing filter Position angle of polarizer filter Normalised transmission parallel to polarizer axis Normalised transmission perpendicular to polarizer axis Reflectance of mirror E-vector parallel to surface (s wave) Reflectance of mirror E-vector normal to surface (p wave) Retardance (deg.) of s wave relative to p wave Instrumental polarization (%) Position angle (deg.) of instrumental polarization (in instrument frame)

with the following column names and format: FILTER CH*16 POLANG R F6.2 TRANSPAR R E10.4 TRANSPER R E10.4 REFLECTRS R F6.4 REFLECTRP R F6.4 RETARDPHI R F8.4 INSTPOL R F6.2 INSTPA R F6.2

Thus table files for different instruments can be produced for use with this routine.

Format of the aperture parameters table file

The STSDAS table file defining the apertures for which the polarization is to be determined has the following columns: Identification name for aperture X centre of aperture (pixels) Y centre of aperture (pixels) Radius of aperture over which to sum object counts (pixels) Width of the gap between the object circle and the annulus for determining background counts (pixels) Width of the annulus for measuring the mean background (pixels)

with the following column names and format (the latter mandatory only for OBJECT_NAME): OBJECT_NAME CH*16 POS_X R F7.2 POS_Y R F7.2 RADIUS R F7.2 GAP R F7.2 ANNULUS R F7.2

Format of the output aperture polarimetry table

The output STSDAS table file listing the derived Stokes parameters, linear polarization and position angle and all propagated errors has the following columns: Identification name for aperture X centre of aperture (pixels) Y centre of aperture (pixels) Stokes I (ADU) Stokes I error (ADU) Normalised Stokes Q Error on normalised Stokes Q Normalised Stokes U Error on normalised Stokes U Linear polarization (%) Error on linear polarization (%) Polarization position angle (degrees) Error on polarization position angle (degrees).

The first three columns are simply copied from the input aperture definition table.

The output table has the following column names and format: OBJECT_NAME CH*16 POS_X R F10.3 POS_Y R F10.3 Stoke_I R E12.5 Stoke_I_Error R E12.5 Stoke_Q R E12.5 Stoke_Q_Error R E12.5 Stoke_U R E12.5 Stoke_U_Error R E12.5 Lin._Poln. R F8.4 Lin._Poln.Error R F8.4 Poln._PA R F8.4 Poln._PA_Error R F8.4

BUGS

Some care should be taken if ORIENTAT is much different between the input images and there is substantial instrumental polarization, since the position angle of instrumental polarization is (probably) fixed in the reference frame of the instrument. This situation is not correctly handled.