NAME

nivignette - Calculate NICER vignette profile for target position

USAGE

nivignette infile outfile

DESCRIPTION

The nivignette task calculates the NICER vignetting profile for a given observation. The vignetting profile is the transmission function for off-axis angles. In the case of NICER, each of the optics has a unique tip angle (< 90 arcsec) and tip azimuth. The information about NICER performance is calibration data which is typically accessed via NICER's Calibration Database (CALDB).

For the default run mode, the output is the vignetting fraction, which is a number between 1.0 (purely on-axis) and 0.0 (far off-axis). This information is used to calculate an accurate response function (ARF), even for off-axis sources.

nivignette calculates the off-axis vignetting profile for a given source X-ray surface brightness profile. Often, a scientist will consider a point-like source, which is the default. However there are other surface brightness profiles -- flat sky background, gaussian, and user-supplied radial profile -- as described more below.

The input to nivignette is the "target position" file, produced by the task nitargdet. Therefore, it is required to run nitargdet before running nivignette. In addition, one should run nitargdet with aligncol=Q_TIP so that optic tip information can be taken into account. In its usual manner of usage, nitargdet will output an array of target positions (THETA_X,THETA_Y) for each time sample in the attitude (or filter) file. nivignette calculates the vignetting response for each time sample, each telescope, and each X-ray concentrator shell in that telescope.

nivignette also uses several calibration files, which are typically stored in NICER's CALDB.

The output of nivignette is a FITS binary table containing the estimated vignette value for each input sample. The table contains the following columns.

Surface Brightness Profiles

nivignette can handle several surface brightness profiles. The default profile is profile=point, a point-like source centered at the target position. This will be sufficient for many analysis workflows, but the user may need alternate profiles to handle more complicated sky brightness distributions.

The allowed X-ray surface brightness profiles are:

Aside from the flat sky background mode, nivignette calculates the NICER vignetting response to the entire source flux. This it the expected behavior for a source with a certain total flux. For point sources, this is trivial. For diffuse sources, nivignette calculates the overlap of the NICER field of view and the surface brightness profile.

For example, if the NICER field of view subtends 50% of the sources surface brightness profile, then nivignette's output will be near 50%, and the ultimate estimated effective area will be about 50% compared to an on-axis point source. Thus, when modeling the spectrum in a analysis tool such as XSPEC, the fitted flux will represent the total flux of the source, not the fraction of the flux in the NICER field of view.

One exeception to this is the "flat" sky surface brightness profile, whose fitted flux values will be in per-solid-angle units, as described below.

For the diffuse brightness profiles, gaussian and radial, the user should be aware of certain limitations of the calibration and processing. First, the calibration vignetting profiles are sampled with 10 arcsec grid spacing. Therefore, analysis should avoid surface brightness models which have features finer than 10 arcsec. More information on this is provided in the detail sections below.

Also, the user should consider that calculating the response to broader profiles takes significant amounts of computing time. If your profile is smooth on the spatial scales of the NICER vignetting profile (~200 arcsec), that means that a large part of your source flux will be outside of the NICER field of view. In that case, consider using the flat profile instead.

A more detailed discussion of individual surface brightness profiles follows.

Point Source (profile=point)

This is the default profile and the total flux is concentrated at a point centered at the target position. The output result is the fractional vignetting response for that source, between 1.0 (purely on-axis) and 0.0 (far off-axis, outside of the NICER field of view). This should be the choice for true point sources and diffuse objects smaller than about 10 arcsec.

Flat Sky Background (profile=flat)

This profile considers the brightness profile to be flat across the entire NICER field of view. This would typically be used for spatially large objects (much larger than the NICER ~200 arcsec radius field of view), or for generic sky backgrounds.

The output of this profile is the amount of solid angle subtended by each NICER module. The units of the output are determined by the 'angunit' parmeter, specifically in solid angle units angunit^2.

Gaussian Profile (profile=gaussian)

This profile is a gaussian centered at the target location. This would be appropriate for somewhat diffuse objects which are smaller than the NICER field of view but bigger than about 10 arcsec.

