A Cookbook for Using The Gemini Phase I Tool (PIT)

Below is an outline of the steps involved in writing a proposal using the Phase I Tool, the PIT. More detailed information is available from the PIT help pages, accessible via the contents list on the PIT home page and within the PIT itself (where there is context-sensitive help). Several areas of the PIT are partner country specific so please check the partner-specific instructions maintained by your National Gemini Office (NGO) e.g. by following the links in the Phase I overview, before submitting a Gemini proposal using the PIT.

1) Overview:

PIT Sections: The PIT is divided in two Sections (Common and Gemini). Each Section contains several Pages (e.g., Scientific Justification, Targets, etc). To select (either a Section or one of its Pages), just click once on the corresponding "folder tab" at the top.

Drop-down Menus: The PIT has three drop-down Menus (upper left corner): File, Observatories and Help. The "File" menu allows the usual file manipulation (New, Open, Save, Save As), plus a Close option to close individual windows if more than one proposal is opened at the same time. An Exit option quits the PIT completely, however, you are prompted to 'save and quit' the file if changes to the proposal have not been previously saved. The "Observatories" menu will eventually allow the selection of different facilities and load Observatory specific information. Currently, only the Gemini Telescope is available. The "Help" menu activates the context sensitive, on-line help.

Page Buttons: Most of the individual Pages within the PIT contain file (Load, Save) as well as text (Cut, Copy, Paste) manipulation buttons. These buttons are located inside the Page window and refer explicitly to the text box below them not the whole proposal. Please read the Help pages entitled "File Tools" and "Cut, Copy Paste" for more information.

Saving a Proposal: To save the full text of the Proposal, use either the Cntl-s key command or the Save (or Save As) command from the File Menu. The Save File button, associated with most of the individual Pages, will save the content of that Page text box only.

Queue or Classical Observing:  A single Gemini proposal can contain multiple observations or the same target or different targets.  However, a proposal cannot contain observations in both queue and classical observing modes.  If you require observations in both modes then you must submit separate proposals.

Target of Opportunity Proposals: Queue programs whose targets are not known at the time of proposal submission should specify whether they are applying for Standard (response times greater than 24 hours to months) or Rapid Response (response times of minutes to hours with interrupt priority) Target of Opportunity (ToO) status. Programs that are granted Rapid Response ToO status may also submit Standard ToO triggers. ToO proposals must include instrument resources, conditions constraints, and one observation with the total requested time.  The observation does not need to include target or guide star information.

Multi-telescope Proposals: For a given proposal, only one telescope (Gemini North, Gemini South, Keck, or Subaru) may be chosen in the resources section.  If you would like to use more than one telescope facility, then please submit a separate proposal for each telescope.

Text Length: The PIT does not limit the length of the text in the Abstract, Scientific and Technical Justification Pages. These are Partner specific limitations and must be verified to conform with the NGO requirements before submitting the proposal.

Cut/Paste between Windows: If more than one proposal window is opened at the same time or you want to move/copy text from one page to another, it is possible to cut, copy and paste between windows/pages using the "Cut", "Copy", and "Paste" buttons.  From external processes/windows on a Unix box these buttons do not work due to differences in the cut/paste buffers between Unix and Java. However, if text is selected (highlighted) in another text application (e.g. a UNIX text editor or xterm), it can be copied using the keyboard "copy" key and pasted in a PIT text box using Ctrl-v. Under Windows and Linux Ctrl-x (cut), Ctrl-c (copy) and Ctrl-v (paste) can be used. On Macs the standard Command-x (cut), Command-c (copy), and Command-v (paste) are available.

Text Format: It is not necessary to format the typed text within the PIT (i.e. include CR/LF at the end of each line) since the program will automatically wrap each line, however, there is no way to unformatted previously formatted text imported/included from an external file other than manually deleting each end-of-line line feed.  Auto formatting of text in text boxes (e.g. in the scientific justification section) is now enabled in the 'Save as Html' feature on the Submit page and hence, the text will appear easily readable in the html saved document.

LaTeX: It is possible (but not recommended) to include LaTeX control sequences in any text input to text boxes within the PIT. However, no LaTeX processing is performed by the program and hence, all LaTeX commands appear in their raw format in the saved/submitted xml file and in a saved html file.  Please check the partner-specific restriction on using LaTeX within your proposals.

Highlighted Text: Highlighted items (e.g. using left-click drag with the mouse) turn green.

Sample Proposal: A sample proposal is included with the distribution (the file named GeminiDemo.xml). It is highly recommended for first time users to load it and examine its contents and structure.

