Synopsis
Determine the approximate dither period and amplitude used during an observation.
Syntax
get_dither_parameters infile [method] [dety_amplitude] [detz_amplitude] [dety_period] [detz_period] [tmpdir] [verbose] [clobber]
Description
`get_dither_parameters' uses the aspect solution file to determine the approximate dither parameters: period and amplitude, used during an observation. The actual values are not computed and the planned values are not stored in the data products; the planned values are only available from the Chaser Details page. Users doing timing analysis may need to know the dither parameters to understand if the timing signature they detect is instrumental or intrinsic to the source.
Most observations use the default dither parameters. Prior to October 2022, the defaults were
Default dither parameter prior to October 2022
Instrument | DET_Y Amp [deg] | DET_Z Amp [deg] | DET_Y Period [sec] | DET_Z Period [sec] |
---|---|---|---|---|
ACIS | 0.0022 | 0.0022 | 1000 | 707.1 |
HRC | 0.00556 | 0.00556 | 1087 | 768.6 |
As of October 2022, the default amplitude and dither for ACIS were doubled to allow for improved star tracking by the aspect camera.
Default dither parameter as of October 2022
Instrument | DET_Y Amp [deg] | DET_Z Amp [deg] | DET_Y Period [sec] | DET_Z Period [sec] |
---|---|---|---|---|
ACIS | 0.0044 | 0.0044 | 2000 | 1414 |
HRC | 0.00556 | 0.00556 | 1087 | 768.6 |
However observers can request custom dither parameters. This was done most notably for the various of Crab observations. In addition some calibration observations use non-standard dither patterns to improve detector coverage. There are also some anomalies where dither was mistaken not enabled during a small number of observations.
The estimated dither parameter values are stored in the tool's own parameter file. In addition, at verbose=1 and higher the estimated dither parameters are printed to the terminal.
Note on detector coordinates
Dither is defined in spacecraft, ie detector coordinates. DET_Z is in the direction of the SIM motion; that is the axis upon which the SIM moves to select the different instruments. DET_Y is moving side-to-side in the detector plane. DET_X is in the direction of the mirrors.
Examples
Example 1
% get_dither_parameters pcadf04425_000N001_asol1.fits.gz method=fold
This is an example of an ACIS observations that used the default, standard dither parameters. The results are printed to the screen:
get_dither_parameters infile = pcadf04425_000N001_asol1.fits.gz method = fold dety_amplitude = 0 detz_amplitude = 0 dety_period = 0 detz_period = 0 tmpdir = /tmp verbose = 1 mode = ql Results: Amplitude Period [arcsec] [sec] DETY 8.004 1000.000 DETZ 7.899 708.000
The tool also stores the outputs back into its own parameter file. These can be retrieved using any of the standard parameter file tools such as plist, pget, or pdump:
% plist get_dither_parameters Parameters for /home/user/cxcds_param4/get_dither_parameters.par infile = pcadf04425_000N001_asol1.fits.gz Input aspect solution file (method = fft) Method to estimate dither parameters (dety_amplitude = 8.00398436876533) Amplitude in DETY direction [arcsec] (detz_amplitude = 7.899064790088977) Amplitude in the DETZ direction [arcsec] (dety_period = 1000) Period in DETY direction [sec] (detz_period = 708) Period in DETZ direction [sec] (tmpdir = ${ASCDS_WORK_PATH} -> /tmp) Directory for temporary files (verbose = 1) Amount of tool chatter (mode = ql)
Example 2
% get_dither_parameters pcadf08908_000N001_asol1.fits.gz meth=fold
This is an example of an HRC observation that used the standard dither parameters. The terminal output looks like:
get_dither_parameters infile = pcadf08908_000N001_asol1.fits.gz method = fold dety_amplitude = 0 detz_amplitude = 0 dety_period = 0 detz_period = 0 tmpdir = /tmp verbose = 1 mode = ql Results: Amplitude Period [arcsec] [sec] DETY 18.957 1087.000 DETZ 19.594 768.000
Example 3
% get_dither_parameters pcadf05555_001N001_asol1.fits.gz meth=fold
This is an observation of the Crab nebula. The observer chose to reduce the size of the dither pattern; they also used a sub-array and a custom window to reduce the size of the field of view (to reduce readout time and lessen telemetry saturation). The output for this observation looks like
get_dither_parameters infile = pcadf05555_001N001_asol1.fits.gz method = fold dety_amplitude = 0 detz_amplitude = 0 dety_period = 0 detz_period = 0 tmpdir = /tmp verbose = 1 mode = ql Results: Amplitude Period [arcsec] [sec] DETY 3.935 1001.000 DETZ 3.754 708.000
In this case the dither period remained the same as the default values but the amplitudes where reduced to 5% of the default values.
Example 4
% get_dither_parameters pcadf03832_002N001_asol1.fits.gz me=fold
This observation was planned to use the standard dither parameters, however there was an error in planning/commanding that actually disabled dither. The output looks like:
get_dither_parameters infile = pcadf03832_002N001_asol1.fits.gz method = fold dety_amplitude = 0 detz_amplitude = 0 dety_period = 0 detz_period = 0 tmpdir = /tmp verbose = 1 mode = ql Results: Amplitude Period [arcsec] [sec] DETY 0.015 2054.000 DETZ 0.021 2769.000
The amplitude values are tiny (typical values are on the order of 10 arcsec) and the periods are much longer than what is shown as planned in Chaser.
Consulting the V&V report we read that in fact dither had been disabled and the values reported here are essentially noise.
Example 5
% get_dither_parameters pcadf18840_000N001_asol1.fits.gz met=fold
The calibration team will sometimes plan observations with non-standard dither patterns to maximize exposure of the calibration source over a large part of the detector to optimize the amount of calibration data they acquire. This is a grating observation using the so-called "Big Dither" pattern; typical dither parameters have equal amplitude in DET_Y and DET_Z directions, thus making a square Lissajous pattern; these observations have a much larger dither amplitude in one-direction resulting in a rectangular pattern.
get_dither_parameters infile = pcadf18840_000N001_asol1.fits.gz method = fold dety_amplitude = 0 detz_amplitude = 0 dety_period = 0 detz_period = 0 tmpdir = /tmp verbose = 1 mode = ql Results: Amplitude Period [arcsec] [sec] DETY 7.852 1000.000 DETZ 62.290 2653.000
Here the DET_Z axis is much larger than DETY.
Example 6
% get_dither_parameters pcadf04425_000N001_asol1.fits.gz method=fold % get_dither_parameters pcadf04425_000N001_asol1.fits.gz method=fit % get_dither_parameters pcadf04425_000N001_asol1.fits.gz method=ffft
Here we have examples of the three different estimation methods. The results are summarized below
Example of different estimation methods
method | DET_Y_Amp [arcsec] | DET_Z Amp [arcsec] | DET_Y Period [sec] | DET_Z Period [sec] | Run time [sec] |
---|---|---|---|---|---|
fold | 8.004 | 7.899 | 1000 | 708 | 25.26 |
fit | 8.136 | 8.009 | 1000.13 | 707.66 | 31.91 |
fft | 8.405 | 8.530 | 1004.35 | 704.80 | 1.83 |
The default method=fold option is the most robust with the middle amount of time to compute. method=fit is more accurate for this case but is slower and can have problems converging to reliable estimates. Finally, method=fft is by far the fastest method, but also the less precise.
Parameters
name | type | ftype | def | min | max | units | reqd |
---|---|---|---|---|---|---|---|
infile | file | input | yes | ||||
method | string | fold | no | ||||
dety_amplitude | real | arcsec | |||||
detz_amplitude | real | arcsec | |||||
dety_period | real | sec | |||||
detz_period | real | sec | |||||
tmpdir | file | output | ${ASCDS_WORK_PATH} | no | |||
verbose | integer | 1 | 0 | 5 | no | ||
clobber | boolean | no | no |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
Aspect solution file, pcadf*asol1.fits
This tool takes as input the aspect solution file for the observation. These are usually located in the primary or repro directories and have file names that look like pcadf{obs_id}_{obi_num}N{version}_asol1.fits or pcadf{obs_id}_repro_asol1.fits. For some very early observations that have not been through Repro-5, there may be one or more aspect solution files that have names that look like pcadf{tstart}N{version}_asol1.fits.
This tool does not accept stacks of aspect solution files. If there is more than one asol file, then they should be merged using dmmerge.
Parameter=method (string not required default=fold)
Choice of algorithm to estimate dither parameters: fold, fit, fft
method options:
- fold : period folding algorithm
- fit : least-squares fit
- fft : powerspectrum (fft) search for maximum power.
The details of each algorithm are discussed below.
Parameter=dety_amplitude (real default= units=arcsec)
The estimated amplitude in the DET_Y direction in units of arcseconds
Parameter=detz_amplitude (real default= units=arcsec)
The estimated amplitude in the DET_Z direction in units of arcseconds
Parameter=dety_period (real default= units=sec)
The estimated period in the DET_Y direction in units of seconds
Parameter=detz_period (real default= units=sec)
The estimated period in the DET_Z direction in units of seconds
Parameter=tmpdir (file not required filetype=output default=${ASCDS_WORK_PATH})
Temporary working directory
Directory used to store temporary file created by the script.
Parameter=verbose (integer not required default=1 min=0 max=5)
Controls the amount of information printed to the terminal
Parameter=clobber (boolean not required default=no)
Delete the output outfile if it already exists?
Description of Algorithms
The get_dither_parameters tool estimates the dither parameters by examining the RA and Dec values in the aspect solution file. The RA and Dec values are rotated by the spacecraft ROLL to convert them into detector coordinates: DET_Y and DET_Z. From there three algorithms are available to estimate the dither parameters.
method=fold
The default method=fold algorithm works by period-folding the TIME values over the range from 200 to 3500 second periods. For each period, the DET_Y and DET_Z values are split up into 10 phase bins and the mean DET_Y and DET_Z values is computed. The period with the maximum standard deviation of the phase bins is the estimated period in each direction. The amplitude is one-half of the peak-to-peak min/max in the phase bins at that period. The period search is skipped if the aspect solution file is less than 200 seconds. If the aspect solution is less than 3500 seconds, then the period search is limited to the duration of the aspect solution file. Testing has shown this to be the most robust algorithm with moderate run-time.
method=fit
This method uses sherpa to model the DET_Y and separately the DET_Z values as a constant plus a cosine function. The data are fit using the least-squares statistic; error estimates are not used. The data are fit using the neldermead optimization algorithm. In the event of a poor fit (as derived from abnormally small amplitudes) the fit is repeated with different intial guesses and then finally with the most robust but slowest moncar optimization method. Generally this is the most precise algorithm but it is significantly slower than the other methods and can sometimes converge on poor estimates.
method=fft
This method uses the apowerspectrum tool to compute the power spectrum of the DET_Y and DET_Z values. The period is taken to be the period bin with the maximum power. The amplitude is estimated by sorting the values and computing the range of the values in the 1% and 99% quantiles; this is to avoid the "tail" that can be seen at the start or end of some aspect solution files. The powerspectrum is the fastest algorithm but is less precise and is not robust for aspect solution files with short duration.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.
See Also
- contrib
- lc_clean, lc_sigma_clip, lightcurves
- tools::acis
- multi_chip_gti
- tools::aspect
- monitor_photom
- tools::timing
- axbary, deflare, glvary, gti_align, pfold