/ ciao4.16 / ahelp / asphist.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.15 · Changes in CIAO 4.16 · Bugs · See Also

AHELP for CIAO 4.16

asphist

Synopsis

Bin the aspect solution into a 3D histogram of duration vs pointing offset and roll offset.

Syntax

asphist  infile outfile evtfile dtffile [geompar] [res_xy] [res_roll]
[max_bin] [clobber] [verbose]

Description

The aspect solution is given every 0.256 seconds during an observation. The aspect solution can be put into a very compressed form by making a histogram of the pointing vs. x-offset, y-offset, and roll-offset. The value in each bin is the time the pointing was within that offset bin during the observation, as modified by the good-time interval (GTI) and dead-time-correction factor (DTF). (The information which is lost is the absolute time at which the pointing was at each offset.)

The histogram is primarily used to shorten the time required to compute the response averaged over the observation (e.g. by the response tools mkarf, mkgarf, or mkexpmap). Another use for the histogram is to provide all the observational configuration (detector, date) via the file's header.

The input file is the aspect solution, which contains the optical axis' right ascension, declination, and roll vs. time. These are combined and converted to pixel offsets, and the duration integrated for each offset. The actual position of the optical axis on the detector is lost in this process, but the result is not used for explicit event coordinate transformations where this information would be crucial. Instead, we have information which allows us to map the detector outline to the sky.

Examples

Example 1

asphist pcad_asol.fits asphist_7.fits evtfile="acis_evt2.fits[ccd_id=7]"

This shows the preferred way of specifying the good-time filter by specifying the chip. (Due to telemetry saturation, each chip may have a different exposure.)

Example 2

asphist pcad_asol.fits asphist_7.fits
evtfile="acis_evt2.fits[time=123456789:123456800,ccd_id=7]"

Similar to above; however, in this example an additional time filter is going to be used in later analysis therefore it needs to be included here to ensure that the proper duration is computed.

Example 3

asphist infile=@hrc_stk.lis outfile=mytest_hist.fits
evtfile=hrc_evt1.lis dtffile=@stack_dtf1.lis

Use a list of aspect solution files, an event file, and HRC dead-time-factor files.

Example 4

asphist infile="asol.fits" outfile=asphist.fits
evtfile="evt1.fits[ccd_id=0]"

Use a single aspect solution file with the specified GTI table.

Parameters

name	type	ftype	def	min	max	units	reqd	stacks
infile	file	input					yes	yes
outfile	file	output					yes
evtfile	file	input					yes	yes
dtffile	file	input					yes	yes
geompar	file		geom
res_xy	real		0.5			arcsec
res_roll	real		600			arcsec
max_bin	real		10000
clobber	boolean		no
verbose	integer		0	0	5

Detailed Parameter Descriptions

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

Input aspect solution file(s). A single file or a stack. Currently, the aspect solution input files must be time-sorted.

For one or multiple input file(s), there should be only one single ASPHIST table in the outfile. ( see the parameter 'outfile' )

Parameter=outfile (file required filetype=output)

Name of the file to write, holding a table of the aspect histogram (extension 'ASPHIST'), and a table of the good time intervals (extension 'GTI').

The GTI table contains the columns of START and STOP, and the ASPHIST table contains the columns,

CAH_REC - bin, Int4, histogram bin
X_OFFSET - pix, Real8, Offset in sky x pixels
Y_OFFSET - pix, Real8, Offset in sky y pixels
ROLL_OFFSET - deg, Real8, Offsets in roll
DURATION - s, Real8, Bin Duration (corrected for LT and GTI)

The total of all durations is the EXPOSURE, which is corrected for the live-time and good-time. Since each detector element can have a unique GTI or DTF, each chip will have unique aspect histogram and EXPOSURE keyword.

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

Input event file name(s). If a stack, only uses the first element.

This file provides information of nominal pointing positions and the SIM factors. It should contain the keywords : NOM , SIM , DETNAM , DTCOR (for ACIS).

The evtfile should have a filter appended to it, the preferred syntax being "[ccd_id=x]" for the ACIS case. None is needed for HRC (since there is only one valid GTI for all HRC plates).

This filter is used for two reasons. First, the aspect solution needs to be time filtered the same as the event file. The simplest way to do so is use the event file's GTI tables directly. Second, without the ccd_id=x, we pick the first subspace (which for ACIS is by default the aim chip). This may or may not be what you're looking for -- the "ccd_id=x" selects the correct GTI for your analysis..

If you knew the GTI ranges, you could just as easily do "evtfile=evt.fits[time=a:b,c:d,...]" and not filter with the event/GTI filters at all.

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

Input DTF file name(s). A single file or a stack.

The dead time correction factor file (and extension). This is an efficiency factor which weights the exposure durations as they are summed into each offsets bin.

For HRC, the files for the dead time correction factors are the "hrcroot_dtf1.fits" files. For ACIS, the livetime correction is from the keyvalue of DTCOR in the principle extension (EVENTS).

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

Parameter=res_xy (real default=0.5 units=arcsec)

Resolution desired, in arcseconds, for both the X and Y offsets. The default is 0.5 arcseconds, which is about 1 ACIS pixel.

Parameter=res_roll (real default=600 units=arcsec)

The resolution in roll (or size of a roll bin) in arcseconds. The default is 600 arcseconds. This is not as big as it seems. 600 arcseconds roll about the center of HRC-I causes a linear translation at the edge of the array of about 4 arcsec, which is smaller than the local PSF, and smaller than the resolution of the QE calibration.

Parameter=max_bin (real default=10000)

Maximal number of bins

Parameter=clobber (boolean default=no)

Clobber output if it exists?[y/n]

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

display level(0-5)

Changes in CIAO 4.15

The tool will now work with the output of sso_freeze: it now checks that the file contains the required columns rather than checking the block name matches ASPSOL or ASPOFF.

Changes in CIAO 4.16

Corrected the units from "degrees" to "deg" as per the FITS standard.

Bugs

Caveats

# asphist (CIAO): The difference of 2 asp_file counters should be 0 or 1.: This error occurs when one of the aspect solution files (pcad_asol1.fits) falls off of the good time interval (GTI) of the data. Removing that aspect solution file from the asphist run will solve the problem.