HELP!!!: If you have more questions consult the PIT web pages of the context-sensitive on-line help .  If this doesn't help, contact your NGO through the Gemini HelpDesk.

2) The Common Section: defining your program

2.a) Title and abstract:

Enter a short title and an abstract for your proposal. The abstract can be entered by clicking in the large white "Abstract" box and typing it directly or by importing an external ASCII/text file. Click on the "Open" button right above the white "Abstract" space, and a new window will appear listing the contents of the current directory. Navigate through it using the Up and Home buttons or by double-clicking on the icons next to the folder name, then double-click the file containing the abstract once you find it. The text inside the "Abstract" box can be manipulated by highlighting the desired section and using the Cut, Copy and Paste buttons the usual way. Check with your NGO on the size allowed for the Abstract.

2.b) Scientific Justification: (aka, the great idea)

This section allows the user to enter a detailed justification for the observations requested, generally in the form of text describing the context of the proposed observations with respect to previous work in the field (the 'Background'), and details of the motivation and scientific importance of the requested observations (the 'Proposed Observations'). Technical details such as integration time, S/N, etc. belong to the Technical Justification Page (3.b). The text can be typed directly or imported from an ASCII file, as with the Abstract. It can also be exported to a file using the Save File tool. The text manipulation buttons also work here. Check with your NGO on the size allowed for the Justification.

Classical programs that request good conditions (better than IQ=85% and CC=70%, or WV=80%) must provide information about bad weather backup plans as an attachment to the scientific justification. Include a brief description of the science, the relaxed observing conditions, a justification of why this can be done under the relaxed conditions, and a target list. The text should not exceed one page but the target list can extend to more pages.

Figures must be included as attachments (as well as tables and the reference list, if you want to save space in the justification itself!). To include an attachment (GIF, JPEG, PDF,  and plain text (TXT) are the formats allowed), first click on the "New Attachment" button, then "Choose" (bottom right of the page). This will give you access to the directory tree. Once found, double click on the desired file, and it will be added to the list. Finally, click inside the "Caption" box and type a description for the attachment (e.g., Fig. 1). If the attachment  includes the caption, then leave the Caption box empty. To include other files, repeat the process from the beginning. Check with your NGO for constraints on the maximum number of attachments allowed. Postscript (PS and EPS) files are no longer accepted as attachments, please convert these files to another format before attaching. Several tools are available to convert postscript to PDF.

2.c) Keywords:

The Keywords set is meant as a tool to categorize the proposal being submitted. There is no limit to the number of keywords allowed. Select as many as may apply to accurately describe your program. It is required that you select at least one keyword otherwise your proposal will not verify.

To choose the keywords, first select a "Category" (e.g., Extragalactic) in the top frame, corresponding to the area of astronomy the proposal falls under. This will bring up all the "Available Keywords" for this category in the lower left panel. To add a keyword to your list, use the scroll bar to find it, highlight it with one single click of the left mouse button (remember, it turns green!) and click on the right-pointing hand to add it to the "Selected Keywords" area (lower right panel). If you add keywords from one category and then chose another Category, your previously entered keywords will be removed.

To manually remove a keyword from the "Selected Keywords" area, highlight it and click on the left-pointing hand.

2.d) Investigators:

First highlight the "PI" entry in the left window, and enter all the Principal Investigator information required in the right window. Then click on the "New Co-I" (left) button to include each of the co-investigators. When finished, selecting the "Team" entry in the left will show the complete list of Investigators on the proposal.  The number of Co-Is allowed is partner-specific, please check your NGO info for the maximum number allowed.  The Co-I list can be re-ordered using the arrow buttons just above the team list.

The pull-down list next to the Institution field contains a reasonably complete database of worldwide Physics and Astronomy research departments and institutes. Selecting one will automatically put its address in the Address field. Check for correctness and completeness and edit the address if necessary.

Grad Thesis vs Grad No Thesis (PI information, "professional status"): if the PI is a Graduate Student and the data are part of the thesis work, select Grad Thesis. If they are not part of the thesis work, select Grad No Thesis.

The following fields on the PI Information are mandatory: First name, Last name, Institution, e-mail. The Proposal will not verify if any of these is left blank.

The "Copy Co-I" button will copy the highlighted entry (including the PI) to a new Co-I one. This is a quick way to create a new Co-I if there are two or more from the same institution.

2.e) Targets:

