The JWST NIRSpec Observation Visualization Tool (NOVT) is a Python application that provides a simultaneous view of both NIRSpec and NIRCam fields of view on a given sky position, for assistance in planning NIRCam pre-imaging for NIRSpec. 

NIRSpec will acquire sensitive multi-object spectroscopy (MOS) by placing science sources in the open 0.20" wide micro-shutter assembly (MSA) spectral shutters. In order to plan the observations, catalog coordinates with exquisite relative accuracy will be needed for the most accurate placement of science sources within their MSA shutters, which translates to optimal data calibration accuracy. NIRCam is the primary imaging camera for JWST, and it is a source for high quality images for planning NIRSpec spectroscopy and target acquisition. The process of pre-imaging an astronomical field has been developed to support the NIRSpec observation planning, particularly for the complex MOS mode.

Pre-imaging observations are images usually acquired using the same telescope as the multi-object spectroscopy, though not necessarily the same instrument, and are executed in the same observatory semester or cycle. Pre-images are used to define field astrometry for spectral target acquisition and aperture slit placement on science objects. As a result, rapid availability and accuracy of pre-imaging is very important for the success of multi-object spectroscopy planning. 

NIRSpec MOS observers need to provide accurate catalogs (relative astrometry of 15 milliarcsec or less) to pursue their observations with optimal source placement in MSA shutters, and those will be derived from space-based observations. When such high accuracy catalogs are not available, NIRCam pre-imaging will be needed for science planning to achieve optimal data calibration. The term NIRCam pre-imaging is used to describe the use of the NIRCam images to support planning for a NIRSpec observation.

This motivated the creation of the NOVT to help users simultaneously visualize the fields of view of both instruments: NIRSpec (MOS mode) and NIRCam (short and long wavelength channels).

Installation

Dependencies

Please contact the JWST Help Desk with questions regarding installation or usage.

Installing with pip 

NOVT can be installed with pip, the package installer for Python, with the following command:

pip install jwst-footprints

Installing from GitHub

Alternatively, one can download the source code from GitHub and install the tool inside the directory containing "setup.py" with the following commands:

git clone https://github.com/spacetelescope/jwst_footprints
cd jwst_footprints
pip install .

Opening NOVT

Once the application is installed, it can be opened with the following command:

jwst_footprints

Graphical user interface

The NIRSpec Observation Visualization Tool works as a wrapper of the well known SAOImage DS9 astronomical imaging and data visualization application. 

This application is operated from a graphical user interface (GUI) as seen in Figure 1. Its main purpose is to display a user-provided image as reference background, and allow the creation of footprints for both the NIRSpec MSA and NIRCam long and short wavelength channels in a variety of configurations (e.g., dither offsets and mosaics). The footprints are generated by transforming the Science Instrument Aperture File (SIAF) aperture coordinates into sky coordinates and creating and displaying the resulting individual DS9 region files. 

Example data

The example below is based on an HST mosaic of the galaxy pair NGC5194 + NGC5195 generated using Hubble archival data from HST GO Program 10452 (PI: S. Beckwith). The filter used for this observation is F814W, and the image is in units of e^–/sec.

The FITS file can be obtained from the LEGUS Public Access Table  under target name "NGC 5194 + 5195 FULL Mosaic". This is the FITS file F814W mosaic with name "hlsp_legus_hst_acs_ngc5194-ngc5195-mosaic_f814w_v1_sci.fits".

The source catalog (m51.radec) contains a selection of massive young clusters. Its format is described in Table 1. 

Table 1. Format of source catalog m51.radec

FITS background image

The first item that needs to be ingested in the GUI is the image of the target of interest. Try to use an image that covers a region of ~200" × 200" or more of your field of interest. Use the Select File button to browse your computer and choose the image. The only supported case are FITS files with science data stored in extension 0 and with a valid World Coordinate System (WCS) associated with it. The image has to be corrected for distortion. 

FITS image WCS

In order to verify the validity of the WCS keywords in the header of your image, use the Astropy UNIX command line wcslint like this:

> wcslint 'foo.fits'

where in place of foo.fits you should use the name of your file. If no issues are reported, then the file will work.

FITS science data

In order to verify which extension contains the science data in your FITS file, use the following Python code:

>>>from astropy.io import fits
>>>hdulist = fits.open('foo.fits')
>>>hdulist.info()
>>>hdulist.close()

The information provided by this last command will help you identify the extension number of your science data. If the science data is in extension 0, then the FITS file is valid. If the science data is in another extension, consider creating a new FITS file using the information provided in the astropy.io.fits article.

Once the image has been validated, you may display it. Simply load the image and then press the Display button at the bottom of the GUI. At this stage, the Python version of DS9 should open in a new window and display the image in Frame 1. All the properties of DS9 (e.g., adjust scale, color map, zoom, etc.) are available to the user. The default values for displaying the image are given for the example FITS file provided with this application. 

Output directory

The Output directory field is a mandatory entry in the GUI. The user needs to provide a directory name from the home directory (e.g., /Users/myuser/Desktop/). If the directory does not exist, the application will create it. This directory will host the region files generated by the application.

DS9 parameters

In this section of the GUI, the user can set the color map, and scale used to display the image. The available colors to map the image are grey, red, green, blue, and heat.

The Scale options are log, linear, power, sqrt, zscale, and  minmax and they are a subset of the options provided by the DS9 Scale Menu. The Low and High values are the user-defined limits in the pixel value distribution. These are set in the same units as the image pixels.

Input catalog

Displaying individual sources from a catalog is an optional step. Creating an MSA observation requires the construction of a catalog of sources, from which candidate sets of primary and filler sources are usually derived. In order to display a source catalog in DS9, you will have to create a white space-separated text file with the column structure described in Table 2.

Table 2. Column format for input catalog

It is possible to have additional columns, but they will not be used by this application. If there are only 2 columns, the code will assume they are the RA and DEC of each source and display them as a single region file. If there exists a third column with a classification (primary source or filler source) then the application will generate separate region files for each type and display them using different colors for visual aid. Figure 2 shows an example of sources displayed close to the center of M51.

NIRSpec apertures

The NIRSpec MSA contains ~250,000 micro-shutters (apertures) that are organized in 4 quadrants. These quadrants cover the sky over a 12.4 arcmin² field of view as shown in Figure 3. Each open micro-shutter, when projected onto the sky, has dimensions of only 0.20" in the dispersion direction by 0.46" in cross-dispersion. 

The NIRSpec integral field unit (IFU) is a larger (3" × 3") aperture that is located in the bar separating the MSA quadrants. The positioning of the IFU in the sky projection allows for a quick identification of the MSA quadrants. The IFU aperture is placed between quadrants 3 and 4 as shown in Figure 3.

The NIRSpec fixed slits are smaller apertures located on the mounting frame in the space between the MSA quadrants. 

This section of the GUI allows the user to display all the NIRSpec apertures at once: the MSA quadrants footprints, the fixed slits, and the IFU footprint on the DS9 display. In order to display the footprints, set the toggle button to Yes.

The center of the field is defined by the user with the form fields  RA center of MSA and DEC center of MSA. The allowed format for these parameters are either Sexagesimal or decimal degrees.

Once these parameters are entered in the GUI and the toggle button is set to Yes, click the Display button at the bottom of the GUI and the footprints should be overplotted on the background image. The default color of the MSA quadrants footprints is Red, but a variety of line colors are available.

NIRCam apertures

The JWST Near Infrared Camera (NIRCam) has 10 IR detectors. Two detectors are sensitive to longer wavelengths (2.4–5.0 μm) and make the long wavelength channel (LWC). The remaining 8 detectors are sensitive in the range 0.6–2.3 μm and are collectively known as the short wavelength channel (SWC). These detectors image the sky simultaneously over a 9.7 arcmin² field of view as shown in Figure 4. 

The NIRSpec observation visualization application was designed to display the LWC and SWC footprints in several configurations, together or separately. As with the MSA quadrants, their location on the plane of the sky is determined by the RA, Dec, and aperture position angle of the fiducial point. These parameters are independent of the MSA parameters because they are meant to design a NIRCam observation that may take place months before the NIRSpec spectroscopy. Use the same format rules as with the MSA parameters. Once these parameters are entered in the GUI and the toggle button is set to Yes, click the Display button at the bottom of the GUI and the footprints should be overplotted on top of the background image. The default color of the LWC footprints is Blue. The default color of the SWC footprints is Green. Other color options are available. Figure 4 shows the footprints for each channel on top of and HST/ACS mosaic of the galaxy pair NGC5194+NGC5195.

