JWST General Target Visibility Tool Help

The JWST General Target Visibility Tool (GTVT) is a command-line Python tool that provides quick-look assessments of target visibilities and position angles for all JWST instruments.

On this page

See also: JWST Moving Target Visibility Tool Help, JWST Position Angles, Ranges, and Offsets, JWST Observatory Coordinate System and Field of Regard

The JWST General Target Visibility Tool (GTVT) is a Python command-line tool for calculating target visibility windows as a function of time. GTVT is one of 2 primary tools for investigating JWST target visibilities.

For a given RA and Dec, the GTVT provides the reference position angle (PA) information for all 4 science instruments and the FGS within the allowed visibility windows. It also outputs the V3 axis PA for reference. Results are in the form of an ASCII file as well as one or more summary plots. A number of options are available from the command line for tailoring the output to your needs. Once the interactive plot is displayed, icons can be selected to pan and zoom in on the plot to see detailed information.

The GTVT contains an optional branch that permits the easy inclusion of moving targets instead of just fixed coordinate targets. See JWST Moving Target Visibility Tool Help for more information on this option.

The schedulability of a given target observation is more complex than just its visibility. It also involves the availability of guide stars as a function of time and other constraints that may be set with special requirements in APT. The GTVT is a "quick look" tool for pre-planning purposes, but the Astronomers Proposal Tool is the true arbiter of schedulability for a given proposed observation.


Dependencies

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

The GTVT requires a few Python packages and libraries. These dependencies include NumPy, Matplotlib, Astropy, Astroquery, and pysiaf.  Use the

pip install [PACKAGE]

command (where PACKAGE is one of the dependencies listed above) to assess whether it is installed.  If not already installed, the pip command will do so.



Installation and usage

The GTVT is currently incompatible with Windows operating systems.

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

https://github.com/spacetelescope/jwst_gtvt

and install the tool inside the resulting jwst_gtvt-master directory (you should see a file called setup.py in this directory) with the command 

python setup.py install

Alternatively, if you are familiar with pip, you can install the tool directly with

pip install jwst_gtvt

or

pip install git+https://github.com/spacetelescope/jwst_gtvt.git

These options assume you have separately verified that your computer has access to the dependencies listed above. Once successfully installed, the program can be run from the command line, as described in the next section.



Usage tips

To see the GTVT help information, type jwst_gtvt -h.

usage: jwst_gtvt [-h] [--v3pa V3PA] [--save_plot SAVE_PLOT] [--save_table SAVE_TABLE] [--instrument INSTRUMENT] [--name NAME]
                 [--start_date START_DATE] [--end_date END_DATE] [--no_verbose]
                 ra dec

positional arguments:
  ra                    Right Ascension of target in either sexagesimal (hh:mm:ss.s) or degrees.
  dec                   Declination of target in either sexagesimal (dd:mm:ss.s) or degrees.

options:
  -h, --help            show this help message and exit
  --v3pa V3PA           Specify a desired V3 (telescope frame) Position Angle.
  --save_plot SAVE_PLOT
                        Path of file to save plot output.
  --save_table SAVE_TABLE
                        Path of file to save table output.
  --instrument INSTRUMENT
                        If specified plot shows only windows for this instrument. Options: nircam, nirspec, niriss, miri, fgs, v3
                        (case insensitive).
  --name NAME           Target Name to appear on plots. Names with space should use double quotes e.g. "NGC 6240".
  --start_date START_DATE
                        Start date for visibility search in yyyy-mm-dd format. Earliest available is 2021-12-26.
  --end_date END_DATE   End date for visibility search in yyyy-mm-dd format. Latest available is 2024-10-02.
  --no_verbose          Suppress table output to screen



GTVT command line examples

When using GTVT in the command line, you only need to specify RA and Dec (the default input values). Observability windows are shown on the terminal, and plots of visibility windows for each instrument are displayed. However, there are other useful command-line options, as shown in the examples below; each command is followed by a text description.

jwst_gtvt 325.678 43.586 --name "SS Cyg"

This command runs and produces an interactive visibility plot on the screen for all instruments. No files are saved to disk. Note that enclosing the target name in double quotes allows for spaces in the text. To exit the program, close the plot window. Alternatively, if you want access to the terminal window from which the tool was run prior to exiting the program, add an ampersand "&" at the end of the command-line entry above to run the program in the background.

jwst_gtvt 325.678 43.586 --name "SS Cyg" --save_plot SSCyg_all.png

This command only saves a plot to a file; no interactive plot is displayed.

jwst_gtvt 325.678 43.586 --name "SS Cyg" --instrument v3 --save_plot SSCyg_v3.png

