Chapter 2 The Basics of Phase II Proposals

HST proposals are submitted using the Astronomer's Proposal Tool (APT), and in Phase II the details of the observations are prepared. This article describes the basics of preparing a Phase II program.

Expand/Collapse all...


On This Page

Format definitions

Boldface type indicates the name of an APT parameter or a value for a parameter.

(red star) Black text indicates an important note.

Magenta text indicates available but unsupported parameters (requires prior approval from STScI).

Red text indicates restricted parameters (for STScI use only).

Brown text indicates text file parameters.

Items in brackets - <value> - are required values.

Items in square brackets - [<value>] - are optional.

Introduction

The computer software used to schedule and execute HST observations can interpret the proposal information only if it is in the proper format. Therefore, proposals must be filled out accurately, completely, and in strict accordance with the instructions in this document. Observers now have the capability and responsibility, with the help of their Program Coordinator (PC) and/or Contact Scientist (CS) for creating and submitting proposals that are not only syntactically correct but also feasible and schedulable. The Astronomer’s Proposal Tool (APT) will help you achieve this.

Note: Starting with Cycle 27, proposers are now required to explicitly list and justify the use of all special requirements in the Phase I proposal. Special requirements not justified in the Phase I proposal may not be used in the Phase II proposal. See the Special Requirements section of HST Preparation of the PDF Attachment.

Astronomer's Proposal Tool (APT)

With APT you can prepare your Phase II program on your computer and then submit it electronically to STScI. You will use a copy of your Phase I proposal (marked up in XML), which contains all the information from your Phase I submission. If you haven’t done so already, please consult the APT web page for detailed instructions on how to install and use APT on your computer. Observers without access to a suitable computer platform to run APT for Phase II should contact their PC.

Entering Information: The APT Graphical User Interface (GUI) versus the Text Proposal File

In the previous proposal entry system, RPS2, you could enter and edit information as text (usually in the form <keyword>=<value>) using a template and your favorite text editor. Also, you could use the Proposal Editor (PED), a graphical editor in RPS2 designed for editing your Phase II program.

In APT you can enter proposal information by using either the APT Form/Spreadsheet Editors via a GUI or a Text Proposal File that employs a "simplified" RPS2 syntax. This text file has been developed for APT  as an alternative method for editing proposals outside of the APT GUI; you use a flat ASCII file format that is similar to the RPS2.prop file that was used in HST cycles 5-11. Small changes to the original RPS2 format were necessary to accommodate enhancements that came with APT, and some of the syntax has been made stricter in order to make reading of the file more robust. You create this file in APT by exporting your proposal into a text proposal file format (for details please see the APT web page).

Text Proposal File

Text Proposal File

Basic Syntax Rules

Users (particularly RPS2 old-timers) should be aware that some changes to the original RPS2 format were necessary to accommodate enhancements that came with APT; also, some of the syntax has been made stricter in order to make parsing of the file more robust (e.g., for special requirements).

Here are a few basic rules that must be followed:

  • Commas or semicolons must be used to delimit items in a list (see specific rules in the following bullets). New lines for each item will not be sufficient delimiters.
  • Semicolons must be used to delimit Special Requirements items.
  • Commas must be used to delimit items in all other lists including target descriptions, target position, fluxes, optional parameters, and spectral elements.
  • Only the shortest forms of the special requirements will be accepted (e.g., POSition TARGet must be POS TARG). For more information on special requirements see Chapter 6: Special Requirements.
  • Exposure lists in Special Requirements must be specified as a single range. No commas are allowed in an exposure list (e.g., use 1-5 instead of 1,2,3-5). As before, visit lists can have comma delimiters.
  • The Time_Per_Exposure must be specified in seconds.
  • Dates should be in the form 01-Jan-2005:00:00:00 (as an example) with the hours: minutes: seconds being optional. Other formats will not be supported except for JD, which is used for ZERO-PHASE.

Sample Text Proposal File Template