Dither patterns

NIRCam imaging supports a variety of pre-defined dither patterns that optimize the use of the observatory in imaging mode. The pre-imaging goal is to design an image that covers most of the MSA footprint to design a proper MOS observation. Three FULL patterns are considered for this application: FULL3, FULL3TIGHT, and FULL6 with 3, 3, and 6 dither pointings respectively. A 4th dither pattern (that is NIRSpec specific) is the FULLBOX 8NIRSPEC. This pattern is designed to cover a 6' × 5' region large enough for NIRSpec pre-imaging using 8 dither points. The properties of these patterns are described in the NIRCam Primary Dithers article. Figure 5 shows the options in the drop-down menu.

Mosaic patterns

NIRCam mosaic patterns are created using vertical and/or horizontal offsets. Mosaics are composed of tiles, where each tile corresponds to one pointing. Only 2-tile mosaics are supported by this application. Offsets are relative to the selected aperture's reference position in that aperture’s ideal coordinate system (X, Y). For NIRCam, all aperture Ideal coordinate systems are nearly aligned (to ~1° rotation) with the JWST coordinate system (V2, V3).

The offsets are defined in the GUI by setting both the vertical and horizontal values in units of arcsec. Once those numbers are entered, click the Display button at the bottom of the GUI and the footprints should be overplotted on top of the background image. Figure 9 shows an example of a NIRCam mosaic on top of the MSA footprint.

Display

Clicking the Display button will update the NIRSpec and NIRCam footprints on the user-provided background image according to the user's input. The footprints are generated by calculating the sky coordinates of the corners of each aperture, and are written as DS9 region files in a user-selected directory before being displayed. All of these region files have a name that starts with 'ds9-'. Every time the Display button is clicked, the code will generate the region files and overwrite the previous files. The reference system used for the DS9 regions is IMAGE which are the pixel coordinates of the background file. 

View Timeline

In order to help the user in the definition of ranges of aperture position angles, this application includes a customized copy of the JWST General Target Visibility Tool. This is a Python tool for calculating target visibility windows as a function of time. It is currently based on assumed pre-launch JWST orbital parameters. For a given RA and Dec, the tool provides the aperture position angle range information for NIRSpec and NIRCam within the allowed visibility windows.

A version of the GTVT can be accessed directly from within this tool by clicking on the View Timeline button at the bottom of the GUI. The code reads the equatorial coordinates RA and Dec from the MSA section and presents a plot over 3 JWST science cycles. Once the plot is displayed, icons can be selected to pan and zoom in on the plot to see detailed information. Figure 10 shows 2 examples: a target close to the Equator and a target close to the North Celestial Pole.

The Target Visibility Tool calculates the minimum and maximum value for the available aperture position angles. Both are included in the plot for NIRCam, NIRSpec and the V2V3 plane. Zoom in to the plot to see the details. A text table with the data used by the plot is saved in the user-defined output directory as the file v3pa_nircam_nirspec.txt. The file's structure is described in Table 3.

Table 3. Format of file containing data on the target visibility plot

Quit

In order to cleanly quit the application, click on the Quit button located at the bottom of the GUI. Before closing the window, the code saves the current parameters to an internal file and they will be recovered the next time you open the application.

Support

If you need help with this application or encountered any problems, please contact the JWST Help Desk.

Version history

References

Anderson, J. 2009, JWST-STScI-001738
Dither Patterns for NIRCam Imaging

Beck, T. et al. 2016, Proc. SPIE 9910   
Planning JWST NIRSpec MSA spectroscopy using NIRCam pre-images 

Coe, D. 2017, JWST-STScI-005798
More Efficient NIRCam Dither Patterns

Cox, C. & Lallo, M. 2017, JWST-STScI-001550  
Description and Use of the JWST Science Instrument Aperture File 

Ubeda, L. & Beck, T. 2016, Proc. SPIE 9910 
Planning your JWST/NIRSpec observation: pre-imaging and source catalogue