NAME

nitargdet - Calculate target position in NICER instrument coordinates

USAGE

nitargdet attitude outfile ra dec

DESCRIPTION

The nitargdet task calculates the position of a celestial target in NICER instrumental coordinates. Unlike the standard NICER filter file column ANG_DIST, which is the angular separation between the NICER boresight and the target, nitargdet has more capabilities.

nitargdet computes the location of the target in instrumental coordinates, not just the angular separation. This is required for NICER response (vignetting) calculations. The next step in the response calculation chain is the task nivignette.

nitargdet can compute the location for the observatory boresight, or a single NICER module, or for every module individually. Again, this is required for calculating per-module vignetting values. This option is controlled by the 'detlist' parameter. detlist may take one of the following values.

nitargdet can calculate the target position either in NICER module coordinates, or NICER module "tip" coordinates. In the "tip" coordinate system, any optical tilt is in the X-Z plane. Again, this is used for vignetting calculation. This option is controlled by the 'aligncol' parameter.

By default, aligncol=Q_MISALIGN computes locations in instrument coordinates. When aligncol=Q_TIP, the task computes locations in "tip" coordinates. Note that aligncol=Q_TIP is not allowed when detlist=BORESIGHT since there is no "tip" coordinate system for the average of many misaligned optics.

The input to nitargdet is a source of attitude data. This can be either the NICER filter file (niNNNNNNNNNN.mkf file), or the NICER attitude file (niNNNNNNNNNN.att file). The attitude file as the advantage of being sampled at 10 Hz, while the filter file is sampled at 1 Hz.

By default nitargdet computes locations for each input time sample, and writes an output row for each as well. In cases where an instrumental coordinate does not make sense, a NULL value is written. If selective processing is desired, the filtexpr parameter can be used. An rowfilter and/or calculator expression can be used to selected desired rows.

The user must also select a target position in celestial sky coordinates using the 'ra' and 'dec' parameters. This must be the Right Ascension and Declination in J2000 degrees. Also, optionally if the attitude file contains target RA/Dec columns, the user can specify these column names as 'racol' and 'deccol', in which case the 'ra' and 'dec' are ignored.

The output file is a FITS binary table with the following columns.

Note that RA_OBJ and DEC_OBJ are only written if 'racol' and 'deccol' are used. Entries for THETA_X and THETA_Y are have either a single value per row (when detlist=BORESIGHT or detlist=number) or 56 values per row (when detlist=ALL).

PARAMETERS

attitude [filename]
Input attitude file. This should be either a NICER filter file (niNNNNNNNNNN.mkf file) or attitude file (niNNNNNNNNNN.att file).
outfile [filename]
Output FITS table file name.
ra [real]
Right ascension of target in J2000 degrees. Ignored if racol/deccol are set.
dec [real]
Declination of target in J2000 degrees. Ignored if racol/deccol are set.
(coord_type="sky") [string]
Coordinate system for RA/Dec. Only "sky" is supported.
(racol="NONE") [string]
Name of R.A. column to use from input file. A value of "NONE" (the default) indicates to use the 'ra' value. Note that racol and deccol must both be set together.
(deccol="NONE") [string]
Name of Dec. column to use from input file. A value of "NONE" (the default) indicates to use the 'dec' value. Note that racol and deccol must both be set together.
(filtexpr="NONE") [string]
Row filtering expression to be applied to the input file to select a subset of rows. A value of "NONE" means to use all input file rows.
(alignfile="CALDB") [string]
Name of alignment file to use, or "CALDB" to automatically query CALDB. By default, the task will look for the teldef file when detlist=BORESIGHT and the XRC alignment file when detlist=ALL or detlist=. A value of "CALDB:teldef" forces a search for the teldef file, and "CALDB:misalign" forces a search for the XRC alignment file.
(detlist="ALL") [string]
Specifies which detectors to operate uppon. The allowed values are, "BORESIGHT" (the commanded NICER observatory boresight), "ALL" (each NICER detector), and a single numerical detector ID between 00 and 67.
(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]
Amount of verbosity of the task. For chatter=0, no output is printed. For chatter=5, debugging output is printed.

(history = YES) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

NOTE: All of the examples below use CALDB for the alignment information. The correct file is selected using standard CALDB access processes.

1. Compute target coordinates from the observation 1234567890's filter file (.mkf), using the given RA/Dec for the observatory pointing boresight. 

nitargdet 1234567890/auxil/ni1234567890.mkf targdet.fits \
  ra=216.59217 dec=5.85921 detlist=BORESIGHT

2. Compute target coordinates from the observation 1234567890's attitude file (.att), using the given RA/Dec for the observatory pointing boresight. 

nitargdet 1234567890/auxil/ni1234567890.att targdet.fits \
  ra=216.59217 dec=5.85921 detlist=BORESIGHT

3. Compute target coordinates from the observation 1234567890's filter file (.mkf), using the given RA/Dec for each and every module's alignment. 

nitargdet 1234567890/auxil/ni1234567890.att targdet.fits \
  ra=216.59217 dec=5.85921 detlist=ALL

4. Compute target "tip" coordinates from the observation 1234567890's filter file (.mkf), using the given RA/Dec for each and every module's alignment. 

nitargdet 1234567890/auxil/ni1234567890.att targdet.fits \
  ra=216.59217 dec=5.85921 detlist=ALL aligncol=Q_TIP

SEE ALSO

niprefilter2
nivignette

LAST MODIFIED

Feb 2021