Compute fraction of region area that covers chips
dither_region infile region outfile [maskfile] [psffile] [gtifile]
[dtffile] [tolerance] [resolution] [maxpix] [convex] [geomfile]
[ardlibpar] [detsubsysmod] [verbose] [clobber]
`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 will take in either the aspect solution or the
aspect histogram as inputs.
-
If the aspect solution (stacks accepted) is supplied,
the output file will have 1 row foreach row in the
input with the fractional area computed. 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 (area in units of sky pixels).
If the psffile is provided the PSF fraction will also be computed.
It is assumed that the PSF file is correctly normalized before
being fed into the tool. The PSF fraction for each chip will also
be computed and stored in an array column.
Users can control the speed of execution by adjusting one of two
parameters. 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 badpixels is retrieve through ARDLIB;
the parameters should be set for the observation specific
badpixel file before running.
The STATUS column in the output indicates why the fraction is
less than 1. '00000100' means in the masked out region,
'00000010' means it covers a badpixel, and '00000001' means it
dithers off the chip. Various combinations of above are possible.
(1) dither_region infile=pcad0000_asol1.fits
region="circle(4096,4096,2)" outfile=fracarea_vs_time.fits
Aspect solution. For every point in the aspect solution,
map the sky region (circle) to chip coordinates and determine
what fractional part falls off the chip or onto badpixels.
On can then use this information to identify which
frequencies are attributed to (part of) the source region
dithering across multiple chips.
(1) dither_region infile=asphist_7.fits region="region(ds9.reg)"
outfile=fracarea_vs_histbin.fits psffile=mypsf.fits
Aspect solution. The syntax is currently a bit cumbersome;
but will be worked. For each aspect histogram bin, the sky
region (taken from external file 'ds9.reg') will be mapped
to chip coordinates and the fraction of good area will be
reported. The output contains the histogram bin number and
the fracitonal area.
Once can use 'dmpaste' (or dmjoin) to put the FRACAREA
column onto the aspect histogram and then use 'dmtcalc' to
correct the 'DURATION' based on the area lost.
The fraction of the PSF that is on a good part of the detector
(and for each chip) will also be computed.
Parameter=infile (file required filetype=input stacks=yes)
Aspect solution or histogram file
Either can be input. The aspect solution will give
information about the time variations (and possibly false periods)
that are introduced by the dither pattern. The aspect histogram (see
example for correct syntax) 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 header. Note that
the DETECTOR and INSTRUME will probably be set incorrectly.
Region specification
The sky region specification for the are to dither across the chip.
Region should be in physical coordinates.
Mask file
Name of detector mask file. Windows with SAMP_CYC=0 are probably being
treated incorrectly right now.
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 mostly useful when doing point source analysis. Extended
source analysis will benifit mostly from the fractional area, not
the PSF weighted value.
The PSF image should be normalized so that the sum(pixels)
is <= 1.0. (Although the clever user will surely find a
use for an unormalize PSF.)
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 (only when
the aspect solution is supplied).
For ACIS, the GTI should be part of a standard DSS 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 the one that will be used.
Dead time factors file
DTF values averaged over the time interval the region is dither.
Aspect solution tolerance
The tolerance of aspect solution records to compute.
Computing the fration 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 loosing 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.
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 evaluted: it will run slower but
will give a better result. The bigger the number, the coarser the
pixel grid but will speed up execution.
Controls the maximum number of pixels to evaluate
Sometimes adjusting the resolution can still produce
long runs. This 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 many, the
resolution will essentially be incremented +1 (so 4
times area); if that's too many it will be incremented
again (so 9 times area) until the number of pixels falls
below this limit. A value of "INDEF" removes any upper
limit cap.
If set to yes, then only those points that makeup the
convex-hull around the histogram are used and output.
Pixlib parameter file
Points to the pixlib parameter file where various calibrations
about the instruments are stored.
Ardlib parameter file
Points to the ARDLIB parameter file. Specifically the
badpixel information is needed from ARDLIB and should be set
to the observation specific files prior to running the tool.
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 badpixels
be overridden (see "ahelp ardlib" for more information).
Tool verbosity or chatter level.
- calibration
-
ardlib
- concept
-
subspace
- dm
-
dmregions
- tools
-
acis_bkgrnd_lookup,
acis_fef_lookup,
acis_set_ardlib,
acisspec,
add_grating_orders,
add_grating_spectra,
asphist,
dmarfadd,
dmcontour,
dmfilth,
dmimg2jpg,
dmmakereg,
dmregrid,
fullgarf,
get_src_region,
mkacisrmf,
mkarf,
mkexpmap,
mkgarf,
mkgrmf,
mkinstmap,
mkpsf,
mkrmf,
mkwarf,
psextract,
psf_project_ray,
rmfimg,
specextract,
tg_create_mask
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}