Your Text Proposal File should include the following and in the order given. Optional blocks are in square brackets ([]). The use of colons is required in the form given. Note that at least one of the three target types (Fixed, Solar System, or Generic) must be present unless the proposal contains only internal or predefined pointings. You can make your own 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, and then export to a text proposal file (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).

Proposal_Information
Title:
Proposal_ID:
Proposal_Category:
Cycle:
[Avail_Ok:]
[STScI_Edit_Number:]
Investigators
PI_Honorific:
PI_First_Name:
PI_Middle_Initial:
PI_Last_Name:
PI_Institution:
[CoI_Name:
CoI_Honorific:
CoI_Middle_Initial:
CoI_First_Name:
CoI_Last_Name:
CoI_Institution:

[Contact:]]

Abstract
Questions
Observing_Description:
[Fixed_Targets
Target_Number:
Target_Name:
[Alternate_Names:]
Description:
Position:
Equinox:J2000
Coordinate_Source:
[RV_or_Z:]

[RA_PM:]

[RA_PM_Units:]
[Dec_PM:]
[Dec_PM_Units:]
[Epoch:]
[Annual_Parallax:]
Flux:
[Other_Fluxes:]
[Comments:]]
[Solar_System_Targets
Target_Number:
Target_Name:
Description:
Level_1:
[Level_2:]

[Level_3:]

[Window:]
[Ephem_Uncert:]
[Acq_Uncert:]
Flux:
[Other_Fluxes:]

[Comments:]]

[Generic_Targets
Target_Number:
Target_Name:
Description:
Criteria:
Flux:
[Other_Fluxes:]
[Comments:]]
[Pattern_Data
Pattern_Number:
Primary_Pattern:
Pattern_Type:
Pattern_Purpose:
Number_Of_Points:
Point_Spacing:
Line_Spacing:
Coordinate_Frame:
Pattern_Orient:
Angle_Between_Sides:
Center_Pattern:
[Secondary_Pattern:
Pattern_Type:
Pattern_Purpose:
Number_Of_Points:
Point_Spacing:
Line_Spacing:
Coordinate_Frame:
Pattern_Orient:
Angle_Between_Sides:
Center_Pattern:]

[Pattern_Comments:]]

Visits
Visit_Number:
[Visit_Priority:]
[Visit_Requirements:]
[On_Hold_Comments:]
[Visit_Comments:]
Exposure_Number:
[Exposure_Label:]
Target_Name:

Config:

Opmode:
Aperture:
Sp_Element:

[Wavelength:]

[Optional_Parameters:]
Number_of_Iterations:
Time_Per_Exposure:
[Special_Requirements:]
[Sub_Exposures:]

[Comments:]

Using the APT GUI

In most of the fields in the APT graphical interface, you choose a keyword or parameter <value> in a list from a pull-down menu, or check a box. In a few other fields (e.g., Other Fluxes, Observing Windows and Criteria in the Targets forms) you enter free text in the field using the formats specified in this document. Required items are marked with a red “x” if you haven’t selected or entered a <value>. Also, for many of the keywords, a tooltips message will appear when you place your pointer on the keyword: <value> area.

Using the Text Proposal File

When creating or editing large repetitive proposals, editing with APT’s graphical interface can be inefficient and prone to error. We present two examples where you may want to use a text proposal file.

  1. 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, you would 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. You would then import the resulting file back into APT for checking and processing.
  2. 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 File format, make your changes in an editor, and then import the Text Proposal File back into APT for new processing.

Table 2.1 summarizes some of the differences between the APT GUI and the Text Proposal File.

Table 2.1: Comparison of APT GUI and the Text Proposal File


Data Entry MethodSyntaxHelp Features and Error Checking
APT

Use the Form or Spreadsheet Editors via the APT User Interface

For most of the fields (exceptions noted below), choose a keyword <value> from a pull-down list, or check a checkbox, or enter a text <value> in the field provided.

1) Required data marked with a red x

2) Tooltips (e.g., a message noting a required item and its format) provided during data entry

3) Context-sensitive help available

Text Proposal FileAfter exporting your proposal from APT to the text file, edit it using your favorite editor.

