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

GTVT article: JWST General Target Visibility Tool Help
See also: JWST Position Angles, Ranges, and OffsetsSolar System Special Requirements
See also: 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 assumed pre-launch JWST orbital parameters.

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., 1992 QB1).  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 objects (NEOs). 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 MTVT comes packaged with the GTVT as of January 1, 2018. The user is referred to the "Installation and usage" section on the JWST General Target Visibility Tool Help page for instructions on how to install (or update if an older version of GTVT was installed) GTVT/MTVT.  Note that the assumed orbital ephemeris and time period of the default calculation was updated in mid-2018 to accommodate the revised launch assumption of March 2021.

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 in a conda environment with the following command:

conda install astroquery

Alternatively, if you are familiar with "pip", you can install the package 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".

Note that the "--v3pa" optional argument in MTVT is identical to the "--pa" optional argument in GTVT. 

$ 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]
                 desg [desg ...]

positional arguments:
  desg                  Moving target designation.

optional arguments:
  -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 2018-01-01.
  
  --end_date END_DATE   End date for visibility search in yyyy-mm-dd format.
                        Latest available is 2021-12-31.


MTVT command line examples

The user is referred to the "GTVT command line examples" section of the JWST General Target Visibility Tool Help page 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."

Evaluating planet visibility

An example command for running 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 either 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 MTVT for a minor body using its number and the "--smallbody" optional argument is shown below. This purpose of this optional argument is to remove ambiguity between low-numbered minor bodies and major bodies. The below example will return information on the asteroid 4 Vesta; without the "--smallbody" optional argument, the MTVT would return infromation on Mars.

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 MTVT for a comet using its name shown below.

jwst_mtvt Encke

An example command for running 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 above commands 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  Primary Desig  >MATCH NAME<
    --------  --------  -------------  -------------------------
       9134             4822 P-L        Encke
     900034     1786    2P              Encke
     900035     1796    2P              Encke
     900036     1805    2P              Encke
     900037     1819    2P              Encke
     900038     1822    2P              Encke
     900039     1825    2P              Encke
     [ ... additional records not shown ... ]
     900088     1990    2P              Encke
     900089     1994    2P              Encke
     900090     1995    2P              Encke
     900091     1998    2P              Encke
     900092     2004    2P              Encke
     900093     2015    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 900093

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.

Figure 1. Default 6-panel MTVT output plot

Allowable position angles are shown on the y-axis in degrees plotted against date on the x-axis. The allowable position angles for each date can be found in the ASCII output table. In general, the visibility windows for solar system objects along the ecliptic will be separated by position angles of ~180°; see the Moving Target Field of Regard page for a diagram of the JWST focal plane orientation for observations along the ecliptic. For a more distant, slower-moving target like the KBO 47171 Lempo, the range of allowable position angles will be very small. Objects closer to JWST will have a larger range of allowable position angles.
Figure 2. Zoom in on a MIRI visibility window

The Zoom tool (magnifying glass icon in the lower left corner of the plot window) can be used to zoom in on visibility windows of interest in individual plots. In the image above, the Zoom tool was used to focus on one particular visibility window for MIRI, showing the allowable position angles in more detail.

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 but 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
 
Using Equatorial Coordinates

       Target

Checked interval [2018-01-01, 2021-12-31]
|           Window [days]                 |    Normal V3 PA [deg]    |            RA             |            Dec            |
   Start           End         Duration         Start         End        Start          End          Start          End     
 2018-01-01      2018-02-01        31.90      67.67509      72.04345      37.01916      36.98653       6.93678       7.07620 
 2018-07-30      2018-09-20        52.00     252.02545     259.92882      41.67917      41.47575       8.68297       8.44445 
 2018-12-16      2019-02-03        49.08      64.86793      72.54123      39.45384      39.17978       7.86610       7.99322 
 2019-08-01      2019-09-23        53.00     252.59432     260.44129      43.88871      43.67978       9.55869       9.32632 
 2019-12-19      2020-02-06        49.00      65.77751      73.16926      41.64973      41.38678       8.77599       8.90424 
 2020-08-03      2020-09-24        52.00     253.30775     260.72663      46.11396      45.90641      10.41771      10.20009 
 2020-12-20      2021-02-08        50.00      66.48428      73.83054      43.86959      43.60062       9.67304       9.80034 
 2021-08-06      2021-09-27        52.00     254.04550     261.26677      48.34573      48.12252      11.25900      11.04993 
 2021-12-23      2021-12-31         7.10      67.48006      68.90828      45.96765      45.96765      10.54498      10.54498 


                                V3PA          NIRCam           NIRSpec         NIRISS           MIRI          FGS
   Date      RA     Dec      min    max      min    max       min    max     min    max      min    max      min    max
