JWST Moving Target Visibility Tool Help
The JWST Moving Target Visibility Tool (MTVT) is a command-line Python tool that provides quick-look assessments of moving target visibilities and position angles for all JWST instruments.
On this page
See also: JWST General Target Visibility Tool Help, JWST Position Angles, Ranges, and OffsetsSolar System Special Requirements, JWST Observatory Coordinate System and Field of Regard
The JWST Moving Target Visibility Tool (MTVT) is a Python command-line tool for calculating moving (solar system) target visibility windows as a function of time. It has similar functionality to that of the JWST General Target Visibility Tool (GTVT), with a few additional features specific to moving targets. The MTVT is bundled with the GTVT, and is automatically installed when users install the GTVT (no stand-alone installation process is provided for the MTVT). Additional documentation can be found at this GitHub page. Both the GTVT and MTVT currently use the post-launch JWST ephemeris.
Unlike the GTVT, users input a solar system target designation, rather than a fixed (RA, Dec) sky position. The designation can be an official name (e.g., Saturn, Gaspra, Encke), number (e.g., 599, 20000), or provisional designation (e.g., 2002 MS4). MTVT uses the JPL Horizons system to resolve the designation, and retrieves the target ephemeris (RA, Dec) at one day intervals. At that point, the functionality of the MTVT is identical to that of the GTVT.
For a given RA and Dec, the MTVT provides the reference position angle information for all 4 science instruments and the FGS within the allowed visibility windows. It also outputs the V3 axis position angle (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 (examples are provided below). Once the plot is displayed, icons can be selected to pan and zoom in on the plot to see detailed information. To execute a new run of the MTVT the plot window must first be closed.
The allowable position angles output by the MTVT can, for example, be used to help users plan observations of giant planet satellites to ensure that the giant planet avoids falling on a nearby science or FGS aperture, or to determine the visibility windows and durations for fast moving near-Earth asteroids (NEAs). In order to visualize an observation in APT using Aladin, users should add a PA range special requirement that reflects the range of allowed position angles from MTVT, and create a fixed target proxy with coordinates consistent with those position angles. Once that is done, visualization can proceed as described in the Visualizing Dithers of a Solar System Observation in APT tutorial.
Note: Use of a fixed target proxy is for planning and visualization purposes only. You should not submit your APT file with the fixed target proxy in place of the moving target.
The schedulability of a given target observation is more complex that 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 and/or Solar System special requirements in APT. The MTVT 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.
Installation and dependencies
The GTVT and MTVT are currently incompatible with Windows operating systems.
The MTVT comes packaged with the GTVT. The user is referred to the "Installation and usage" section on the JWST General Target Visibility Tool Help article for instructions on how to install the GTVT/MTVT (or update it if an older version of GTVT was installed). Note that the assumed orbital ephemeris and default time period over which the calculations run are sufficient to accommodate the duration of Cycles 1 & 2.
Similarly, the user should refer to the "Dependencies" section on the JWST General Target Visibility Tool Help page for information on the packages and libraries required to run GTVT/MTVT. In addition to those packages and libraries, MTVT also requires the Astroquery Python package. This package can be installed with the following command:
pip install astroquery
Once successfully installed, MTVT is run from the command line, as described below.
Usage tips
To see the MTVT help information, type jwst_mtvt -h.
usage: jwst_mtvt [-h] [--smallbody] [--v3pa V3PA] [--save_plot SAVE_PLOT] [--save_table SAVE_TABLE] [--instrument INSTRUMENT]
[--name NAME] [--start_date START_DATE] [--end_date END_DATE] [--no_verbose]
desg [desg ...]
positional arguments:
desg Moving target designation.
options:
-h, --help show this help message and exit
--smallbody Set if the designation is that of a comet or asteroid. This is required for periodic comets with multiple
orbit solutions in JPL/HORIZONS.
--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
MTVT command line examples
The user is referred to the "GTVT command line examples" section of the JWST General Target Visibility Tool Help article for basic GTVT/MTVT commands.
Basic use of the MTVT is shown with the example command below:
jwst_mtvt Ceres
Note that the following command will produce the same results:
jwst_mtvt ceres
After running this command, a table will be output in the terminal and a plot will open in a new window that includes the allowable position angles as a function of time for the V3 axis, the 4 science instruments (NIRCam, MIRI, NIRSpec, NIRISS), and the FGS. Examples of these outputs are shown in the section below, "MTVT outputs."
Official names such as "Ceres," "Jupiter," and "Chiron" are not case-sensitive. However, primary designations such as "1992 QB1" and "2002 MS4" are case-sensitive. Specifically, primary designations must use capital letters or else the MTVT will output an error.
Evaluating planet visibility
An example command for running the MTVT for a planet is shown below:
jwst_mtvt Jupiter
However, running the above command will result in the following message
*******************************************************************************
Multiple major-bodies match string "JUPITER*"
ID# Name Designation IAU/aliases/other
------- ---------------------------------- ----------- -------------------
5 Jupiter Barycenter
599 Jupiter
Number of matches = 2. Use ID# to make unique selection.
*******************************************************************************
In order to obtain a result from the MTVT, the user must select Jupiter Barycenter as the target using ID# 5:
jwst_mtvt 5
Or Jupiter as the target using ID# 599:
jwst_mtvt 599
The ID# of the planet barycenters and the planets themselves used by JPL Horizons are presented in Table 1.
Table 1. JPL Horizons planet ID numbers
ID# | Name |
|---|---|
4 | Mars barycenter |
5 | Jupiter barycenter |
6 | Saturn barycenter |
7 | Uranus barycenter |
8 | Neptune barycenter |
9 | Pluto barycenter |
499 | Mars |
599 | Jupiter |
699 | Saturn |
799 | Uranus |
899 | Neptune |
999 | Pluto |
Evaluating minor body visibility
An example command for running MTVT for a minor body using its name is shown below.
jwst_mtvt Makemake
An example command for running MTVT for a minor body using its provisional designation is shown below.
jwst_mtvt 2007 OR10
An example command for running the MTVT for a minor body using its number and the --smallbody optional argument is shown below. The purpose of this optional argument is to remove ambiguity between low-numbered minor bodies and major bodies. The example below will return information on the asteroid 4 Vesta. But, without the --smallbody optional argument, the MTVT would return information for the Mars barycenter.
jwst_mtvt 4 --smallbody
For higher-numbered minor bodies, the --smallbody optional argument is not necessary, as shown below for the dwarf planet Haumea.
jwst_mtvt 136108
The special case of comets
An example command for running the MTVT for a comet using its name is shown below:
jwst_mtvt Encke
An example command for running the MTVT for a comet using its designation is shown below. Use of the --smallbody optional argument is not necessary for comets when using the designation as the identifier.
jwst_mtvt 2P
The commands above are equivalent and will both result in the following message:
*******************************************************************************
JPL/DASTCOM3 Small-body Index Search Results 2018-Mar-02 19:16:20
Comet AND asteroid index search:
NAME = ENCKE;
Matching small-bodies: Record # Epoch-yr >MATCH DESIG< Primary Desig Name
-------- -------- ------------- ------------- -------------------------
90000031 1786 2P 2P Encke
90000032 1796 2P 2P Encke
90000033 1805 2P 2P Encke
90000034 1819 2P 2P Encke
90000035 1822 2P 2P Encke
90000036 1825 2P 2P Encke
90000037 1828 2P 2P Encke
90000038 1832 2P 2P Encke
90000039 1835 2P 2P Encke
90000040 1838 2P 2P Encke
90000041 1842 2P 2P Encke
90000042 1845 2P 2P Encke
90000043 1848 2P 2P Encke
90000044 1852 2P 2P Encke
90000045 1855 2P 2P Encke
90000046 1858 2P 2P Encke
90000047 1862 2P 2P Encke
90000048 1865 2P 2P Encke
90000049 1868 2P 2P Encke
90000050 1872 2P 2P Encke
90000051 1875 2P 2P Encke
90000052 1878 2P 2P Encke
90000053 1881 2P 2P Encke
90000054 1885 2P 2P Encke
90000055 1888 2P 2P Encke
90000056 1891 2P 2P Encke
90000057 1895 2P 2P Encke
90000058 1898 2P 2P Encke
90000059 1901 2P 2P Encke
90000060 1904 2P 2P Encke
90000061 1908 2P 2P Encke
90000062 1911 2P 2P Encke
90000063 1914 2P 2P Encke
90000064 1918 2P 2P Encke
90000065 1921 2P 2P Encke
90000066 1924 2P 2P Encke
90000067 1928 2P 2P Encke
90000068 1931 2P 2P Encke
90000069 1934 2P 2P Encke
90000070 1937 2P 2P Encke
90000071 1941 2P 2P Encke
90000072 1947 2P 2P Encke
90000073 1951 2P 2P Encke
90000074 1954 2P 2P Encke
90000075 1957 2P 2P Encke
90000076 1961 2P 2P Encke
90000077 1964 2P 2P Encke
90000078 1967 2P 2P Encke
90000079 1971 2P 2P Encke
90000080 1974 2P 2P Encke
90000081 1977 2P 2P Encke
90000082 1980 2P 2P Encke
90000083 1984 2P 2P Encke
90000084 1987 2P 2P Encke
90000085 1990 2P 2P Encke
90000086 1994 2P 2P Encke
90000087 1995 2P 2P Encke
90000088 1998 2P 2P Encke
90000089 2004 2P 2P Encke
90000090 2016 2P 2P Encke
(61 matches. To SELECT, enter record # (integer), followed by semi-colon.)
*******************************************************************************
JPL Horizons contains multiple orbital solutions for periodic comets, so the user must select one option to proceed. The user is less likely to receive this message for long-period comets. If the user does not know the Record # for the orbital solution of interest ahead of time, this is an easy way to see a list of possible values. If the user knows the Record # ahead of time, they can skip the step of viewing the list. If the user wants the most recent orbital solution for 2P/Encke, they would type the following command:
jwst_mtvt 900090
Note that the most recent orbital solution is not selected as a default when running the MTVT.
MTVT outputs
The default outputs for the MTVT are identical to the GTVT: a 6-panel plot showing the allowable position angles for the V3 axis, the 4 science instruments, and the FGS; and an ASCII table containing the information in the plot in table form. See the "Example plots from GTVT" section of the JWST General Target Visibility Tool Help page for instructions on how to output a plot for only one instrument.
The table below shows the dates and duration of each visibility window when the target is in JWST's field of regard, as well as the allowable position angles and the start and end RA and Dec values for these dates. The RA and Dec, along with the allowable position angles for the V3 axis, each of the 4 science instruments, and the FGS, are output for each date that the object is observable by JWST. The table written to the terminal is much longer than shown and has been truncated for the purpose of presentation in this article. The table can be scrolled horizontally to reveal the hidden columns.
$ jwst_mtvt Lempo
TARGET NAME: 47171 Lempo (1999 TC36)
=========================================
Checked interval [2021-12-26, 2024-10-02]
| Window [days] | Normal V3 PA [deg] | RA | Dec |
Start End Duration Start End Start End Start End
2021-12-26 2022-02-11 47.90 67.95104 74.58430 46.05738 45.81946 10.55088 10.68448
2022-08-09 2022-09-30 52.00 254.67284 261.99116 50.58513 50.35068 12.08653 11.88138
2022-12-25 2023-02-13 50.00 68.50396 75.13738 48.30629 48.03686 11.41428 11.53797
2023-08-11 2023-10-02 51.91 255.39243 262.35148 52.81873 52.59405 12.88779 12.69714
2023-12-28 2024-02-16 50.00 69.52688 75.82408 50.52653 50.26924 12.25436 12.37781
2024-08-13 2024-10-02 49.10 256.17395 262.34560 54.87405 54.87405 13.50112 13.50112
V3PA NIRCam NIRSpec NIRISS MIRI FGS
Date RA Dec min max min max min max min max min max min max
2021-12-26 46.06 10.55 61.06 74.84 60.96 74.75 199.62 213.41 61.62 75.40 65.89 79.68 59.82 73.60
2021-12-27 46.04 10.55 61.41 74.97 61.31 74.88 199.97 213.54 61.97 75.54 66.24 79.81 60.17 73.73
2021-12-28 46.02 10.55 61.73 75.09 61.64 75.00 200.30 213.66 62.29 75.65 66.57 79.93 60.49 73.85
2021-12-29 46.01 10.55 62.04 75.21 61.95 75.11 200.61 213.77 62.60 75.77 66.88 80.04 60.80 73.97
2021-12-30 45.99 10.55 62.34 75.32 62.24 75.22 200.91 213.88 62.90 75.88 67.18 80.15 61.10 74.08
2021-12-31 45.97 10.55 62.62 75.42 62.53 75.33 201.19 213.99 63.19 75.99 67.46 80.26 61.38 74.18
2022-01-01 45.96 10.55 62.90 75.53 62.80 75.43 201.46 214.09 63.46 76.09 67.73 80.36 61.66 74.29
2022-01-02 45.95 10.55 63.16 75.63 63.06 75.53 201.73 214.20 63.72 76.19 68.00 80.47 61.92 74.39
2022-01-03 45.93 10.55 63.41 75.73 63.32 75.63 201.98 214.30 63.97 76.29 68.25 80.57 62.17 74.49
2022-01-04 45.92 10.55 63.66 75.83 63.56 75.73 202.22 214.40 64.22 76.39 68.49 80.67 62.42 74.59
2022-01-05 45.91 10.55 63.89 75.93 63.80 75.83 202.46 214.49 64.45 76.49 68.73 80.76 62.65 74.69
2022-01-06 45.89 10.55 64.12 76.03 64.02 75.93 202.69 214.59 64.68 76.59 68.96 80.86 62.88 74.78
2022-01-07 45.88 10.55 64.34 76.12 64.24 76.02 202.91 214.69 64.90 76.68 69.18 80.96 63.10 74.88
2022-01-08 45.87 10.55 64.55 76.22 64.46 76.12 203.12 214.78 65.11 76.78 69.39 81.05 63.31 74.98
2022-01-09 45.86 10.55 64.76 76.31 64.66 76.21 203.33 214.88 65.32 76.87 69.60 81.15 63.52 75.07
2022-01-10 45.85 10.55 64.96 76.41 64.86 76.31 203.53 214.97 65.52 76.97 69.80 81.24 63.72 75.16
2022-01-11 45.84 10.55 65.15 76.50 65.06 76.40 203.72 215.07 65.72 77.06 69.99 81.34 63.91 75.26
2022-01-12 45.83 10.56 65.34 76.59 65.25 76.50 203.91 215.16 65.90 77.15 70.18 81.43 64.10 75.35
2022-01-13 45.82 10.56 65.53 76.69 65.43 76.59 204.09 215.25 66.09 77.25 70.36 81.52 64.29 75.45
2022-01-14 45.81 10.56 65.70 76.78 65.61 76.68 204.27 215.35 66.27 77.34 70.54 81.62 64.46 75.54
2022-01-15 45.81 10.56 65.88 76.87 65.78 76.78 204.44 215.44 66.44 77.43 70.71 81.71 64.64 75.63
2022-01-16 45.80 10.56 66.05 76.97 65.95 76.87 204.61 215.53 66.61 77.53 70.88 81.80 64.81 75.73
2022-01-17 45.79 10.57 66.21 77.06 66.11 76.96 204.78 215.63 66.77 77.62 71.05 81.89 64.97 75.82
2022-01-18 45.79 10.57 66.37 77.15 66.28 77.06 204.94 215.72 66.93 77.71 71.21 81.99 65.13 75.91
2022-01-19 45.78 10.57 66.53 77.25 66.43 77.15 205.10 215.81 67.09 77.81 71.36 82.08 65.29 76.01
2022-01-20 45.78 10.57 66.68 77.34 66.58 77.24 205.25 215.91 67.24 77.90 71.52 82.18 65.44 76.10
2022-01-21 45.77 10.58 66.83 77.44 66.73 77.34 205.40 216.00 67.39 78.00 71.67 82.27 65.59 76.19
2022-01-22 45.77 10.58 66.98 77.53 66.88 77.43 205.54 216.10 67.54 78.09 71.81 82.37 65.74 76.29
2022-01-23 45.77 10.58 67.12 77.63 67.02 77.53 205.69 216.19 67.68 78.19 71.96 82.46 65.88 76.38
2022-01-24 45.76 10.59 67.26 77.72 67.16 77.62 205.83 216.29 67.82 78.28 72.09 82.56 66.02 76.48
2022-01-25 45.76 10.59 67.40 77.82 67.30 77.72 205.96 216.38 67.96 78.38 72.23 82.65 66.15 76.58
2022-01-26 45.76 10.60 67.53 77.91 67.43 77.82 206.10 216.48 68.09 78.48 72.37 82.75 66.29 76.67
2022-01-27 45.76 10.60 67.66 78.01 67.56 77.91 206.23 216.58 68.22 78.57 72.50 82.85 66.42 76.77
2022-01-28 45.76 10.60 67.79 78.11 67.69 78.01 206.36 216.68 68.35 78.67 72.62 82.95 66.55 76.87
2022-01-29 45.76 10.61 67.91 78.21 67.82 78.11 206.48 216.78 68.48 78.77 72.75 83.05 66.67 76.97
2022-01-30 45.76 10.61 68.04 78.31 67.94 78.21 206.60 216.88 68.60 78.87 72.87 83.15 66.80 77.07
2022-01-31 45.76 10.62 68.16 78.41 68.06 78.31 206.73 216.98 68.72 78.97 72.99 83.25 66.92 77.17
2022-02-01 45.76 10.62 68.28 78.51 68.18 78.42 206.84 217.08 68.84 79.08 73.11 83.35 67.04 77.27
2022-02-02 45.77 10.63 68.40 78.62 68.30 78.52 206.96 217.18 68.96 79.18 73.23 83.45 67.15 77.38
2022-02-03 45.77 10.63 68.51 78.72 68.41 78.62 207.08 217.29 69.07 79.28 73.35 83.56 67.27 77.48
2022-02-04 45.77 10.64 68.62 78.83 68.53 78.73 207.19 217.39 69.18 79.39 73.46 83.66 67.38 77.59
2022-02-05 45.78 10.64 68.73 78.93 68.64 78.84 207.30 217.50 69.30 79.50 73.57 83.77 67.49 77.69
2022-02-06 45.78 10.65 68.84 79.04 68.75 78.95 207.41 217.61 69.40 79.60 73.68 83.88 67.60 77.80
2022-02-07 45.79 10.65 68.95 79.15 68.85 79.06 207.52 217.72 69.51 79.71 73.79 83.99 67.71 77.91
2022-02-08 45.79 10.66 69.06 79.26 68.96 79.17 207.62 217.83 69.62 79.83 73.89 84.10 67.82 78.02
2022-02-09 45.80 10.67 69.60 78.94 69.50 78.84 208.16 217.51 70.16 79.50 74.43 83.78 68.36 77.70
2022-02-10 45.80 10.67 70.33 78.43 70.23 78.33 208.89 216.99 70.89 78.99 75.16 83.26 69.09 77.19
2022-02-11 45.81 10.68 71.06 77.91 70.96 77.82 209.62 216.48 71.62 78.48 75.89 82.75 69.82 76.67 [ ... Additional output not shown ... ]
Credits
The MTVT was developed by Michael S. P. Kelley, University of Maryland.