Tutorial on Creating Solar System Targets in APT

Four examples of creating a Solar System target in the JWST Astronomer's Proposal Tool (APT) are presented in this article.

On this page

See also: JWST Astronomers Proposal Tool Overview

You should first read how the JWST Astronomers Proposal Tool (APT) defines Solar System targets. Here we walk through 4 examples for creating a new Solar System target in APT:

  1. Defining a Level 1 "standard target" planet
  2. Defining a non-"standard" Level 2 satellite
  3. Defining a Level 3 feature
  4. Defining a Level 1 minor body

To learn how to download APT and start a JWST proposal, see Moving Target APT Instructions. After this tutorial you may want to read Tutorial on Creating Solar System Targets in APT and Tutorial on Visualizing Dithers of a Solar System Observation in APT.

The following examples are by no means exhaustive. If you have questions please contact the help desk.


Getting started creating a new Solar System target

To create new targets, select the Targets folder and click the New Solar System Target button. 

Figure 1. APT Solar System targets page

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

A new Solar System Targets folder will be created with an empty sub-folder, Unnamed Target. To create additional targets, you can click the New Solar System Target button either at the Targets level or the Solar System Targets level.

To define your first target, select the Unnamed Target folder. Inside you will see that there are three "levels" to defining a Solar System target.

  • Level 1 Type: Observation will track the center of a planet, comet, asteroid, etc. 
  • Level 2 Type: Observation will track a feature, satellite, ring, position angle, etc. of the Level 1 target. 
  • Level 3 Type: Observation will track a feature, satellite, ring, position angle, etc. of the Level 2 target.

See also APT Targets for a more general discussion. The following examples illustrate a subset of the Solar System targets that may be defined.


Example 1: Defining a Level 1 Standard Target planet

The simplest target to define is a Level 1 Standard Target.

Type the name of your target in Name in the Proposal, select Planet from the Keyword drop-down choices, and add a description. The keyword is for archiving purposes only. Note that if you choose Dwarf-Planet for Keyword but select Mars as the Level 1 target, the Keyword value remains unchanged, even though it is not an accurate description (making this mistake will not affect the evaluation of your proposal). Therefore, to properly define your target type, select a value among the three "level" parameters: for a simple observation of Jupiter, select Standard Target from the Level 1 Type drop-down choices. 

Figure 2. Keywords and Level 1 targets

Next, you will be taken to the screen shown in Figure 3. Scroll through the Standard Target drop-down choices and select Jupiter.
Figure 3. Choosing a standard target

Example 2: Defining a non-"standard" Level 2 satellite

If you are observing a satellite that is not listed among the "standard targets," you can define it. This can work at Level 2 or Level 3, but we will illustrate it at Level 2 by creating a new satellite for Jupiter. 

Create a new target sub-folder, select Satellite from the Keyword drop-down choices, and enter a name and description. As in the example above, select Jupiter as the Level 1 Standard Target. Then in the Level 2 drop-down choices, select Satellite.

Figure 4. Level 2 targets

You will be taken to the form shown in Figure 5 where you can enter the satellite's orbital parameters.
Figure 5. Defining a new Jovian satellite

Example 3: Defining a Level 3 feature

At Level 3, you can define a feature to track on a Level 2 target. In this example, we will define the location of a volcano on the surface of the Jovian satellite Io. 

Select Feature from the Keyword drop-down choices, Jupiter as the Level 1 Standard Target, and Io as the Level 2 Standard Target. Finally, select Planetographic from Level 3 to set the Level 3 target's coordinates to be in longitude and latitude relative to the Level 2 target. You can find the full list of coordinate frames in the article Solar System Targets Position Levels 2 and 3.

Figure 6. Level 3 features

You will be taken to the form shown in Figure 7, where you can define the volcano's longitude, latitude, etc.
Figure 7. Defining a volcano on Io as a Level 3 feature

Example 4: Defining a Level 1 minor body

Most minor bodies such as asteroids, comets, and KBOs are not considered standard targets and must be selected from either the Comet or Asteroid categories, the latter including outer Solar System minor planets. For example, to define the trans-Neptunian object Sedna, select Asteroid from the Level 1 drop-down choices. 

Figure 8. Defining a Level 1 asteroid

On the next form, shown in Figure 9, type "Sedna" into the Search box. Choose the object from the pop-up window and click OK.
Figure 9. Using the JPL Horizons search tool

Next, APT will retrieve the object's orbital elements from JPL Horizons. If you had previously entered any elements into this form, they will be overwritten unless you click Cancel.
Figure 10. Loading orbital elements

If you wish to edit the JPL Horizons elements (which is not recommended), uncheck the box indicated in Figure 11.
Figure 11. Updating orbital elements

Non-standard characters in minor body names

The Horizons Search tool is unable to parse certain special characters in the names of minor bodies. When this happens, APT will first produce a pop-up that says that the search did not return any results, then will produce a pop-up stating that APT is unable to contact the STScI server. The second pop-up is accompanied by the Search box being greyed out. In this situation the connection is not actually broken, and the workaround for this is to wait a few seconds for the Search box to become usable again or to click anywhere else in the tree editor.

Specific guidance on how to handle minor bodies with non-standard characters:

  • Accent marks: Avoid using accent marks on letters; simply type "a" for "á," for instance.
  • Acute accent/Hawaiian `okina: Replace this character with an apostrophe (single quotation mark on the keyboard) to avoid issues. Simply removing the character will result in the search returning no targets.
  • Periods: Names with periods will either result in the tool returning a very large list of results (not including the target being searched for) or a pop-up that the search did not return any results. The workaround for this is to supply the target's provisional designation or number instead of the name. Examples of minor bodies with periods in their names include:
    • 17602 Dr. G. (1995 SO1)
    • 2309 Mr. Spock (1971 QX1)
    • 12448 Mr. Tompkins (1996 XW18)
  • Other non-standard characters: Other unaccepted characters include exclamation points, pipes ( | ), and equal signs. The workaround is again to supply the target's provisional designation or number instead of the name. Examples of minor bodies with these characters in their names include:
    • 229762 Gǃkúnǁ'hòmdímà (2007 UK126), rendered in ASCII format as G!kun||'homdima
    • 469705 ǂKá̦gára (2005 EF298), rendered in ASCII format as |=Kagara

The following characters are accepted in the search box and do not cause issues: spaces, dashes, and apostrophes. Other situations that also do not cause issues: names with only capital letters and names with alternating lowercase and capital letters. Of course, there are many other special characters, but currently none of them are used in the ASCII formatted names of minor bodies and so are not discussed here.

Note: Names with 3 or more separate components (2 or more spaces) will result in only the first 2 components of the name being present in the NAIF Name and Name for the Archive boxes. This may lead to degeneracy when searching MAST for a minor body with a multi-component name. For example, the minor bodies 2823 van der Laan and 32893 van der Waals would both appear in MAST as "van der."


References

Download the Astronomer's Proposal Tool



Latest updates
  •  
    Added information about issues parsing some minor body names.

  •  
    Minor wording changes.


  • Fixed the link in the references section.
Originally published