NAME

polarimetry -- Compute polarization indexes from HSP measurements.

USAGE

polarimetry infile inmask outroot efficiency paoffset

DESCRIPTION

The amount and angle of linear polarization are computed from measurements taken through four Polaroid filters. Normalized Stokes parameters are also calculated.

The HSP aperture assembly contains four near ultraviolet filters. Each filter has four apertures with polarizers oriented at 0, 45, 90, and 135 degrees. Linear polarization in any filter is measured by observing through each of the four apertures. The measurements through each aperture are assumed to be corrected for instrumental polarization (i.e., relative sensitivity) before using this task.

The normalized Stokes parameters I, q and u are computed from the four measurements and are transformed from the instrumental coordinate system to the equatorial coordinate system. Then the degree of linear polarization and its position angle are calculated from the normalized Stokes parameters. During data reduction, measurements are corrected for polarization efficiency and position angle offset which are stored in the calibration data base and are maintained by STScI. The user may substitute different correction factors during the reduction procedure by giving these values in the user parameters.

The input data for this procedure are four time series files, one for each of the apertures for the chosen wavelength filter. All four time series files must contain the same number of measurements.

Each time series file may have an associated mask file. If any measurement in a given pixel is flagged as a bad pixel in the data mask file, then no calculations of polarization indexes are performed for that pixel. Pixels in the output time series of polarization indexes are filled with the value specified by datafill.

PARAMETERS

infile = "" [string]

Name of the input data file (file name templates are allowed in this task).

The number of input files must be a multiple of four and the files must be grouped in sets of four files in the file name list. The files in each set must be the same size and share the same filter. Within a set of files, the four files do not have to be in a certain order; each file's aperture can be determined from the file headers.

inmask = "" [string]

Input mask file name.

This parameter is optional, but if any mask files are used, the number of mask files must be the same as the number of input files.

outroot = "" [string]

Root name to be used for output files.

Because every four input files will produce one set of output files, the number of output root names must be one fourth the number of input files. There are six output files for each input file set: the intensity, Stokes parameters q and u (both in percent), polarization (in percent), position angle (in degree, at equatorial system), and the output data mask file. The output files have the extensions i, q, u, p, a, and m attached to the output root name. For example, if the output root name is abc, the output files will be abci, abcq, abcu, etc. All output file headers are copies of the 0 degree aperture input file header. In addition, they have the following new header keywords:

"PEFF0"	    polarization efficiency of 0 deg. aperture used in 
	    this task
"PEFF45"    polarization efficiency of 45 deg. aperture used in 
	    this task
"PEFF90"    polarization efficiency of 90 deg. aperture used in 
	    this task
"PEFF135"   polarization efficiency of 135 deg. aperture used in 
	    this task
"PA0"	    the position angle offset used in this task

efficiency = "" [string]

Name of the STSDAS table containing polarization efficiencies. This table has the following columns:

"APER_NAME"	aperture name
"PEFF"		polarization efficiency
"PEFF_ERR"	error of polarization efficiency

If this parameter is null, the values supplied in parameters poleff0, poleff45, poleff90, and poleff135 must be specified.

paoffset = "" [string]

Name of the STSDAS table containing position angle offsets. This table has the following columns:

"FILTER_NAME"	filter name
"DTHETA"	position angle offset
"DTHETA_ERR"	error of the position angle offset

If this parameter is null, the value supplied in parameter pa0 is to be used.

(poleff= 1.) [real]

Polarization efficiency to be used at 0 degree aperture when a table of polarization efficiency is not specified in the parameter efficiency (see above).

(poleff= 1.) [real]

Polarization efficiency to be used at 45 degree aperture when a table of polarization efficiency is not specified in the parameter efficiency (see above).

(poleff= 1.) [real]

Polarization efficiency to be used at 90 degree aperture when a table of polarization efficiency is not specified in the parameter efficiency (see above).

(poleff= 1.) [real]

Polarization efficiency to be used at 135 degree aperture when a table of polarization efficiency is not specified in the parameter efficiency (see above).

(pa= 0.) [real]

Position angle offset to be used when a table of position angle offset is not specified in the parameter paoffset (see above).

(datafill = 1.) [real]

Fill value for bad data in output data files.

EXAMPLES

1. Reduce the HSP polarimetry observation from the data set of abc0.d0h, abc45.d0h, abc90.d0h, and abc135.d0h. Use the polarization efficiency table pol_eff.tab and the position angle offset table pa_offset.tab.

ti> polarimetry @in.lis "" output pol_eff pa_offset

The text file in.lis contains the following lines:
abc0.d0h
abc45.d0h
abc90.d0h
abc135.d0h

BUGS

REFERENCES

SEE ALSO