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.
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 two tools for investigating JWST target visibilities. In mid-2018, the assumed orbital ephemeris and default time period over which the calculations run were modified to accommodate the expected launch date of March 2021.
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 plot is displayed, icons can be selected to pan and zoom in on the plot to see detailed information.
As of early March 2018, the GTVT contains an optional aspect that permits the easy inclusion of moving targets instead of just fixed coordinate targets. To access this version, you will need to re-install the GTVT is you have installed it prior to that time. 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.
The GTVT requires a few packages and libraries, all of which are included in the STScI AstroConda python distribution. These dependencies include NumPy, Matplotlib, and AstroPy. Therefore, to avoid problems, we recommend that you download and install AstroConda so that GTVT can be run in the AstroConda environment.
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.
Installation and usage
One can download a .zip file or clone the repository for GTVT from the following GitHub link:
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
Alternatively, if you are familiar with "pip", you can install the tool directly with
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 below.
At present, the GTVT cannot be installed using the "conda install" command. We hope to provide this installation path as an option again in the near future.
To see the GTVT help information, type "jwst_gtvt -h".
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:
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.
Only saves a plot to a file; no interactive plot is displayed.
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.
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.
Saves both outputs to the specified files; there is no interactive plot.
Interactive plot is displayed for all 6 instruments, starting at June 1, 2019 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 two limits shown.
...(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.
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 an 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's plotted. Figure 2 shows an example made with the following command:
Figure 3 is a similar plot for an assumed target near the ecliptic plane (in this example, the ecliptic latitude is only 16.3°). Note how the available angles are restricted to two narrow ranges near 20o and 200o, and there are large ranges of position angle that are unavailable at ANY time for this target due to the JWST observatory constraints.