USING THE TEXT PROPOSAL FILE

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 Proposal File".

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 exposure sequences).

• 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 interruption.

• 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 delimiter.
• 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 delimiters.
• 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 list.
• The syntax for Proper Motion has changed to allow for multiple allowed units.

• 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 STScI.

• 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 visits).
• 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).

• 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.