Last modified: December 2022

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

asphist

Context: Tools::Aspect

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,

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


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.

See Also

calibration
ardlib
psf
psf
tools::aspect
asp_offaxis_corr, dither_region
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::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