/ ciao4.15 / ahelp / dither_region.html

Jump to: Description · Examples · Parameters · ACIS Continious Clocking Mode · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

dither_region

Context: Tools::Aspect

Synopsis

Compute fraction of region area that covers chips

Syntax

dither_region  infile region outfile wcsfile [maskfile] [psffile]
[gtifile] [dtffile] [imapfile] [tolerance] [resolution] [maxpix]
[convex] [geompar] [ardlibpar] [detsubsysmod] [verbose] [clobber]

Description

`dither_region' takes a region on the sky and computes its location on the detector. When part of the region falls onto a bad-pixel, goes off the detector, or goes outside the bounds of the mask (optional) the area is decremented.

dither_region takes either the aspect solution or the aspect histogram as input.

If the aspect solution is supplied, then the fractional area is computed for each row in the input file(s). This is useful for timing analysis since certain frequencies can be attributed to the source dithering across bad pixels or into chip gaps. One can change the tolerance parameter to speed up the calculations at the expense of skipping rows in the aspect solution file. There will also be a DELTA_T column with the time length between points when the fractions are computed. The fraction is computed at the start of the time 'bin'.
If the aspect histogram is supplied, then the fractional area is computed for each point in the histogram. There is no timing information; only information about where in the dither pattern the region dithered off the chip.

The outfile will contain either a TIME or CAH_REC column depending on the type of aspect file provided: solution or histogram respectively. It will contain a column with the total fractional area, FRACAREA. It will also contain an array column with data for each chip (3 HRC plates, 10 ACIS chips) with the fraction on each chip; this is useful if the region dithers across chips since the response of the chips can be very different. There is TOTLAREA keyword with the total area of the region in units of sky pixels.

If the psffile is provided, the PSF fraction for each chip will be computed and stored in an array column. It is assumed that the PSF file is correctly normalized before being input to the tool.

Users can control the speed of execution by adjusting one of two parameters: resolution and convex. First, they can pick the resolution of the region (in sky pixels). A small resolution provides a better estimate of the fraction but will slow down the execution time considerably. If the aspect solution is used, the tolerance parameter controls how much the aspect solution has to change before the next fractional area is computed. Another option when an aspect histogram is supplied is to use the points that make up a convex hull around the aspect histogram rather than all the points. By checking the outer boundary you can tell if any part of the region goes on/off a chip.

The information about bad pixels is retrieved through ARDLIB. The parameters should be set for the observation-specific bad pixel file before running this tool; see the Use Observation-specific Bad Pixel Files thread for instructions.

The STATUS column in the output indicates why the fraction is less than 1:

'00000100' - in the masked-out region
'00000010' - covers a bad pixel
'00000001' - dithers off the chip

The options may be combined, e.g. '00000011' covers a bad pixel and dithers off the chip.

Examples

Example 1

dither_region infile=pcad_asol1.fits region="circle(4096,4096,2)"
outfile=fracarea_vs_time.fits

For every point in the aspect solution, map the circular sky region to chip coordinates and determine what fractional part falls off the chip or onto bad pixels.

This information can be used to identify which frequencies are attributed to (part of) the source region dithering across multiple chips.

Example 2

dither_region infile=asphist_7.fits region="region(ds9.reg)"
outfile=fracarea_vs_histbin.fits psffile=mypsf.fits

For each aspect histogram bin, the sky region in the file 'ds9.reg' is mapped to chip coordinates and the fraction of good area is reported. The output contains the histogram bin number and the fractional area. The fraction of the PSF that is on a good part of the detector (and for each chip) will also be computed.

The dmpaste or dmjoin tool can be used to append the FRACAREA column onto the aspect histogram. dmtcalc may then be used to correct the DURATION column of the aspect histogram based on the area lost.

Example 3

dither_region infile=pcad_asol.fits
region=circle(12:34:56.0,-08:09:10,5") wcsfile=evtfile.fits
outfile=dr_out.fits

If the input region is in celestial coordinates, then a wcsfile must be supplied that has the coordinate information needed to convert it back to physical coordinates. This can be either an event file or a sky image.

Parameters

name	type	ftype	def	min	max	units	reqd	stacks
infile	file	input					yes	yes
region	string						yes
outfile	file	output					yes
wcsfile	file	input					yes
maskfile	file	input
psffile	file	input
gtifile	file	input
dtffile	file	input
imapfile	file	input						yes
tolerance	real		INDEF			arcsec
resolution	real		1	0
maxpix	integer		1000	1
convex	boolean		no
geompar	file		geom
ardlibpar	file		ardlib
detsubsysmod	string
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

Aspect solution file(s) or aspect histogram file

The aspect solution will give information about the time variations (and possibly false periods) that are introduced by the dither pattern. The aspect histogram gives information about what part of the aspect solution the chips dithers over.

The instrument is determined based on the SIM_Z location; SIM_Z less than 0 implies ACIS, greater than 0 implies HRC.

The header is copied from the first file.

Parameter=region (string required)

Region specification

The sky region specification for the area to dither across the chip. Region should be in physical coordinates.

Parameter=outfile (file required filetype=output)

Output file name

The content of the output file depends on whether an aspect solution or an aspect histogram is used as input. The DESCRIPTION section of this file describes each case.

Parameter=wcsfile (file required filetype=input)

File containing WCS information

The WCS file is used to obtain the correct tangent plane projection. It is required for any observations which have been reprojected to a new tangent point and is required anytime regions are provided in celestial coordinates. The wcsfile should be either an image or event file associated with the region.

Parameter=maskfile (file filetype=input)

Mask file

The mask file (msk1.fits) for the observation. The mask is necessary for the tool to know which CCDs (or portions of CCDs) were turned on during the observation. It is especially important when a window or subarray was used.

A value of "NONE" indicates that no mask file will be applied.

More information on the mask file is available in the CIAO Dictionary.

Parameter=psffile (file filetype=input)

An image of the PSF.

An image of the PSF for the source location. Pixels within the sky region ('region' parameter) will be integrated over all the good pixels on the detectors. The fraction (integrated fraction) is output.

This is most useful when doing point source analysis. Extended source analysis will benefit more from the fractional area, not the PSF-weighted value.

The PSF image should be normalized so that the sum(pixels) is <= 1.0.

Parameter=gtifile (file filetype=input)

Good time interval table

A file with GTIs attached. The time period when the aspect doesn't change more than 'tolerance' arcsec is intersected with the GTI for each chip. The fraction of time is reported in the output file if an aspect solution is used as input.

For ACIS, the GTI should be part of a standard data subspace that also contains the CCD_ID. For HRC, the same GTI will be used for all plates. If there are multiple GTIs for HRC and/or multiple GTIs for the same chip in ACIS, the last GTI is used.

Parameter=dtffile (file filetype=input)

Dead time factor file

The dead time correction factor (DTF) file. This is an efficiency factor which weights the exposure durations.

Parameter=imapfile (file filetype=input stacks=yes)

Stack of Instrument files

If a stack of instrument maps is supplied, the average good value (i.e. not a bad pixel) in the region vs. time/asphist-bin is output to the 'AVG_EA' column. (The column is not created unless the instrument maps are supplied.)

Parameter=tolerance (real default=INDEF units=arcsec)

Aspect solution tolerance

The tolerance of aspect solution records to compute. Computing the fraction at every aspect solution record is very time consuming. By picking time records where the aspect solution hasn't changed by 'tolerance' arcsecs, we can greatly increase the speed without losing much information (since the dither is relatively slow).

The default value is INDEF which will get the sky pixel size for the given instrument and will divide by 2.

Parameter=resolution (real default=1 min=0)

Resolution of sky region to evaluate fractions

dither_region computes a pixel list for the given sky region and evaluates the fractions on that list. The smaller the resolution value, the more pixels will be evaluated: the tool will run slower but will give a better result. Using a larger number creates a coarser pixel grid but speeds up execution.

Parameter=maxpix (integer default=1000 min=1)

Controls the maximum number of pixels to evaluate

Sometimes adjusting the "resolution" value isn't enough to reduce the tool run-time. This parameter sets an absolute upper limit on the number of pixels that will be used to compute the fractions. If the number of pixels is too large, the resolution will essentially be incremented +1 (4 times area). If that is still too many pixels to process, it will be incremented again (9 times area) until the number of pixels falls below this limit. A value of "INDEF" removes any upper limit cap.

Parameter=convex (boolean default=no)

If set to yes, only those points that make up the convex hull around the histogram are analyzed and included in the output.

Parameter=geompar (file default=geom)

Pixlib parameter file

The pixlib geometry parameter file where various calibrations about the instruments are stored.

Parameter=ardlibpar (file default=ardlib)

Ardlib parameter file

The ARDLIB parameter file. The bad pixel information is needed from ARDLIB and should be set to the observation-specific bad pixel file before running this tool; see the Use Observation-specific Bad Pixel Files thread for instructions.

Parameter=detsubsysmod (string)

Ardlib detector sub-system modifier

Unlike some other ARDLIB-enabled tools; dither_region runs on multiple chips and as such does not have a detsubsys parameter. This parameter allows one to modify the internal detsubsys value to allow the response product to be modified. Things such as skipping bad pixels be overridden (see "ahelp ardlib" for more information).

Parameter=verbose (integer default=0 min=0 max=5)

Tool verbosity or chatter level.

Parameter=clobber (boolean default=no)

Overwrite existing files?

ACIS Continious Clocking Mode

Since ACIS Continious Clocking mode data is lacking information in the CHIPY direction, the regions one typically uses does not represent the true 2-D extracted region. That means that unless especial care is taken, dither_region is not useful for CC mode data. Users should be especially suspicious of any frequencies detected that are harmonics of the dither frequencies.

Changes in CIAO 4.15

Corrects typo in verbose output

Bugs

There are no known bugs for this tool.