NIRSpec Observation Visualization Tool Help

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. 

On this page

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 requirementmust be defined at proposal time.


Motivation

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 

Dependencies

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.

Further information on setting up AstroConda for your machine is availble in the AstroConda documentation. Help can also be obtained by contacting the JWST Help Desk.

Example data

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:


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



Installation

Downloading from GitHub

One can download a .zip file or clone the repository for this application from the following GitHub link 

https://github.com/spacetelescope/jwst_footprints

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

$ bash -l
$ source activate astroconda
(astroconda)$ git clone https://github.com/spacetelescope/jwst_footprints
(astroconda)$ cd jwst_footprints
(astroconda)$ python setup.py install
(astroconda)$ jwst_footprints

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. 

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 are discussed in detail in the following sections of this articleClicking 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. 



Step-by-step instructions

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" × 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 MSA aperture position angle 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°.



Target visibility

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.

Figure 10. Visibility tool output plots

Aperture Position Angle plotted as a function of time using the Visibility Tool. The shaded areas represent the JWST Commissioning and first two science cycles, assuming a launch date of 01MAR2019. [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 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:



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



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.



Support

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



Version history

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