APT Export Files

APT allows export of several files that may be useful to users for separate analysis tasks.

On this page

See also: JWST Astronomers Proposal Tool Overview

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

APT allows the user to output a number of ancillary files that may be useful for developing certain offline tools or supporting other activities. Figure 1 shows how to locate the Export options and the files that are available.  

Some of these export options duplicate functionality from elsewhere in APT, but it may be convenient to access them here. Examples include creating a PDF file of the proposal in various formats or creating Target Confirmation Charts.  Other options, such as the times file, pointing file, and Smart Accounting visit sequences files, are unique to the Export menu and provide information that may be useful for other offline tasks specific to a given user.

This article does not try to outline every option, but rather concentrates on the options most likely to be of interest to general users, with the most useful files described first. 

Figure 1.  Finding Export options in APT

To find the list of export options, use the APT File pull-down menu (left) and select Export. This brings up a separate pop up menu (shown on the right) where various options can be chosen. In this example, pointing file has been selected. By default, only one entry can be selected at a time, but note the" cmd-click" option for selecting multiple entries. Selecting OK will create files of the selected item(s), defaulting to your computer's desktop unless stated otherwise.

pointing file

The pointing file is an ASCII file containing detailed information about the pointing positions and offsets of the observations and visits in a proposal, including dithers. Figure 2 shows a small section of an example file, while Figure 3 provides a glossary with brief explanations of the column headings in this file. The pointing file is also exportable in machine parsable JSON format.

Figure 2.   APT pointing file example

Depending on the size and structure of your proposal, the pointing file can get quite large.

Figure 3.   Glossary information for the APT pointing file

For more information on the the coordinate systems referred to above, please see JWST Instrument Ideal Coordinate SystemsAlso note that there is an option in the APT Preferences (in the JWST tab) called High precision pointings report that increases the number of decimal places in the output.

times file

The times file shows a detailed breakdown of each visit in your proposal. It may be useful for providing insight into the overheads being charged based on the options selected for each visit. It may also help users understand items that go into defining the various times, such as "Photon Collection" time, "Exposure Duration," etc. Figure 4 shows an excerpt from a times file, and Figure 5 shows the meanings of the headings for the times file. For more information on overheads, see JWST Observing Overheads Summary. Like the pointing file, the times file is also exportable in JSON format.

Figure 4.   APT times file example

The times file shows detailed breakdowns of the time charges for various activities as well as roll ups at the exposure and visit levels.

Figure 5.   The Glossary for APT times file

The meanings of the headings on both the Exposure Specification and Visit  levels are shown.

Smart Accounting visit sequences file

The Smart Accounting visit sequences file was added to the Export menu to provide more insight into what the Smart Accounting algorithm is assuming when generating the revised accounting of overheads for a proposal. Figure 6 shows an example output file. Smart Accounting must be run prior to creating this file.

Figure 6.   Example Smart Accounting visit sequences file

Comparing the "Smart Accounting Slew" column entries to those in the "APT Slew" column, a user can see where Smart Accounting was able to reduce assumed overheads. In this example, Smart Accounting was able to reduce the overheads on Sequence 1 by 6,461 sec while no savings were garnered for the short Sequence 2.

MSA-related files

There are 2 NIRSpec MSA-related files that can be exported: the MSA Target Info file and the MSA Conflicts file.

The MSA conflicts file is documented in MSA Shutter Operability.  

The MSA Target Info file provides machine- and human-readable ASCII output data for scheduled MSA targets. This file may be useful as a reference, or used for developing summary or assessment tools for observations. The tabulated data may be useful for any number of analysis or assessment tasks. As one example, target centering information in a given shutter is one of the tabulated values; results for an object observed in 2 or more configurations can be compared to see whether the achieved fluxes are consistent with planned target centering. The linked article above contains a full description of the file and its contents.

Visit-related files

There are 2 visit-related files in the Export menu.

The Visit Positions/Coverage to MAST option will send the pointing information for one or more selected visits in the proposal to the MAST Discovery Portal where they can be visualized against a variety of image backgrounds and compared with previous observations for many missions. A video tutorial is available that uses an HST example but the video has details on how the interface works for both HST and JWST position inputs. (Note: in addition to showing the Export interface, this 7-minute video provides a good example of working within the MAST Portal itself.) Users may find this to be a convenient way to check for potential duplications of their proposed observations prior to submission, or to see what other data may exist for a given target to be observed.

 How to use the MAST Portal from APT

The Visit Coverage file has heritage back the the HST "Exposure Positions/Coverage to file" option, but in the JWST implementation only primary position information is created (there is no information for parallels). Aperture position information for the selected visits is output in an ASCII CSV file; with effort on a users' part, this information could be utilized with SAOimage DS9 or other display programs outside of APT to show the apertures on relevant imagery.

xml file

It has been reported that some email programs do not allow the standard APT output files in the .aptx format to be included as attachments. One workaround for this is to create your proposal as an XML file. The user on the other end can then use the APT Import option to read in the XML file.  Anecdotally, we have heard of users who found it useful to parse specific information of interest out of the XML proposal files, especially for some large proposals.

Diagnostic Summary file

The Diagnostic Summary selection creates an ASCII text file with a roll up of any and all error and warning messages within the current proposal. This is simply a convenience file for user reference or for making a printed version of your proposal's diagnostics.

Latest updates

  • Slew times updated for APT 2023.5 (release date: Aug. 24, 2023)
Originally published