This command shows a single instrument panel for (in this case) the V3PA. The allowed values for --instrument are "nircam", "nirspec", "niriss", "miri", "fgs", and "v3" (case insensitive). To exit the program, close the plot window.

jwst_gtvt 325.678 43.586 --name "SS Cyg" --save_table SSCyg.dat

The command produces a plot on the screen for all 6 instruments. Tabular data are sent to a file instead of being displayed on the screen. To exit the program, close the plot window.

jwst_gtvt 325.678 43.586 --name "SS Cyg" --save_plot SSCyg_all.jpg --save_table SSCyg1.dat

This command saves both outputs to the specified files; there is no interactive plot.

jwst_gtvt 325.678 43.586 --name "SS Cyg" --start_date 2022-07-01 --end_date 2023-06-30

An interactive plot is displayed for all 6 instruments, starting at July 1, 2022 and running for one year. To exit the program, close the plot window.

The example below shows the top portion of an ASCII output file from a simple run of GTVT. The top section provides a summary of the target and windows, and the bottom table (truncated) shows the day-by-day minimum and maximum allowed angles in each of the visibility windows for each instrument. The nominal angles are approximately midway between the 2 limits shown.

                ecliptic
RA      Dec     latitude
325.678  43.586  52.656

Checked interval [2021-12-26, 2024-10-02]
|           Window [days]                 |    Normal V3 PA [deg]    |
   Start           End         Duration         Start         End         RA            Dec     
 2022-06-02      2022-12-20       201.07     243.68898      50.62431     325.67800      43.58600 
 2023-06-02      2023-12-21       201.99     243.89490      50.12458     325.67800      43.58600 
 2024-06-02      2024-10-02       121.10     243.35636     124.30248     325.67800      43.58600 


                V3PA          NIRCam           NIRSpec         NIRISS           MIRI          FGS
   Date      min    max      min    max       min    max     min    max      min    max      min    max

2022-06-03   240.06 247.16   239.96 247.07    18.63  25.73   240.62 247.73   244.90 252.00   238.82 245.92
2022-06-04   238.94 246.76   238.84 246.66    17.50  25.32   239.50 247.32   243.77 251.59   237.70 245.51
2022-06-05   237.81 246.35   237.72 246.25    16.38  24.92   238.38 246.91   242.65 251.19   236.57 245.11
2022-06-06   236.69 245.95   236.60 245.85    15.26  24.51   237.25 246.51   241.53 250.78   235.45 244.70
2022-06-07   235.57 245.54   235.48 245.45    14.14  24.11   236.13 246.10   240.41 250.38   234.33 244.30
2022-06-08   234.69 244.90   234.60 244.80    13.26  23.47   235.26 245.46   239.53 249.74   233.45 243.66
2022-06-09   233.94 244.14   233.84 244.04    12.50  22.71   234.50 244.70   238.77 248.98   232.70 242.90
2022-06-10   233.18 243.38   233.08 243.28    11.75  21.95   233.74 243.94   238.01 248.22   231.94 242.14
2022-06-11   232.42 242.62   232.32 242.53    10.99  21.19   232.98 243.18   237.26 247.46   231.18 241.38
2022-06-12   231.66 241.86   231.57 241.77    10.23  20.43   232.23 242.43   236.50 246.70   230.42 240.62
2022-06-13   230.91 241.11   230.81 241.01     9.47  19.67   231.47 241.67   235.74 245.94   229.67 239.87
2022-06-14   230.15 240.35   230.05 240.26     8.72  18.92   230.71 240.91   234.99 245.19   228.91 239.11
2022-06-15   229.39 239.60   229.29 239.50     7.96  18.16   229.95 240.16   234.23 244.43   228.15 238.36
2022-06-16   228.63 238.84   228.54 238.74     7.20  17.41   229.19 239.40   233.47 243.68   227.39 237.60
2022-06-17   227.87 238.09   227.78 237.99     6.44  16.65   228.43 238.65   232.71 242.92   226.63 236.85
2022-06-18   227.11 237.33   227.01 237.24     5.68  15.90   227.67 237.89   231.95 242.17   225.87 236.09
2022-06-19   226.35 236.58   226.25 236.48     4.92  15.14   226.91 237.14   231.19 241.41   225.11 235.34
2022-06-20   225.59 235.82   225.49 235.72     4.15  14.39   226.15 236.38   230.42 240.66   224.35 234.58
2022-06-21   224.82 235.07   224.72 234.97     3.39  13.63   225.38 235.63   229.66 239.90   223.58 233.83
2022-06-22   224.06 234.31   223.96 234.21     2.62  12.88   224.62 234.87   228.89 239.15   222.81 233.07
2022-06-23   223.29 233.55   223.19 233.46     1.85  12.12   223.85 234.11   228.12 238.39   222.05 232.31
2022-06-24   222.52 232.79   222.42 232.70     1.08  11.36   223.08 233.36   227.35 237.63   221.28 231.55
2022-06-25   221.75 232.04   221.65 231.94     0.31  10.60   222.31 232.60   226.58 236.87   220.50 230.79
2022-06-26   220.97 231.28   220.87 231.18   359.54   9.84   221.53 231.84   225.81 236.11   219.73 230.03
2022-06-27   220.19 230.51   220.10 230.42   358.76   9.08   220.76 231.07   225.03 235.35   218.95 229.27
2022-06-28   219.41 229.75   219.32 229.65   357.98   8.32   219.98 230.31   224.25 234.59   218.17 228.51
2022-06-29   218.63 228.98   218.53 228.89   357.20   7.55   219.19 229.55   223.47 233.82   217.39 227.74
2022-06-30   217.85 228.22   217.75 228.12   356.41   6.78   218.41 228.78   222.68 233.05   216.61 226.98
2022-07-01   217.06 227.45   216.96 227.35   355.62   6.01   217.62 228.01   221.89 232.28   215.82 226.21
2022-07-02   216.27 226.68   216.17 226.58   354.83   5.24   216.83 227.24   221.10 231.51   215.03 225.43
2022-07-03   215.47 225.90   215.37 225.80   354.04   4.47   216.03 226.46   220.31 230.74   214.23 224.66
2022-07-04   214.67 225.12   214.58 225.03   353.24   3.69   215.23 225.69   219.51 229.96   213.43 223.88
2022-07-05   213.87 224.35   213.77 224.25   352.44   2.91   214.43 224.91   218.71 229.18   212.63 223.10
2022-07-06   213.06 223.56   212.97 223.47   351.63   2.13   213.63 224.12   217.90 228.40   211.82 222.32
2022-07-07   212.25 222.78   212.16 222.68   350.82   1.34   212.82 223.34   217.09 227.61   211.01 221.54
2022-07-08   211.44 221.99   211.34 221.89   350.01   0.55   212.00 222.55   216.28 226.82   210.20 220.75
2022-07-09   210.62 221.20   210.52 221.10   349.19 359.76   211.18 221.76   215.46 226.03   209.38 219.95
2022-07-10   209.80 220.40   209.70 220.30   348.36 358.97   210.36 220.96   214.63 225.24   208.56 219.16
2022-07-11   208.97 219.60   208.87 219.50   347.54 358.17   209.53 220.16   213.80 224.44   207.73 218.36
2022-07-12   208.14 218.80   208.04 218.70   346.70 357.36   208.70 219.36   212.97 223.63   206.90 217.56

