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).

Accessing the application

NOVT tools may be used directly by a user by installing the Python package, or they may be accessed via a web application served by STScI (coming soon). For more information on using the Python tools, see the software documentation or the example notebooks in the source distribution. The sections below describe usage for the default NOVT application, run either locally or on the STScI host.

Local installation

It is highly recommended that the user install the NOVT package into a virtual environment. For example, use "conda" to create and activate a virtual environment before following the installation and startup steps:

conda create -n jwst_novt python
conda activate jwst_novt

The environment creation command only needs to be run once. Environment activation must be run in the terminal before starting the application, every time it is used.

Installing with pip 

The interactive NOVT tools and their associated dependencies can be installed with "pip", the package installer for Python, with the following command:

pip install jwst-novt[interact]

Installing from GitHub

Alternatively, one can download the source code from GitHub and install the package and its dependencies with the following commands:

git clone https://github.com/spacetelescope/jwst_novt
pip install -e jwst_novt[interact]

Opening NOVT

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

novt

User interface

The NOVT 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 overlaying the resulting regions on the reference background image. 

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. For NOVT purposes, only the first three columns are used.  The first two (RA and Dec) are required for all catalogs.  The Flag column is optional.

Table 1. Format of source catalog m51.radec

Upload data

For most common NOVT use cases, the first step is to upload an image of the target of interest. Start by opening the Upload Data tab.

Try to use an image that covers a region of ~200" × 200" or more of your field of interest. Use the Image File button to browse your computer and choose the image. The only supported cases are FITS files with science data stored in extension 0 and with a valid World Coordinate System (WCS) associated with it. The image should be corrected for distortion.  If you attempt to load an image without a valid WCS, it may appear in the viewer, but no overlay features will be available.

FITS data validation

In order to verify which extension contains the science data in your FITS file, use the following Astropy command line tool fitsinfo:

> fitsinfo image.fits

where in place of image.fits you should use the name of your file. 

The information provided by this 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 documentation.

In order to verify the validity of the WCS keywords in the header of your image, you may also use the Astropy command line tool wcslint:

> wcslint image.fits

If no issues are reported, then the file should work.

Image display

Once the image has been uploaded, it is automatically displayed in a viewer tool integrated in the NOVT interface. If the View Image tab is not already open, expand it now to view your image (Figure 2).

NOVT uses Imviz as its viewer tool. Imviz is a full-featured FITS image display tool developed by STScI as part of the Jdaviz package. You can use the toolbars included in Imviz to configure your image display (image stretch and colormap, zoom and pan, etc.).

Note that only one FITS image can be loaded into Imviz in a session. If you need to replace an uploaded image with a new one, save your work if needed, then reload the browser window to reset NOVT.

Source 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 NOVT, 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 overlay. If there exists a third column with a classification (primary source or filler source) then the application will generate separate overlays for each type, displayed with different colors for visual aid. Figure 3 shows an example of sources displayed close to the center of M51.

To upload your catalog, use the Catalog file button in the Upload Data tab. The expected file extension is ".radec". If your text file has a different extension, you may need to use the options in the file dialog to enable all files before your catalog can be selected.

To turn on or off catalog overlays in your FITS image, toggle the Primary Sources or Filler Sources buttons above the viewer, in the View Image tab. The colors assigned to the catalogs may be edited in the Appearance tab under Upload Data.

Configure 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 4. 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 4.

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

The center of the field is defined by the user with the form fields RA and Dec in the Position tab under Configure NIRSpec Apertures. These parameters must be entered in decimal degrees. After entering a value, hit return or click away from the field to apply the change.

The PA field should be set to the desired aperture position angle (APA) of the MSA, expressed in units of degrees. This angle is given by the JWST General Target Visibility Tool (GTVT). A customized interface to this tool is provided in NOVT (see the "Show timeline" section). Further information on the JWST position angles can be found in the Specifying JWST Position Angles article.

Configure 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 6. 

The NOVT 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.

Enter RA, Dec, and aperture PA in the Configure NIRCam Apertures tab, using the same format rules as with the MSA parameters.  After entering a value, hit return or click away from the field to apply the change. Toggle the NIRCam Short or NIRCam Long buttons to show or hide the NIRCam footprints in the viewer (Figure 7). The colors and fill opacities for the overlays may be configured in the Appearance tab under Configure NIRCam Apertures.

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 8 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 NOVT by setting the Horizontal offset and Vertical offset values in units of arcsec, in the Configure NIRCam Apertures tab. Once those numbers are entered, set the Mosaic field to Yes and the footprint overlays will automatically update. Figure 12 shows an example of a NIRCam mosaic on top of the MSA footprint.

Show timeline

In order to help the user in the definition of ranges of aperture position angles, this application includes customized plots of visibility data provided by the JWST General Target Visibility Tool. This is a Python tool for calculating target visibility windows as a function of time, based on a JWST ephemeris provided by JPL Horizons.

For a given RA and Dec, NOVT plots the aperture position angle range information for NIRSpec and NIRCam within the allowed visibility windows. Open the Show Timeline tab and click the Make Timeline Plot button to show the visibility and PA data.

The code reads the equatorial coordinates RA and Dec from the NIRSpec aperture section and presents a plot over the coming year, by default. Edit the start and end date fields to display different data ranges. Once the plot is displayed, the buttons below the plot can be selected to pan and zoom in on the plot to see detailed information. The average angle in the plot legend is updated to match the values in the date range currently shown.

Figure 13 shows 2 examples of timeline plots: 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 as a shaded area, for NIRCam and NIRSpec. The V3 axis PA for JWST is also plotted as a gray line, for reference.

Save data

Displayed overlay regions (NIRSpec or NIRCam footprints and primary or filler source catalogs) can be downloaded from the NOVT app. Open the Save Data tab and enter a name for the downloaded file in the Region file name field. Click Make Region File to generate the text file, then click Download to save it to your computer. Only the DS9 format is supported at this time, but regions may be recorded in either pixel coordinates corresponding to your FITS image, or in sky coordinates.

To save your work, you may also download a NOVT configuration file. This is a text file in YAML format that specifies the values of any fields you have modified in the NOVT. To generate it, click the Make Config File button under the Save Data tab, then click Download to save it to your computer. This configuration file can be used to restore your work in a future run of the NOVT application: under the Upload Data tab, use the Config file button to identify and upload your config file. A sample configuration file is shown below.

catalog:
  color_alternate: yellow
  color_primary: red
nircam:
  alpha: 0.0
  color_alternate: blue
  color_primary: green
  dec: 47.2109
  dither: FULL3
  mosaic: 'Yes'
  mosaic_v2: 48.0
  mosaic_v3: 60.0
  pa: 60.0
  ra: 202.4642
nirspec:
  alpha: 0.0
  color_primary: red
  dec: 47.2109
  pa: 45.0
  ra: 202.4642
save:
  config_filename: novt_config_m51.yaml
  coordinates: sky coordinates
  region_filename: novt_overlays_m51_dither_mosaic.ds9
timeline:
  dec: 47.2109
  end_date: 2025-01-01
  ra: 202.4642
  start_date: 2023-01-01

Support

If you need help with this application or encounter any problems, please contact the JWST Help Desk or file a ticket on the NOVT GitHub repository.

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