The targets list can be typed in manually or imported from an ASCII/text file. In either case is important that the coordinates are typed separated by spaces or ":" only (e.g., SgrA will be at 17:45:12.0 and not 17h45m12.0s. The wrong input is accepted by the Tool, but an error will occur only when the target list is imported latter in the Observations Page (3.a).  Target of Opportunity proposals do not need to enter targets or target placeholders here.

Before selecting targets please check that they will be visible for a significant period of time in the semester for which you are proposing. The proposal checks in the Submit tab will give warnings if the coordinates of the targets are outside the optimal range for the given semester. Short visibilities can lower the proposal's chances of getting time or of being scheduled.

If typing in your target list, first click "New", then type the Object's name in the white box at the bottom of the page (you cannot edit the middle panel!). Select the System (HMS, Deg or Non-sidereal) and the equinox, and type the coordinates on the white boxes to the right. Enter a source brightness in the text box below the object name.  The brightness is a text string and can be in any units (e.g. 20th mag at K). Please specify them! If your targets are non-sidereal, the time at which the coordinates are valid must be also entered here. Repeat the process to add all targets. The entries can be moved up or down the list using the arrows above the central panel.

If importing a target list form an ASCII/text file please use the correct format.  This format is best described by entering information for one target then saving it to a file using the "Save" button and viewing the file.  The format is basically a tab separated list of sources, one per line.  Please note that, at present, the target brightness is not written to the text file when a target list is saved, hence, these values will have to be entered manually even if a target list is imported.

All targets are labeled "Science" to distinguish them from Wavefront Sensor Guide Stars.

The final column in the target table in the center section of the target page, indicates how many times a target is used (referenced) in the Observations Page. If  a target has a 0 here, the proposal does not reference this target and it will not be observed under this proposal .  However, it is acceptable for targets not to be referenced in the Observations page since they could be targets for a different proposal.
 

3) The Gemini Section: defining your observations

3.a) Observations:

It is simplest to do this in order, since there is a lot of detail required. Selecting an option in the left window will open the associated panel in the right one. Just fill in or click on as appropriate.

Program Information: Click on "Program Information" in the left panel to choose between classical or queue mode observing. Note that if submitting a proposal for classical mode, there is no need to set the observing constraints (see below), even thought the option is active.  Classical and queue mode observing cannot be combined in one proposal but require separate proposals.  Queue programs whose targets are not known at the time of proposal submission should specify whether they are applying for Standard (response times of greater than 24 hours) or Rapid Response (response times of less than 24 hours) Target of Opportunity (ToO) status. 

Resources: Click on "Default Resources" in the left panel to choose the facility to be used.  Starting in 2007B only resources from a single telescope facility (Gemini North, Gemini South, Keck, or Subaru) can be selected in a given proposal. Next, choose the instrument and configuration by a single-click on the expansion icon or a double-click on the item itself. Open up the whole tree, then select the lowest "leaf" e.g. a filter or grating. This will automatically select the branches above it to the facility.  Select as many "leaf" entries as you wish to completely define your proposed observations. Multiple instruments can also be selected in the Resource section. Clicking on the "Resource Summary" tab will show the final resource list for the proposal.

Note: The "Resources" list will change from semester to semester as different instruments become available. Make sure you have the correct version of the PIT for the semester that you are proposing. Contact your NGO if in doubt.

Constraints: Click on "Default Constraints" in the left panel to define the observing conditions required by your queue observing proposal. The right panel will show one single entry, called "Global Defaults". Expand the Constraints tree and click on Global Defaults. This will show you the values defined as "global defaults" for Sky Background, Cloud Cover, Image Quality and Water Vapor.  If these are acceptable to your proposal you need do nothing else since these constraints are globally effective. To create your own set of constraints, highlight Constraints again and click on the "Create" button at the bottom of the panel. A new entry (named only ObservingConditions) will be created.  Click on this entry in the left panel and the right panel will change to show the four above options. Click on the white space to entry a name to your Constraints set, then specify the different constraints as required by your scientific goals and chosen instrument.  See the Gemini web pages for details on the meaning/use of the four constraints.
Each observation (defined as detailed below) can have its own set of observing constraints which overrides the global defaults. To modify an existing set of constraints, select it as default (select "Constraints", then check the corresponding box), click on its name on the left panel "Constraints" tree, then change the values on the right panel as above. 

Adding Observations: Click on the "Add Obs" button to import the target list, as entered in (2.e) above. Select by checking/unchecking the appropriate boxes in the first column, or by clicking "All". By default the Tool selects all the unused entries. Then click "Create Observations" to generate the individual entries on the left panel of the Observations Page, in the form of a series of "Object Name (Observations)" containers. To delete an observation, highlight its container and click on the "Cut" button (the scissors). You can also copy and paste an observation using the corresponding buttons, or create a totally new target with the "New Obs" button.

