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: 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