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.
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 disk 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.
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.
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.
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.
This profile is a uniform surface brightness profile with a disk shape on the sky, centered at the target location. Unlike "flat", which is recorded in surface brightness per solid angle and unbounded over the entire sky, the disk model is bounded and thus has a finite total flux. This profile may be appropriate for some supernova remnants.
The user must specify the parameter "profpar=radius:value" where value is the disk radius value in each X and Y dimension, in arcseconds. As noted above, sigma values smaller than 10 arcseconds should be avoided.
Compared to the point-like profile, the gaussian computation will take approximately 4*(sigma/10)^2 times longer. Thus, large values of sigma should be avoided; when sigma approaches 200 arcsec, consider using the flat model if the target fills NICER's FOV.
The profile is normalized so that the total integrated flux is unity. Thus, when fitting spectral data to models, the fitted flux should represent the total flux of the target, including portions that may not be in NICER's field of view.
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.
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.
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