Adding Guide Stars: Click the "Add WFS" button, to add one or all of  the following: Gemini Peripheral Wave Front Sensor (PWFS) guide stars, On-Instrument WaveFront Sensor (OIWFS) guide stars or facility AO WaveFront Sensor (AOWFS) guide stars. Remember: Guide stars are mandatory for all non-ToO proposals of sidereal targets that use resources from either Gemini North or Gemini South, either classical or queue!  Non-sidereal targets do not need to have guide stars selected. Next, the Catalog Search Assistant window will open. Use the upper pull-down list to choose a Guide Star Catalog server (from CDS, CADC or ESO). Next select a search algorithm for the appropriate instrument and WFS combination. Currently the following algorithms are available.

If your target will also be the AO guide star then select either the "Target is NICI AO Guide Star" if using NICI or "Target is AOWFS Guide Star" if using Altair. Next, select the targets by either clicking on the "All" button or by checking the appropriate boxes in the "Included?" column.  Then click on the magnifying glass button below the target table to start the search. Clearly, your computer has to be on the network for the search to be successful.  The status of each object will change from "pending" to "complete" as the algorithm successfully find the guide stars (one for each object). The lower panel will show the selected stars for the object highlighted in the upper panel. Once the search is complete, click on "Ok" (bottom of screen) to copy the guide star information and return to the Observations Page. The "Override?" box allows the user to select other stars than the ones chosen by the algorithm (the brightest ones). You will be presented with the full list of stars inside the patrol field. Select by checking the box in the left. If the search fails (or you decide none of the stars in the list is of your liking), you will be required to enter the guide stars by hand. For the purposes of this cookbook, we will assume the search was successful.

Defining Observation Details: Select each object (upper branch of the Object Name (Observation) tree) one-by-one and enter an exposure time. This time should include all overheads as detailed in the Gemini web pages and must also include off-source (sky) integrations. You can select different observing constraints for each object, if your program calls for it . To do so, click on the "Override Default Constraints" button at the bottom of the right panel. The list of defined constraints sets will appear, select by checking the appropriate box. A new branch (Constraints) under the object tree will be opened. The constraints can be edited by clicking on the constraint set name.  When you have finished entering  exposure times, selecting again the Program Information container will show the total observing time for the proposal. The current version does not update this value to include the overheads which are, as stated above, added into the exposure time per object. The exposure times specified have to be justified in the Technical Justification below.  Integration Time Calculators (ITCs) for most Gemini instruments are available on the Gemini web pages.  Exposure time calculators or sensitivity tables for available Subaru instruments (MOIRCS and Suprime-Cam) and Keck (HIRES) are available on the respective observatories' websites.

3.b) Technical Justification: (aka, the dry reality)

This Page should include a detailed technical justification for the requested observations, including items such as the rationale behind the choice of instrument and instrument configuration, and supporting figures for the exposure times requested (e.g., in terms of obtaining a particular signal-to-noise level or photometric accuracy, and the need of such.). Describe any additional calibration needed (AO stars or calibrations other than the default set - see below). If a particular observing sequence (series of sky-object exposures) is preferred, include it here. In the end, consult the Instrument Help Pages to add up the overhead time, and give the total (observations, off-source, overheads, AO stars, special calibrations) length of the proposal. The procedure for the Queue Mode will be to obtain standard flat fields and appropriate spectroscopic standards (estimated photometric magnitudes are probably accurate to 10%) for ratioing and approximate flux calibration.  These are called the baseline calibration set. If your observations require more precision, or if you wish to specify the calibrations to be performed, please provide details here.  If not, the baseline calibration data set will be available to you. As for the Science Justification, type or import the text from a file, and include the figures and tables as attachments. All the File and text editing tools described before can be used here. Again, check with your NGO on the maximum length and number of attachments allowed here.

3.c) Band 3 Considerations:

The "Band 3" page allows the Principal Investigator to specify how a queue program would be carried out if it were to be scheduled in ranking Band 3. Programs in this band often need to relax the default observing conditions and modify the observing strategy in order to improve the chances of being observed (see Advice for Band 3 programs on the external web pages). All proposals that wish to be considered for Band 3 must fill out this section.

The top check box is to specify whether the proposal should be considered for inclusion in Band 3 by the TACs. This box is checked by default. Uncheck this box and ignore the rest of this page if you do not want the TAC to consider your proposal for Band 3.

If a proposal should be considered for Band 3 then enter the minimum amount of time that is required for the program to be considered successfully observed in the minimum required time entry box. Note that Gemini's goal is to complete (observe the entire allocated time) all programs in ranking Bands 1 and 2. In ranking Band 3 the minimum required time entered here will be used as the criteria of successful observation but Gemini will make every effort to complete as many Band 3 programs as possible. A small minimum required time will make it more likely that the program will be attempted but the minimum time should be large enough to generate a truly useful dataset.

