The JWST NIRSpec Observation Visualization Tool 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 (NOVT) 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 is ideally used for observation planning for programs that seek to acquire observation planning imaging using NIRCam (especially pre-imaging). However, it can also be used to visualize NIRSpec (MOS mode) observations prior to rigorous 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 and input 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.
JWST 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. MOS 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 planning pre-images is very important for the success of multi-object spectroscopy planning.
NIRSpec MOS observers need to provide accurate (relative astrometry of 15 milli-arcsec or less) catalogs 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, it is envisioned that 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 NIRSpec Observation Visualization Tool (NOVT) to help users simultaneously visualize the fields of view of both involved instruments: NIRSpec (MOS mode) and NIRCam (short and long wavelength channels).
Downloading the application
The NIRSpec Observation Visualization Tool (NOVT) requires a few packages and libraries, all of which are included in the STScI AstroConda Python distribution. These dependencies include NumPy, Matplotlib, Tkinter, PyDS9, and AstroPy. Therefore, to avoid problems, we recommend that you download and install AstroConda.
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.
The instructions below are 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:
|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|
Downloading from GitHub
One can download a .zip file or clone the respository for this application from the following GitHub link
and install the tool inside the resulting "jwst_footprints-master" directory (you should see a file called "setup.py" in this directory) with the command
This should produce no error messages and open the graphical user interface.
Graphical user interface
In order to visualize the NIRSpec field of view on the sky at any position, the NIRSpec team has developed the NIRSpec Observation Visualization Tool which 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 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.
Input 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" X 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 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.
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.
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.
|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.
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.
NIRCam AperturesThe 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.
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.
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.
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 that extends from commissioning to the third JWST science cycle. 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.
This Target Visibility plot is a "quick look" Tool for pre-planning purposes, but the Astronomers Proposal Tool 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:
|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|
DS9 region files
NOVT displays both NIRSpec and NIRCam footprints on a user-provided image background. The footprints are generated by calculating the sky coordinates of the corners of each aperture. These are then written as DS9 region files in a user-selected directory, and they are finally 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 according to the user's input and overwrite previous files. The reference system used for the DS9 regions is 'IMAGE' which are the pixel coordinates of the background file.
Quitting the application
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"|
Added NIRSpec fixed slit apertures
Added NIRCam 8NIRSPEC dither pattern
Changed launch date and science cycles in timeline
DS9 parameters added to GUI
Added output directory
|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. et al. 2009, JWST Technical Report
Description and Use of the JWST Science Instrument Aperture File
Ubeda, L. et al. 2016, Proc. SPIE 9910
Planning your JWST/NIRSpec observation: pre-imaging and source catalogue