2018-01-01    37.02   6.94    61.98  73.37    61.95  73.35   199.46 210.86    61.41  72.80    66.99  78.39    60.73  72.12
2018-01-02    37.01   6.94    62.19  73.49    62.16  73.46   199.67 210.97    61.62  72.92    67.20  78.50    60.94  72.24
2018-01-03    37.00   6.94    62.39  73.60    62.36  73.57   199.88 211.09    61.82  73.03    67.41  78.61    61.14  72.35
2018-01-04    36.99   6.94    62.59  73.71    62.56  73.68   200.08 211.20    62.02  73.14    67.61  78.72    61.34  72.46
2018-01-05    36.99   6.94    62.79  73.82    62.76  73.79   200.27 211.31    62.22  73.25    67.80  78.84    61.54  72.57
2018-01-06    36.98   6.95    62.98  73.93    62.95  73.91   200.46 211.42    62.41  73.36    67.99  78.95    61.73  72.68
2018-01-07    36.97   6.95    63.16  74.04    63.14  74.02   200.65 211.53    62.59  73.47    68.18  79.06    61.91  72.79
2018-01-08    36.97   6.95    63.34  74.16    63.32  74.13   200.83 211.64    62.77  73.59    68.36  79.17    62.09  72.91
2018-01-09    36.96   6.95    63.52  74.27    63.49  74.24   201.01 211.76    62.95  73.70    68.54  79.28    62.27  73.02
2018-01-10    36.95   6.96    63.69  74.38    63.67  74.35   201.18 211.87    63.12  73.81    68.71  79.40    62.44  73.13
2018-01-11    36.95   6.96    63.86  74.49    63.84  74.47   201.35 211.98    63.29  73.92    68.88  79.51    62.61  73.24
2018-01-12    36.95   6.96    64.03  74.61    64.00  74.58   201.52 212.09    63.46  74.04    69.05  79.62    62.78  73.36
2018-01-13    36.94   6.97    64.19  74.72    64.17  74.69   201.68 212.21    63.62  74.15    69.21  79.73    62.94  73.47
2018-01-14    36.94   6.97    64.35  74.83    64.33  74.81   201.84 212.32    63.78  74.26    69.37  79.85    63.10  73.58
2018-01-15    36.94   6.97    64.51  74.95    64.48  74.92   202.00 212.44    63.94  74.38    69.52  79.96    63.26  73.70
2018-01-16    36.94   6.98    64.66  75.06    64.64  75.04   202.15 212.55    64.09  74.49    69.68  80.08    63.41  73.81
2018-01-17    36.93   6.98    64.81  75.18    64.79  75.15   202.30 212.67    64.24  74.61    69.83  80.19    63.56  73.93
2018-01-18    36.93   6.99    64.96  75.30    64.93  75.27   202.45 212.78    64.39  74.73    69.98  80.31    63.71  74.04
2018-01-19    36.93   6.99    65.11  75.41    65.08  75.39   202.59 212.90    64.54  74.84    70.12  80.43    63.86  74.16
2018-01-20    36.93   7.00    65.25  75.53    65.22  75.51   202.74 213.02    64.68  74.96    70.26  80.55    64.00  74.28
[ ... Additional output not shown ... ]



Credits

The MTVT was developed by Michael S. P. Kelley, University of Maryland.




Published

 

Latest updates
  •  
    Removed mention of callhorizons and added installation instructions for astroquery.

  •  
    Added notation regarding updated orbital ephemeris.