The Band 3 total requested time box gives the total time requested if the program ends up in Band 3. By default the "Edit value" box is not checked for new proposals and the time in this box matches the summed time from the Observations tab. If this value needs to be changed, click the "Edit value" check box and then enter the new number in the entry box. The change should be justified in the consideration text box. Unchecking the "Edit value" box will cause the value to revert to the value from the Observations tab. Proposals from semesters prior to 2008A will have the "Edit value" box checked by default and either the box must be unchecked or a value entered before the proposal can be submitted with the current PIT.

Next, enter the conditions that your program would use if it were to be done in Band 3. Unless your program really, truly needs the very best observing conditions that Mauna Kea or Cerro Pachon have to offer, relaxing your image quality, cloud cover, sky background or  water vapor requirements can greatly increase the chances of your program getting data. Use the radio buttons in the conditions section to specify the observing conditions that the programs gets placed in Band 3. To copy the default conditions constraints from the Observations page to the current one, click the "Set to Default Constraints" button to the right of the Water Vapor section.

The Band 3 Consideration Text should describe the changes to the original program that would take place if it were to be in Band 3. Specifically, the trade offs between total exposure time and the number of targets should be discussed and the final signal to noise of the observations using the relaxed conditions (if any) should be given. If the observing conditions cannot be relaxed then this should be explained. Finally, the minimum required time should be justified.

3.d) Publications:

List any previous publications, either directly related to this program or simply based on data acquired over the last few (5-6) semesters, using any telescope (not limited to Gemini). List also all previous telescope allocation time (anywhere) for this program only. To enter a new publication, click on the "New Publication" button and then type the reference in the form

Author1, Author2, Author3, et al. (YYYY), "Title of Publication", status (in press or Journal, Volume, Page).

3.e) Allocations:

3.f) Scheduling:

If this is a queue-mode proposal that has special timing constraints, such as observing a rare eclipse or occultation or is to be done synchronosly with another telescope, then Optimal or Synchronous dates and reasons should be given in the appropriate tabs.  Queue proposals cannot give Impossible dates.

If this is a classical-mode proposal, indicate the impossible, optimal, and/or synchronous range of dates, whichever and all that applies. 

To enter a constraint first select the appropriate type (e.g., Impossible) using the radio buttons, then select the month using the arrows on the top of the calendar frame, and finally mark the range of dates by clicking on the first and last day of the interval (for the Impossible example, a red arrow will appear across the interval). Repeat for the Optimal (green) and Synchronous (blue) ranges, if applicable. The ranges selected will appear on the Summary window. Enter a justification for the dates selected in their appropriate boxes (e.g., ASCA observations, LNA TAC meeting).

3.g) Submit:

In the top space, enter the total and minimum time requested from each partner to which the proposal is to be submitted.  The value in the box in the Totals row of the Time Requested column should be the same as  the value in the "Time Summed over All Observation" box in the Program Information page of the Observations tab (see 3.a above). Select the country, or countries, to which the proposal will be submitted, then VERIFY YOUR PROPOSAL with the "Check Proposal" button. This process verifies the completeness of key fields (e.g. an Abstract  is present and Observations defined).  Also, generate a summary (see 3.h below) and check it visually for errors. Once you have confirmed that the proposal is complete, click the "Submit Proposal" button on this page. The proposal will be submitted to all the partners selected. The process may take a minute or so (since verification takes place at the remote NGO site).  Once complete, a dialogue box will be displayed indicating the success of your submission.  If successful, you will be allocated a reference number to identify your proposal to the NGO.  If not successful you may fix any problems, you may need to contact your NGO for help, and resubmit.

3.h) TAC:

Don't touch. This is for the partner country Time Allocation Committee use only!

3.h) Summary:

This will generates a summary of the proposal that can be printed or saved as an HTML or PDF file.  The generation of the HTML summary generally takes between 3 and 30 seconds depending on your OS and computer speed.  The HTML summary now retains paragraphing in the justification sections and produces a complete summary of your proposal.  In some partner countries it is this version of the proposal that is read by the TAC and referees/assessors. The Save as PDF button will save a PDF summary of the proposal with allowable attachments (various figure formats and text, but not .ps or .eps) embedded in the document. The PDF format can be selected from the list of available style files e.g. Gemini Default, NOAO, Chilean NGO, UK NGO.

Original document July 21, 2000; Claudia Winge
Last update February 14, 2008; Bryan Miller