USING THE TEXT PROPOSAL FILE
APT's text proposal file (.prop file) is a flat ascii text
representation of your HST Phase II Proposal. It can be exported from
APT to facilitate editing of large programs in cases when the APT GUI
editor is not efficient. Because of the inherent limitations of
this capability, we strongly recommend not using it in place of APT
GUI Editors unless your editing task truly warrants it.
Here are some questions and answers to help you decide whether the
text proposal file would be useful for you:
There are two scenarios where the text proposal file could be
The best way to discover proper text proposal syntax is to create a
small test proposal in the APT GUI and export it.
- Repetitive Change: You have already built a fairly large
program in APT by creating unique exposures and visits, and then used
the duplicate and multiple duplicate features in APT. Then, you
discover that you need to make a small change to a large number of
exposures (such as removing or adding an optional parameter). This
would be tedious to do in the APT GUI, but straightforward in the text
proposal file. Simply export your program to the text proposal format,
make your changes in an editor, and then import the text proposal back
into APT for reprocessing.
- Large Mosaic: You are building a large repetitive program
with many targets and visits in order to create a mosaic. Initially,
you would use APT to build a proposal that has one or two targets and
one of each of the unique visits. You would then run the Orbit Planner
and Visit Planner to make sure that the visits fill the right number
of orbits and schedule. Then export this small template proposal to
the text proposal file format, and use scripts or your favorite editor
to build your program into a larger version. Finally you would import
the resulting file back into APT for syntax checking and
processing. BUT, before doing this please consider if the new
Mosaic tool would meet your needs.
The text proposal syntax has been added to the Phase II Proposal
Instructions for reference. It is set apart in brown text. For an example look in
section 6.1 for the "Additional Rules and Conventions for the Text
One potentially confusing difference between the text proposal
structure and the APT proposal structure is the way exposure groups
are represented (e.g. parallels,patterns and non-interruptible
It is very similar to the RPS2 syntax that was used for Phase II
Proposal writing in Cycles 5-11. But that is not to say you can simply
import a Cycle 11 proposal. If you need to update a script that writes
out a .prop file please note the following major differences:
- Parallels: In APT if you want exposure 2 in parallel with
exposure 1 you have to click on "New Parallel" and then drag the two
exposures into the "Prime+Parallel Group" container. The first
exposure would be the primary and the second would be the parallel. If
you export this you will note that the syntax is an exposure level
special requirement on exposure 2: "PAR 2 WITH 1".
- Patterns: In APT if you want one or more exposures executed
in a canned pattern you have to click on "New Pattern", select a
Pattern specification and then drag the exposures into the Pattern
group. If you export this you will note that the syntax is an exposure
level special requirement of the form: PATTERN 1 2-3, which means that
pattern specification 1 is being used on exposures 2-3.
- Sequences: In APT you create a non-interruptible exposure
sequence by clicking on "New Sequence" and dragging the exposures into
the Sequence group. If you export this you will note that the syntax
is an exposure level special requirement of form: SEQ 1-2 NON-INT,
which means that exposures 1-2 must be obtained without
All necessary Phase II proposal information is retained when you export your
proposal. But for completeness please note the following things which will be not be retained:
- You must put a COMMA between optional parameters, target
descriptions, target position coordinates, and spectral elements (if
more than 1 is needed). A carriage return is no longer a valid
- You must put a SEMICOLON between special requirements. A carriage
return is no longer a valid delimiter.
- There is a new longer format for the PI and Co-I names.
- Only the shortest forms of special requirements will now be
accepted. For example, POSITION TARGET must now be POS TARG.
- Exposure times must be specified in seconds.
- Exposure lists may only be expressed as a range (e.g. use 1-3
instead of 1,2,3.) As before, visit lists can have comma
- The fixed target keyword "Flux" is now only used for specifying
the V magnitude. All other flux information is specified in the new
keyword called "Other_Fluxes".
- Secondary spectral elements (such as polarizers) must be specified second in the comma delimited
- The syntax for Proper Motion has changed to allow for multiple
The sub-exposure information contains the orbit numbers (usually
assigned by the Orbit Planner) and any actual durations (usually set
by using the auto-adjust function) that have been assigned. If you
have not run the Orbit Planner (in which case these values will be
blank), or if you are planning to move or copy individual exposure in
the text file, it is best to export without the sub-exposure
information. However, be aware that any sub-exposure information in
the proposal (such as for visits with completed processing) will be
lost on export.
- Phase I data: The APT file carries your Phase I as well as
Phase II data. But the text proposal file does not have any syntax for
retaining the Phase I data. This has little practical effect
(especially if you kept a copy of your original Phase I). Note that
your e-mail address will be lost from the file and you will be
prompted for your e-mail address at submission time.
- Past processing results: The Orbit Planner has a mechanism
for remembering the results of processing from session to session.
This memory will be lost when you export and then reimport the text
proposal file. So it will appear that no processing has ever been
done. (And any diagnostics generated during Orbit Planner processing
will go away until you processing is redone.)
- Submission data: The APT file carries information about
your past submissions, but not the text proposal file. So you will
notice that if you have previously submitted, things like submission
comments, justification of diagnostics, and e-mail address for
acknowledgement are gone. You will also be warned that the number of
the submission in the proposal does not match the number recorded at
- BUG: If you find that your edited .prop file will not re-import into
APT (with no information as to why), try this experiment: Export the .prop
file and try to re-import it into APT will no edits at all. If this does
not work you may well have non ascii characters in the text of the
original APT file. These characters don't cause APT grief unless it
is trying to import a .prop file. If you can't find the non ascii characters
please ask us for help.
- If you have processed a visit through the Orbit Planner prior to
export, there will be information in the sub-exposure keyword. Do NOT
edit the APT generated sub-exposure information. If you are copying
or moving individual exposures, you should delete the sub-exposure
keyword(s) first. If you are copying entire visits, you should delete
the sub-exposure keywords in the new visit if you will be making
changes such as adding or moving exposures. Note that you can export
the text file WITHOUT the sub-exposure information.
- For visit groups, you MUST explicitly include the current visit in
the visit list (e.g. if you want to GROUP visits 01, 02, and 03, then
use the special requirement GROUP 01-03 WITH 5D on one of the three
- Since APT requires consecutive numbering of exposures, the
following will happen on import if you have physically rearranged and
removed exposures during text file editing (and have not
renumbered). First the exposures will be put into APT in the order
that they are numbered. Then they will be renumbered so that the
numbering is consecutive. (All the references to other exposures are
updated.) For example if you rearrange and remove exposures in the
.prop file so that you have exposure numbers 3 (filter A) 7 (filter B)
5 (filter C), what you will actually get after import is: 1 (filter A)
2 (filter C) 3 (filter B).
There are two different classes of errors you will get in APT as a
result of importing a flawed text proposal:
- Repetitive Change: If you have already written a proposal
in APT and need to do a repetitive edit, simply click on
File/Export/Export Text proposal. This will prompt you for where you
would like to save your .prop file. (Whatever you type in will have
.prop appended to it.) Now make your edits in your favorite text
editor. When you are ready to import back into the APT please first
close (using File/Close) the old version of the proposal. You may get
confused if you have both the old and new versions open in APT at the
To import the .prop file back into APT click on File/Import/Import
Text proposal. See the section below for how to deal with errors found
in your .prop during import. If the import goes well you can reprocess
the proposal and File/Save to a new an improved .apt file.
- Large Mosaic: If you are going to build a large repetitive
proposal outside of APT, you can make your starting template in APT
from your Phase I proposal by opening it in APT and changing it to
Phase II. Then enter your Phase II ID number, add a visit (which can
be completed or left empty), and then click on File/Export/Export Text
proposal. (If you have already retrieved your proposal from STScI
using the Phase II ID given to you by your PC, then the Phase II ID
number will have already been filled in.) You can then write scripts
to craft your proposal using this template and then import using
File/Import/Import Text proposal. BUT, before doing this please consider if the new
Mosaic tool would meet your needs.
As with the previous example you will want to first save and close
your original version of the proposal before importing your generated
.prop file. And you will likely go through a few iterations to get rid
of syntax errors (see below).
- APT Error: The red X of an ordinary APT error will be
placed next to any entry that the importer could confidently pass
to APT. APT is then in charge of informing you (for example) that you
have two special requirements that are inconsistent (just as if you
had made the mistake using the APT Form Editor). If you are ready to
work in the APT Editor again you can simply correct the problem in
APT. If you have a wide spread problem you may wish to correct the
problem in your .prop file and reimport.
Note that in some cases you may have entered a value for something
that should not have a value or the field has a required value and you
have specified something different (the pattern specification fields
are an example). APT will report the error with a red X, but you will
not be able to fix it in APT because the APT Form Editor locks out
fields you should not be changing. You will have to fix this type of
problem in the .prop file and reimport.
- Importer Error: These are generated by the importer
when the file contains syntax errors (such as misspelled keywords,
missing required keywords and alphabetic characters where a number is
required) or other mistakes that cannot be represented in APT (such as
multiple exposures with the same number). The first instance of this
class of error will result in a pop up warning and all the targets,
visits, etc., will be empty. In order to figure out how to fix your
.prop file, click on the Diagnostics tool or the red X in the lower
right hand corner. If the error message itself seems cryptic, be sure
to look for what line number it says had the problem. Mostly likely
your error was on or just above that line.
Last modified: May 14, 2013.