...(full table truncated)



Example plots from GTVT

By default, a plot showing 6 panels (one for each instrument, the FGS, and the observatory V3PA) will be displayed by GTVT on the screen or sent to a named output file. The y-axis of each plot shows valid aperture PAs for each instrument as a function of time. These values can be entered into the relevant APT special requirements as needed for a given science case.

Figure 1. The default 6-panel GTVT output plot

Note that over time, a large range of potential position angles are available for this target, which is at ecliptic latitude 52.6°, and the pattern repeats closely from one year to the next.

This summary plot may not be that useful when saved as a file. But in interactive mode, icons at the lower left of the plot window allow you to pan and zoom within each panel for a closer look at the figures. After panning and zooming in the interactive plot, the right-most icon provides another way to save the current view of the interactive plot.

Alternatively, for viewing a single instrument, use the --instrument argument to specify a particular instrument; this produces a display with a single panel plot for that instrument. Also, the time range on the default plot covers the entire current period with a preliminary orbital ephemeris. You can also use the --start_date and --end_date arguments to shorten the time range that is plotted. Figure 2 shows an example made with the following command:

jwst_gtvt 325.678 43.586 --name "SS Cyg" --instrument nirspec --start_date 2022-07-01 --end_date 2023-01-31

Figure 2. A GTVT plot for a single instrument and a restricted time range

This target is at an ecliptic latitude of 52.6° and has a single, long visibility period between the chosen dates. A wide range of position angles are available for such a target.

Additional information on JWST’s pointing restrictions, and how those affect target visibility and available position angles are included in the article JWST Position Angles, Ranges, and Offsets

 


Latest updates
  •  
    Updated for JWST General Target Visibility Tool (GTVT) version 0.3.0.

  •  
    Updated for version 0.2.0.


  • Removed language about specific launch date and made generic.

  •   
    Added a note about incompatibility with Windows.


  • Removed "conda install" instructions for the time being.

  •  
    Comment added regarding updated ephemeris.

  •  
    Added a note and link regarding the moving target option of GTVT.
Originally published