get_dither_parameters

Synopsis

Determine the approximate dither period and amplitude used during an observation.

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

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

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

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

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