Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dither_region.html
AHELP for CIAO 4.16

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.

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:

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.


Bugs

There are no known bugs for this tool.

See Also

calibration
ardlib
concept
subspace
dm
dmmasks, dmregions
psf
psf
tools::aspect
asp_offaxis_corr, asphist
tools::background
acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg
tools::composite
combine_grating_spectra, combine_spectra, specextract
tools::coordinates
reproject_aspect, sky2tdet
tools::core
dmextract
tools::detect
get_src_region
tools::gratings
tg_create_mask
tools::image
dmimgdist, dmimgfilt
tools::region
bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
tools::response
acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg
tools::statistics
aprates