The user must specify the parameter "profpar=sigma:value" where value is the gaussian sigma value in each X and Y dimension, in arcseconds. As noted above, sigma values smaller than 10 arcseconds should be avoided.

Note that the gaussian is only calculated out to an approximate radius of 3-sigma. Beyond that, the profile is assumed to be zero. Compared to the point-like profile, the gaussian computation will take approximately 36*(sigma/10)^2 times longer. Thus, large values of sigma should be avoided; when sigma approaches 200 arcsec, consider using the flat model instead.

The normalization of the gaussian is not important. Internally, the gaussian profile is normalized so that the total integrated flux is unity.

Radial profile (profile=radial)

The user can specify a custom radial profile. This profile represents the azimuthally-averaged surface brightness profile. During tracking of a target, off-axis targets typically rotate about the instrumental boresight, so this azimuthally averaged profile is a natural fit for NICER data when averaged over large amounts of observing time.

Profiles should consist of a set of radius values and a set of surface brightness values. The number of profile sample values must be two or greater and the radius values must be strictly ascending. Negative radius or surface brightness values are not permitted.

Absolute normalization and/or units of the profile sample values is not important, other than they be in units of flux or counts per unit solid angle. Internally, the profile will be normalized to a total solid-angle-integrated flux of unity.

IMPORTANT: the final surface brightness sample value must be zero, to establish the boundary of the target.

The units of the profile are flux or counts per unit solid angle. I.e. counts per steradian or per square arcsec, etc. It is not enough to make pure radial profile in radial bins unless each bin is normalized by the number of steradians or square arcseconds in that bin.

Performance. As noted above, spatial variations on scales finer than 10 arcsec will not be captured by nivignette; analysis should smooth their profile to at least the 10 arcsec scale. Large diffuse objects will take significant amounts of computing time. Compared to the point-like profile, the radial computation will take approximately 4*(max_radius/10)^2 times longer, where max_radius is the largest radial sample. If possible, large profiles should be avoided, especially if they contain many near-zero values.

There are two ways to specify a profile, either directly on the command line or by specifying an input FITS binary table file.

To use the command line, use a profpar parameter of the following form.

where radiusi are the radius values in arcseconds, and the valuei are the surface brightness values in per-solid-angle units. The parentheses are required in the syntax.

To specify a FITS file, use a profpar parameter of the form, profpar=file:filename, where filename is the name of the file containing the profile. The file should contain at least two columns of the following form.

The TUNITn keyword of RADIUS is checked to verify that it is specified in units of arcsec.

PARAMETERS

infile [filename]
Input target coordinate file, calculated by nitargdet using aligncol=Q_TIP.
outfile [filename]
Output FITS table file name.
(vigfile="CALDB") [string]
Vignette profile calibration file, or CALDB.
(xrcshellfile="CALDB") [string]
XRC shell calibration file, or CALDB.
(xrcalignfile="CALDB") [string]
XRC alignment calibration file, or CALDB.
(profile="point") [string]
X-ray surface brightness profile name. Must be one of "point" (point-like), "flat" (flat sky background), "gaussian" (Gaussian).
(profpar="NONE") [string]
Special parameters for given X-ray surface brightness profile. For the gaussian profile (profile="gaussian") it is required to specify the Gaussian sigma value as profpar="sigma:value" where value is the Gaussian standard deviation of each axis. For other profiles that do not require special parameters, set profpar=NONE
(angunit="arcsec") [string]
Specifies the units of angular quantities. In particular, when profile="flat", angunit specifies the units of solid angle. Allowed values are "arcsec", "arcmin", "deg", "rad", "sr". For example, when angunit="arcsec" the output units will be arcsec^2.
(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 calibration alignment information. The correct file is selected using standard CALDB access processes.

1. Compute vignetting values for point source. The input file is mytarg.fits (produced by nitargdet detlist=ALL aligncol=Q_TIP), and the output is myvignette.fits

  nivignette mytarg.fits myvignette.fits profile=point

1. Compute vignetting values for flat sky background. Input and output files are as before. The output units are arcmin^2.

  nivignette mytarg.fits myvignette.fits profile=flat angunit=arcmin

SEE ALSO

niprefilter2
nitargdet

LAST MODIFIED

Mar 2021