NIRSpec Observation Visualization Tool Help

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. 

On this page

The NIRSpec Observation Visualization Tool was created to help users simultaneously visualize the fields of view of both the NIRSpec (MOS mode) and NIRCam (short and long wavelength channels). This tool can be used for observation planning for programs that seek to acquire imaging using NIRCam (especially NIRCam pre-imaging). However, it can also be used to visualize NIRSpec (MOS mode) observations prior to observation planning using the MSA Planning Tool (MPT) in the Astronomers Proposal Tool (APT)

The NOVT is meant to improve user understanding of the observatory orientation and field constraints. It is not recommended to use the tool to derive strict execution orientation restrictions on either the NIRCam or NIRSpec observations. As true for all JWST programs, observations are easier to schedule and accommodate in observatory planning if they have no execution orientation restrictions at proposal submission. A minimum range of possible angles for observation execution is recommended to be 20 degrees, to ensure program schedulability.

As a reminder, teams are not allowed to add orientation constraints to observations that have already been accepted. Any necessary angle special requirement must be defined at proposal time.


Motivation

NIRSpec will acquire sensitive multi-object spectroscopy (MOS) by placing science sources in the open 0."2 wide micro-shutter assembly (MSA) spectral shutters. In order to plan the observations, exquisitely accurate catalog coordinates 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 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 milli-arcsec 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

The NOVT requires a few packages and libraries, all of which are listed in the "setup.py" file and included in the STScI AstroConda Python distribution. These dependencies include Setuptools, NumPy, Matplotlib, Tkinter, PyDS9, and AstroPy. Therefore, to avoid problems, we recommend that you download and install AstroConda. When you download, select Python 3+ for the installation.

AstroConda runs from within the bash shell. If TCSH or CSH are your default shells, either change your terminal window to the bash shell (type "bash -l") before running the program, and/or consider changing your default shell to the bash shell. Further information on setting up AstroConda for your machine is available in the AstroConda documentation. Help can also be obtained by contacting the JWST Help Desk.

Before trying to install or open NOVT, activate the AstroConda environment using the following command:

$ source activate astroconda

Installing with pip 

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

(astroconda)$ pip install jwst-footprints

Installing from GitHub

Alternatively, one can download a .zip file or clone the repository for this application from GitHub, and install the tool inside the resulting "jwst_footprints-master" directory (you should see a file called "setup.py" in this directory) with the following commands:

(astroconda)$ git clone https://github.com/spacetelescope/jwst_footprints
(astroconda)$ cd jwst_footprints
(astroconda)$ python setup.py install

Opening NOVT

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

(astroconda)$ 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. 

Figure 1. NIRSpec observation visualization tool GUI

Version 2.3 of the user interface. All parameters used by the application are managed from this window.

The GUI gives the user complete control over what is displayed. The available input fields are:

These fields, along with the Display, View Timeline, and Quit buttons, are discussed in detail in the following sections of this article. Clicking on any of the items above will take you directly to that section.

There are two mandatory entries in the GUI: the first item is the background image, and the second item is the output directory. The rest of the entries are optional. 


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 electrons/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 and it is an ASCII file with the following format:



NameTypeUnitDescription
column 1RAFloatdegreesRight ascension of the source
column 2DECFloatdegreesDeclination of the source
column 3TypeString

Primary source (P) or Filler source (F)

column 4F814WFloatmagnitudeF814W magnitude of the source


* Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.


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 files must have the science data in extension zero and a proper World Coordinate System (WCS) in the Primary Header.

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 following column structure:



NameTypeUnitDescriptionOption
column 1RAFloatdegreesRight Ascension of the sourceRequired
column 2DECFloatdegreesDeclination of the sourceRequired
column 3TypeString
Is source a Primary or a Filler ? Use letters P or FOptional


It is possible to have additional columns, but they will not be used by this application. If there are only two 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.

Figure 2. Displaying sources

The example catalog m51.radec is plotted using two region files, the first for the primary sources in color red and the second for the filler sources in color yellow.


NIRSpec apertures

The NIRSpec MSA contains ~250,000 micro shutters (apertures) that are organized in four 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.2" 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.

Make sure that the input coordinates fall within the field of view of the image. Otherwise DS9 will not be able to display the region file. Region files are stored in the Output directory.

The MSA 'Aperture PA' is the aperture position angle of the MSA that should be expressed in units of degrees. This angle is given by the JWST General Target Visibility Tool (GTVT).  A customized version of this tool is provided in this GUI by clicking on the 'View Timeline' button. Further information on the JWST position angles can be found in the Specifying JWST Position Angles article.

The recommended practice in MSA observation planning is to experiment with a range of Aperture Position Angles as opposed to one single fixed angle. Since programs that specify fixed orientations can restrict scheduling opportunities, most NIRSpec MOS programs will be submitted without orientation restrictions, in order to allow the schedulers to find suitable windows for them. Once an accepted MOS observation has been placed on a long range plan, a specific position angle will be assigned for use in detailed planning.

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 over plotted on the background image. The default color of the MSA quadrants footprints is 'Red', but a variety of line colors are available.

Figure 3. NIRSpec MSA and IFU fields of view

The NIRSpec apertures (MSA quadrants, IFU, and fixed slits) are over plotted on an HST/ACS image of M51. The location of the fiducial point is marked with a plus sign. The IFU aperture is shown on the right side between MSA quadrants 3 and 4. The small fixed slits are also shown in red. The yellow labels are not part of the application, they are used here to guide the user in the identification of the different apertures, and to show scale.