Enter free text in the file in the form <keyword> = <value>. You must conform to the proper syntax described in this document.

None while editing. After editing your proposal, you must import it back into APT (see the APT web page for instructions). Once you have imported your program back into APT you can run the diagnostics tool.

APT Tools

APT also provides tools to help you plan your observations, such as an Aladin based visualization tool, an Orbit Planner and a Visit Planner (see the Using APT web page). If you have any problems using APT, or have any questions about your proposal, please feel free to contact your assigned Program Coordinator (PC) and/or Contact Scientist (CS). Programs without an assigned CS may also contact the STScI HST Help Desk (web: https://hsthelp.stsci.edu; email: help@stsci.edu) for help with APT. We encourage use of the new website where you can submit questions directly to the appropriate team of experts.

Submitting Your Program

After you submit your Phase II program, the APT system will give you an automatic electronic acknowledgment. This should be followed in a few days by an acknowledgment from your PC. If, at the time of submission, the proposal contains errors, the APT submission system will give a warning, but will allow the proposal to be submitted. However, the proposal will be flagged, and your PC will contact you within a few days to discuss how to proceed.

(red star) The resolution of errors in the Phase II Program is the responsibility of the Principal Investigator. The fact that APT may allow you to submit a program that contains errors does not mean that your program can or will be scheduled.
We strive to make APT a useful aid for preparing and checking your Phase II program, but it is nevertheless imperfect. On rare occasions syntax errors are not detected. Also, APT does not check for guide stars. If there are guide star issues your PC will contact you with options.

What to Submit

Observers must submit their Phase II proposal to STScI by the Cycle 32 Phase II deadline. It should contain the following:

  • Updated Proposal Information: This section includes the title, the abstract, a Phase II ID, a proposal description, PI and CoI information. Please note that some general information is very useful for a thorough and helpful technical review of your proposal. You may wish to include parts of your Phase I science discussion, but please note that all the Phase II information you provide will be freely available via the Web.
  • Target Information: The information for one or more of the Fixed, Solar System, or Generic Targets must be completed. If necessary, proper motion and parallax information should be supplied for fixed targets. Detailed instructions for filling out the target data, as well as the proper motion and parallax information, are provided in sections 3.1 Fixed Targets, 3.3 Generic Targets, and 3.2 Solar System Targets.
  • Visit, Exposure Group, and Exposure Specifications: These specifications include orientation information, scheduling requirements, SI information, exposure special requirements and so on. Required items will be clearly noted as you complete the specifications. General instructions for completing this section are provided in Chapter 4: Visits, Exposures, and Exposure Groups.

General Instructions

When you first bring up APT, you will have to convert the information in your Phase I proposal, which is an XML file, into a Phase II program format using the “Phase I->Phase II” conversion button on the APT User Interface.

Note the following general instructions and conventions when entering your Phase II information:

  • After converting your Phase I Proposal into Phase II information, please verify that all the general information is correct and readable.
  • Entries in text must precisely conform to the formats specified in this document. If you have decided to use the Text Proposal File, the order of the entries must be correct as well (see Text Proposal File).
  • Proposal data text may contain only standard ASCII characters. All other symbols must be spelled out. Greek letters must be spelled out (e.g., BETA-LYR, H-ALPHA). The degree sign should be replaced with “D” (e.g., BD+16D516). Subscripts and superscripts are not allowed.
  • When providing a Target “Description” please use the target keywords and syntax presented in Target Description tables (for Fixed and Solar System targets).

If you are unable to use the APT software, please contact your PC (listed in your notification letter) to make other arrangements.

Proposal Information [Proposal_Information]

This block contains basic information about the proposal including the Title, Abstract, Category, and Cycle. After converting your proposal from Phase I to Phase II, your Phase II program will have the program information filled out based on your Phase I submission.

Proposal Title

The title from your Phase I submission will be used.

Abstract

The abstract from your Phase I submission will be used. Please check this since you may need to update this text based on your final TAC allocation.

If a Phase II submission is not based on a Phase I proposal, please fill in missing information.

Phase II ID

This ID will be provided to you by your Program Coordinator.

STScI Edit Number

This field holds a counter for an operational version number of the proposal and cannot be edited by the user. If you are connected to the Internet, the version number in your proposal file is compared to the one in the STScI proposal database when a proposal is opened or submitted. In either case, if your file’s version number is less than the database’s number for that proposal, you will get a pop up warning that a more recent version is available (via APT’s Retrieve from STScI). This prevents you from doing an update with an old copy of the proposal, or making edits to a version that does not include changes your PC has made to the proposal. The STScI software increments this number whenever the Phase II file is edited by STScI staff.

Proposal Category

For those Phase II submissions that are not based on a Phase I proposal, the Category should be selected from one of the following:

GO (General Observer)
GO/DD (Director’s Discretionary time)

SNAP (snapshot proposals)

For restricted parameters

The following proposal categories may also be used internally to STScI, but only as Restricted:

CAL/STIS, CAL/COS, CAL/WFC3, CAL/AST, CAL/OS, CAL/OTA, ENG/STIS, ENG/FGS, ENG/COS, ENG/WFC3, ENG/AST, ENG/SC, ENG/OTA, NASA, CAL/ACS, ENG/ACS

New proposal types can be created, but only if needed.

A Category of SNAP is used for “snapshot” programs. By their nature these programs take advantage of otherwise-unused blocks of telescope time for relatively short exposures. SNAP exposures therefore must carry as few restrictions as possible. In particular, Special Requirements should not ordinarily be used with SNAP programs (consult with your Program Coordinator if you feel you need to do so). Some special policies apply to SNAP programs: in particular, STScI will not repeat failed SNAP exposures.

Pure Parallels

For pure parallel proposals, check the “Parallel” checkbox next to the Proposal Category in the Proposal Information form. Please note that SNAP/PAR is not a valid proposal type.

Proposal Cycle

Unless you have been told otherwise, the Cycle should be 32. Multiple values of Cycle are not permitted.

Availability

You must choose supported. If the observing modes normally offered by STScI to GOs do not meet the needs of your program, please contact your Program Coordinator.

For available but unsupported parameters

The Avail_Ok keyword is intended for GOs who want to use “Available but Unsupported” engineering options, which are described throughout this document. The only legal value for Avail_Ok is YES. GOs may use Available but Unsupported options only if this keyword has been enabled by an Instrument Scientist (contact your PC or your Contact Scientist if your program has one). You will be asked to provide a scientific justification of your request. The instrument scientist will need to determine that the use of an Available but Unsupported mode is justified. If the Avail_Ok keyword is enabled, APT will perform full error checking on exposures with Available but Unsupported options in GO proposals. Otherwise APT will report a syntax error and any other problems with the exposure will not be detected.

Proposal types beginning with CAL or ENG may use any engineering option and are not required to supply the Avail_Ok keyword.

Target of Opportunity Number Of Activations

Enter the total number of ToO activations requested for each type of Target of Opportunity visit in the program. The four separate parameters correspond to the Target of Opportunity Response Times specified in the ToO visit level special requirements: 

Proposal Description

Proposal Text Sections

These four sections are needed for STScI to execute your program properly. Not all questions will need to be answered by every observer, and note that the answers to these questions will be made public. As with the Abstract, please review this text to make certain the information is correct.

Description of Observations [Observing_Description]

Provide a detailed description of your observing plans. Text from your Phase I proposal will need updating based on your final TAC allocation and on details to be worked out in Phase II.

Investigators

This section contains the names of the Principal Investigator (PI), all Co-Investigators[1] (CoI), and their institute affiliations. This information comes from your Phase I proposal submission.

Phase II Contact

If a Co-Investigator is also to be a contact for a program, then the Phase II Contact keyword box should be checked. More than one Co-Investigator may be designated as a Contact. The Contact(s) will receive the same (non-budgetary) automated e-mails for the program as the PI.

If any of the Investigators have changed addresses between the Phase I and Phase II submissions (or any time after the Phase I submission), please contact your Program Coordinator with the updated address, or by logging on to MyST at: https://proper.stsci.edu/proper/authentication/auth. You cannot use the Phase II submission to implement address changes.

For Phase II submissions that are not based on a Phase I proposal, please fill in the information accordingly.

Target Information [Fixed_Targets, Solar_System_Targets, Generic_Targets]

Sections 3.1 Fixed Targets, 3.3 Generic Targets, and 3.2 Solar System Targets describe how to fill out the Target Lists.

Visit Information [Visits]

The Chapter 4: Visits, Exposures, and Exposure Groups article describes how to fill out the Visit and Exposure Specifications. Instructions for submitting parallel observations are given in Chapter 5: Parallel Science Exposures, and the detailed, instrument-specific parameters are described in the ACS, COS, FGS, STIS, and WFC3 chapters.

Examples and General Advice

Phase constraints for periodic observations

Phase constraints in a Phase II program are applicable when the observations are to follow a periodic event, such as an exoplanet transit or a regularly-variable object. The most important aspect to have in mind is that the phase range on an exposure sets a window over which that exposure may start.

In particular for exoplanet transit observations, it is important to set the phase range in a way that allows for an adequate out-of-transit baseline that includes one or more exposures before the ingress of the exoplanet. For example, setting a PHASE 0.95 TO 0.05 for a transit with ingress happening at phase 0.98 may lead to missing the pre-transit time, since the exposure may be scheduled with a start time after the ingress. Consider instead PHASE 0.94 TO 0.97, since it would guarantee that the exposure starts before the ingress phase 0.98.

More details about the phase constraints of periodic observations can be found in Sections 6.2.3 Timing Visit-level Special Requirements and 6.3.2 Timing Exposure-level Special Requirements.

Acquisitions and Pointings

Getting HST located and oriented properly lies at the heart of successful observations, especially when a small aperture is being used, and there are a number of ways to do that. The remarks here apply specifically to fixed targets, and mostly apply to the use of small apertures, although many of them can be applied to moving targets as well. For more information, see Section 3.1 Target Position Type.

First, you have to acquire an object successfully that is at or near the position at which the science observation will be made. The object to be acquired should meet these conditions:

  1. It should be a point source or nearly enough to point-like that the centering algorithms can determine a precise centroid.
  2. The object’s coordinates must be both precise and accurate and any proper motion must be known. This requirement boils down to the need for the object to fall within the search region at the time of the acquisition. For this to happen the coordinates must also be consistent with the Guide Star Catalog or they must fall within another system that can be related to the GSC. This is why the source of the acquired object’s coordinates are required.
  3. The object must be neither too bright nor too faint for the instrument mode used. These conditions are described in the various Instrument Handbooks.

The coordinates for the acquired object can be specified in several ways:

Second, once the acquisition has been made, the telescope must be repositioned to the precise point desired. This step is unnecessary, of course, if the object acquired in the first instance is the object to be observed. Repositioning can be implicit or explicit.

An offset is implicit when a target such as “XX-OFFSET” is acquired with some ACQ mode, and then “XX” is observed via a science exposure. This often leads to confusion because no specific motion of the telescope has been provided, but that motion is implied by specifying the separate targets with different coordinates. “XX-OFFSET” is specified for the acquisition because it is bright enough and point-like enough to be acquired successfully, but the coordinates specified by “XX” are what is to be observed.

An offset is explicit when you use a Special Requirement such as POS TARG to move the telescope away from the position acquired. In this scheme, the position specified in the acquisition is placed at the fiducial point for the aperture requested (in general the geometric center of the aperture). The POS TARG then moves the telescope relative to that nominal position. Thus POS TARGs are not cumulative, and always refer back to the original acquired position.

Examples

People who are looking for examples of APT files are encouraged to go to:

http://archive.stsci.edu/hst/abstract.html

and do a search for a selection of proposals from the most recent cycle. For any program that appears as though it could serve as a useful example, the APT file can be obtained by typing the proposal ID number into the search form at:

https://www.stsci.edu/hst/observing/program-information

Additionally, several examples of ACS dither patterns using POS TARGs which may be used in an APT proposal can be found on the ACS Web site at:

http://www.stsci.edu/hst/instrumentation/acs

Common Problems

Incorrect Proposal Format

When you are entering text in a field the formats described in this document must be followed exactly, since the information in the forms is interpreted by computer software. Some items that warrant repetition are:

  • Visit numbers must be unique.
  • Target names must be spelled exactly the same throughout the proposal.
  • The format for target positions must be followed to the letter. For more information on coordinates, see Section 3.1 Target Coordinates.
  • The format for Optional Parameters and Special Requirements must be followed to the letter.
  • Observations which cannot be defined using the syntax in these Instructions may be described in Comments fields, but such comments should be used very sparingly, if at all, and their use may impede execution of a program.

Imprecise Target Positions

See the discussion of required position accuracies in the table of Required Coordinate Accuracies. The requirements are much more stringent than is typically the case for ground-based observations.

Lack of Acquisition Exposures with Small Apertures

When exposures are requested in very small apertures or fields of view, a separate acquisition exposure is generally required. Please consult the Instrument Handbooks for the instrument you are using.

Consideration of Limited Resources

Starting with Cycle 26, proposers are now required to explicitly list and justify the use of all special requirements in the Phase I proposal. Special requirements not justified in the Phase I proposal may not be used in the Phase II proposal.

Proposers should be aware that several of the Special Requirements  impose serious constraints on the scheduling system because they require the use of limited resources; for example, RT ANALYSIS requires real-time use of the Tracking and Data Relay Satellite System (TDRSS) that is only available some of the time. Hence these Special Requirements should be requested only if they are absolutely necessary to achieve the scientific goals of a project. It is quite possible that some proposals will be impossible to schedule because of their resource requirements, rather than a lack of scientific merit. The limited-resource Special Requirements can force the planning system to schedule the observations at a less than optimal time. The use of limited-resource Special Requirements by many observers can reduce the overall efficiency with which the planning system can schedule the science program. For these reasons, these Special Requirements should only be used when necessary to achieve the science objectives of the program. The STScI will review the necessity for the Special Requirements and in some cases may suggest removing them, or using alternate methods to obtain the same goal.

The Table 2.2 summarizes the Special Requirements that involve seriously limited resources.

The need for many of these Special Requirements must be justified in the Proposal Description. Those are: CVZ, SHADOW, LOW-SKY, and ON HOLD for Targets of Opportunity.

Table 2.2: Limited-Resource Special Requirements

Limited ResourceReason for constraint
ON HOLD [FOR <visit>]

Requires special handling (e.g., Targets of Opportunity).

RT ANALYSIS

REQuires UPLINK

Requires real-time TDRSS links, which are difficult to schedule and may be withdrawn at last moment.

ORIENTation <angle1> TO <angle2>

SAME ORIENTation AS <visit>

A specific orientation can be available for as little as a one-week period every six months.

SHADOW

LOW-SKY

CVZ

Available for only a fraction of orbits.

AFTER <date>

BETWEEN <date1> AND <date2>

BEFORE <date>

SEQuence <visits-checked> WITHIN <time>

SEQuence <exposure-list> NON-INTerruptible

PHASE <number1> TO <number2>

Constrain scheduling opportunities. Can be mutually incompatible.

1The number of CoIs is limited to 999.

Expand/Collapse all...




Table of Contents


Change Log

Version Cycle 32 April 2024

  1. PROPINST-91405 - Added an explanation of the new fields for Target of Opportunity Number of Activations.
  2. Fix the link to the documentation of the Cycle 2 deadline.

Version Cycle 31 June-July 2023

  1. Added advice about phase constraints to the "Examples and General Advice"
  2. Fixed links to the Call for Proposals in the Introduction and What to Submit and the HOM page in the Lack of Acq section.

Version Cycle 30 May 2022

       Updated links to Cycle 30 Call for Proposals