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.
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.
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.
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 "
) 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:
Installing with pip
NOVT can be installed with pip, the package installer for Python, with the following command:
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:
Once the application is installed, it can be opened with the following command:
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.
The GUI gives the user complete control over what is displayed. The available input fields are:
- Background image from a FITS image
- Output directory
- Catalog of sources
- DS9 parameters
- Coordinates of the center and orientation of the NIRSpec MSA
- Coordinates of the center and orientation of the NIRCam short and/or long wavelength channel
- NIRCam dither patterns
- NIRCam mosaics
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.
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 '
The source catalog (m51.radec) contains a selection of massive young clusters and it is an ASCII file with the following format:
|column 1||RA||Float||degrees||Right ascension of the source|
|column 2||DEC||Float||degrees||Declination of the source|
Primary source (P) or Filler source (F)
|column 4||F814W||Float||magnitude||F814W 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:
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:
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
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' 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.
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', '
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.
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:
|column 1||RA||Float||degrees||Right Ascension of the source||Required|
|column 2||DEC||Float||degrees||Declination of the source||Required|
|column 3||Type||String||Is source a Primary or a Filler ? Use letters P or F||Optional|
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
. This file has the following structure:
|column 1||MJD||days||Modified Julian Day. Add 2400000.5 to express time in JDTDB Julian Day Number, Barycentric Dynamical Time|
|column 2||MIN_V3PA||degrees||Minimum V3PA value|
|column 3||MAX_V3PA||degrees||Maximum V3PA value|
|column 4||MIN_NIRCam||degrees||Minimum NIRCam aperture position angle|
|column 5||MAX_NIRCam||degrees||Maximum NIRCam aperture position angle|
|column 6||MIN_NIRSpec||degrees||Minimum NIRSpec aperture position angle|
|column 7||MAX_NIRSpec||degrees||Maximum NIRSpec aperture position angle|
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.
If you need help with this application or encountered any problems, please contact the JWST Help Desk.
|2.4||12MAR2018||Corrected the input fields "aperture position angle"|
|2.3||01JAN2018||Added NIRSpec fixed slit aperturesAdded NIRCam 8NIRSPEC dither patternChanged launch date and science cycles in timeline|
|2.2||14JUN2017||DS9 parameters added to GUI. Added output directoryFootprints colors|
|2.0||06JUN2017||Major re-write of the code. Compatible with Python 2.7 and Python 3.0|
|1.2||30MAY2017||Added output table with aperture position angles from GTVT|
|1.1||26MAY2017||Added hhmmss format for RA |
Added ddmmss format for DEC
Changed the naming convention of dither patterns to FULL3 FULL3TIGHT FULL6
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