NIRCam apertures

The JWST Near Infrared Camera (NIRCam) has ten IR detectors. Two detectors are sensitive to longer wavelengths  (2.4–5.0 μm) and make the long wavelength channel (LWC). The remaining eight 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 over plotted 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.

Figure 4. NIRCam LWC and SWC footprints

NIRCam has two channels that image the sky simultaneously: the Long Wavelength Channel (LWC, left) and the Short Wavelength Channel (SWC, right). Their fields of view are shown here on top of an HST/ACS mosaic of the galaxy pair NGC5194+NGC5195. The plus sign represents the fiducial point whose equatorial coordinates (RA, DEC) are defined by the user in the GUI. The yellow labels are not part of the application, they are used here to show scale.



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

Figure 5. Selecting NIRCam dither patterns

Available dither options for the NIRCam imager. The default value is 'None' meaning that no offsets will be shown.
In order to display a dither pattern, simply select the pattern by name and then click the 'Display' button at the bottom of the GUI and the footprints should be over plotted on top of the background image.  Figure 6 shows the three FULL dither options for both channels. Figure 7 shows the 8NIRSPEC dither pattern on the same target. Figure 8 presents a comparison of fields of view of the 8NIRSPEC dither pattern with the MSA footprint over plotted on M51
Figure 6. Available NIRCam FULL dither patterns

Different views showcasing the available NIRCam dither patterns in the application. The top row represents the FULL3, FULL3TIGHT, and FULL6 patterns using the LWC. The bottom row displays the same patterns using the SWC. The background image is an HST/ACS mosaic of the galaxy pair NGC5194+NGC5195. The aperture position angle used for this figure is 60°.
Figure 7. NIRCam FULLBOX 8NIRSPEC dither pattern

The 8NIRSPEC FULLBOX dither pattern shown using the LWC (left) and SWC (right). The background image is an HST/ACS mosaic of the galaxy pair NGC5194+NGC5195. The aperture position angle used for this figure is 0°. This pattern covers a rectangular region without gaps.
Figure 8. NIRCam 8NIRSPEC dither pattern and the MSA

The 8NIRSPEC FULLBOX dither pattern shown in blue together with the NIRSpec apertures in red. Note that the dither pattern is designed to cover the MSA footprint at any aperture position angle. The yellow tables are not part of the application, they are used here to show the position of the MSA quadrants, the IFU and to show scale.



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 two-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 over plotted on top of the background image. Figure 9 shows an example of a NIRCam mosaic on top of the MSA footprint.

Figure 9. NIRCam mosaic example

Two tile mosaic example created using the NIRCam LWC. The gap between the modules is 45" and 48" for the long wavelength detectors. In this case we chose 48" as the horizontal offset and 60" for the vertical offset. For reference, the MSA field of view is also shown in red using the same equatorial coordinates (RA, DEC) for the fiducial point. MSA quadrants 1 and 4 are completely covered by the NIRCam detectors. The NIRcam aperture position angle is 0° and the NIRSpec aperture position angle is 138°.



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 three 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 two examples: a target close to the Equator and a target close to the North Celestial Pole.

Figure 10. Visibility tool output plots

Aperture Position Angle plotted as a function of time using the Visibility Tool. [Bottom] Visibility plot obtained for a target located close to the North Celestial Pole (α=0.0º , δ=+88.0º). [Top] Visibility plot obtained for a target located close to the Equator (α=0.0º , δ=+2.0º). Blue represents NIRCam, red represents NIRSpec, and yellow represents the position angle of the V3 axis (V3_PA).
This Target Visibility plot is a "quick look" Tool for pre-planning purposes, but the APT defines if it is possible to schedule a given proposed observation.  It is advisable to select a range of feasible aperture angles and plan the creation of NIRCam observations for a variety of positions. 

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.  This file has the following structure:



NameUnitDescription
column 1MJDdaysModified Julian Day. Add 2400000.5 to express time in JDTDB Julian Day Number, Barycentric Dynamical Time
column 2MIN_V3PAdegreesMinimum V3PA value
column 3MAX_V3PAdegreesMaximum V3PA value
column 4MIN_NIRCamdegreesMinimum NIRCam aperture position angle
column 5MAX_NIRCamdegreesMaximum NIRCam aperture position angle
column 6MIN_NIRSpecdegreesMinimum NIRSpec aperture position angle
column 7MAX_NIRSpecdegreesMaximum NIRSpec aperture position angle



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

2.4.212DEC2019Modified timeline
2.412MAR2018Corrected the input fields "aperture position angle"
2.301JAN2018Added NIRSpec fixed slit aperturesAdded NIRCam 8NIRSPEC dither patternChanged launch date and science cycles in timeline
2.214JUN2017DS9 parameters added to GUI. Added output directoryFootprints colors
2.006JUN2017Major re-write of the code. Compatible with Python 2.7 and Python 3.0
1.230MAY2017Added output table with aperture position angles from GTVT
1.126MAY2017Added hhmmss format for RA 
Added ddmmss format for DEC
Changed the naming convention of dither patterns to FULL3 FULL3TIGHT FULL6
1.014JUL2016Initial version



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 




Published

 

Latest updates

  • Corrected the input fields NIRCam aperture PA and NIRSpec aperture PA
    Modified to document new 8NIRSPEC dither pattern in updated code