P2PP: tutorial for the README file
This tutorial provides step-by-step instructions on how to to fill in the README file available in P2PP 3.4.1 and above. To follow it, you should have a P2PP installation on your computer and be familiar with the essentials of the use of the software. Please refer to the instructions in order to install it, and to the P2PP User Manual for a general overview of P2PP and generic instructions on the preparation of Observing Blocks.
A README file is an integral part of the Phase 2 package that must be submitted together with OBs and finding charts for each Service Mode observing run. The README file is prepared and submitted with the same tool (p2pp) that is used to prepare and submit the OBs.
While writing the README, please keep in mind that the observer on Paranal has to deal with many different programmes. Therefore, a README should be concise and contain only information necessary to correctly execute your service mode observations. As much as possible, the observing constraints and strategy has to be encoded in the Observing Blocks (OBs) and this information should then not be repeated in the README.
In the following, we will show how to fill-in the README form, save it and reuse it, and check it into the ESO database.
In P2PP, the commands allowing you to manipulate your README file are gathered in a single menu, labeled Readme File. From the top down, you will find in this menu the following functions:
- View/Edit Readme: this pops up the README window, from where you can both see and edit the contents of the README file for the observing run which is currently selected in the list of folders in P2PP. This command is also available via the big yellow sticky note icon that appears in the P2PP toolbar.
- Import Readme: From your local disk, you can choose a previously exported README file, and use it to pre-fill the form in P2PP. This can be useful when you want to restore a README file from a previous backup, for example if you have prepared your run on a different computer. Also, this enables you to easily duplicate a README for a different run, for which the information is the same, or similar enough so that you want to modify it without starting from scratch.
- Export Readme: this function will create on your local disk an exported version of your README file. It is an ascii file with extension .rdx. It can be used to duplicate an existing README for another, similar observing run, saving time when preparing several runs. An exported README can be imported in P2PP with the Import function (see above).
- CheckIn Readme: with this command you will check-in your README file into the ESO database. An automatic verification is made on your inputs, as described above. If check-in was successful, the View/Edit menu will contain only the View option. When the README is checked in, you can still view it, however, all the fields are in read-only mode so that you cannot edit your inputs anymore.
- CheckOut Readme: as you can guess, this achieves the opposite of the previous operation. Calling this command enables to retrieve a README file that you have previously checked-in and to once again edit the contents of your README file.
The following section details the use of these functions on a real-life case. For further reference, we also encourage you to browse through the corresponding section of the P2PP manual.
Editing the README
For the purpose of this tutorial, we will prepare a realistic Readme, taking examples from different instruments. We will go through all required steps to fill in the README form for the first run and check it in. We will then use this README file as a starting point for the other observing run, taking advantage of the import/export functionalities described in the above section.
Filling out the README form
In the main P2PP window, select the appropriate run in the list of folders, for which you want to prepare a README file. (Reminder: if your most recent observing runs do not appear in the list of folders, please update it by using the command Download/Refresh Observing Runs in the File menu of P2PP.)
The first thing you will have to do is to call up the README window. This can be done by using the Edit/View Readme command in the Readme File pull-down menu, or by simply clicking the (yellow) sticky note icon in the main toolbar. When you do this, the window shown below appears.
Let's review the main components of this README window. In the top part, there is a non-editable section containing general information about your observing run. It is fetched directly from the ESO database and features your run ID, proposal type (e.g. normal, DDT, large program...), the instrument allocated to the run, the name of the PI, the OPC priority class (A-, B- or C-class program), and the total execution time allocated to the run.
Below the run information are three tabs which allow you to fill the readme, specify pre-imaging sources, and go through a checklist. You select the leftmost (readme) tab to first enter the estimated total execution time of the OBs you submitted for this run. To get this information, you can simply run the Execution Time report on all the OBs of your run, and then copy and paste the computed time in this field.
In order to enter specific information related to your run, please select the vertically stacked tabs (see figure above), some of which have a red triangle reminding you that filling these is mandatory. Each gives access to a section of the README file. By clicking on a tab, the corresponding section is displayed on the right-hand side. The information entered on these tabs will be read by the night astronomer just before executing your program so that no detail is overlooked for a successful observation!
For every section, you can input free format text. For tabs with a red triangle, a text example might be displayed in light grey in the input field the first time you select this tab. When you click on it to enter your text, the light grey text disappears. Only after entering text will also the red alert triangle disappear. For tabs without red triangle (non-mandatory tabs), hovering with the mouse over the tab label will display information on this tab. In some cases, a default text has already been entered. Please keep in mind that all changes made to the file are effective immediately (i.e. there is no longer a "Cancel" button"). The list of sections is as follows (those marked with a star (*) are mandatory):
- General Description*: short summary of observing programme, providing the night astronomer with any information needed to meet your science objective (e.g. required SNR). Also, please mention here any information necessary to identify the correct target in case there could be a doubt at the telescope (e.g. in the case of close companions!). Decision paths and/or OB modification requests that depend on the outcome of previously executed OBs are not allowed. Any more detailed execution instructions should be put in the "Special Execution Requirements" tab - please do not just duplicate the information!
- Waiver Requests: short summary of any approved Phase 2 waiver requests, including when they were submitted and when they were approved. These alert the night astronomer to pay attention to non-standard procedures.
- Critical Observing Condition Constraints*: any critical information about required observing conditions, but only those which could not be entered in the OB! For example, the specification of a coherence time for VLTI observations could be useful or a minimum image quality to avoid saturation.
- Time-Critical Aspects*: Please mention briefly time critical aspects, if any, encoded in the OBs or OB containers such as absolute time windows. Also mention aspects which cannot be encoded, such as coordinated observations between UT1 and UT2.
- Special Execution Requirements: should you have a dedicated execution procedure for your run, please use this section to describe it.
- Special Calibration Information: if you have submitted OBs for calibration, please describe them here, why you have submitted them, and how they should be executed relative to your science OBs (e.g. same night, once per observing run, etc.), unless they are submitted as part of an OB concatenation.
- ToO Information (onlt ToO runs): please indicate that this is a Target of Opportunity programme and give any special details.
- ToO Activators List (only ToO runs): here you should list people who are allowed to trigger the observations for this ToO run.
Just to the right of the readme tab is the pre-imaging tab. If your run is actually a pre-imaging run, check the box next to the question "Is this a pre-imaging run?".
If your run uses some pre-imaging data, please specify which instrument(s) were used as the pre-imaging source(s) be selecting them from the list under the "Sources" field on the right. Hold down the Ctrl key while selecting instruments with the left mouse button if more than one instrument was used for the pre-imaging. If you happen to use a source of pre-imaging which is not in the proposed list, you have the possibility to specify it in the field named "Other". Simply enter the name(s) of the instrument(s) that was (were) used. One final remark: the choice of the pre-imaging sources does not appear for the instrument VIMOS, because no other instrument than VIMOS itself can be used for pre-imaging.
Now, let's have a look at the third and last tab of the main Readme window. It contains a series of questions that you must answer. This latter part is designed as a check-list for your observing runs, for you to make sure that you did not forget any important information, and that your OBs comply with the defined, instrument-specific rules for Service Mode observations.
Please select the appropriate answer for each question. This can be either Yes or N/A (Not Applicable) if a question does not apply to your particular run. Please take the time to read carefully every question before answering, as the check-list is not the same for all instruments. Also, as said above, some questions will or will not apply to your run, depending on its intrinsic characteristics (observing mode, type of program, etc.). After having answered all of the questions, the red triangle on this tab will disappear.
Check-in (and check-out) of the README file
To submit your README file to ESO, you use the command Check-In Readme from the main Readme menu of P2PP. A verification report is run on your inputs, and if it reveals any error, you will not be allowed to check-in the README file. Please revise it, fill in all mandatory sections, answer to all the questions in the check-list, and try again.
A README which is checked-in cannot be edited unless it is checked-out again. If you need to modify or update your README file, you will have to check it out from the ESO database. Before doing so, make sure that you have selected the correct run from the list of folders. The selected folder will determine which README file you will unlock and retrieve. Once the run is selected, just call the command Check-out Readme.
You should not use the check-in / check-out facility as a convenience for preventing unwanted modifications on your side. Please use Check-In Readme only when you have the final version of your README file and you want to submit it to ESO. It is also not necessary to check-in your README file to save your inputs: as already explained, your README information is saved into your P2PP local cache whenever you change any information in it. Finally, if you want a backup copy of your README file(s), you can use the Export functionality (see below).
Exporting and Importing the README
In the same way that you can export your Observation Blocks, a similar functionality is available for your README files. By calling the command Export Readme, you will be presented with a selection dialog. Please note, that you are to choose the directory in which you want to save the file, and not the filename itself. As a matter of fact, the name of your exported README will be generated automatically from the corresponding run number. For example, the README file for the run 075.A-0123(B) will be stored as the file 075.A-0123_B_.rdx on your local disk.
Exporting your README files may be useful to keep a separate backup of your data, just as for your OBs. It can also prove to be useful if you want to transfer your Phase 2 data from one computer to another, i.e. from one installation of P2PP to a different one. Logically, your README file can be re-imported by using the command Import Readme. A dialog window will inform you if the import operation was successful or not.
Finally, the import/export functionality can be very useful if you happen to have several, very similar observing runs on a given instrument. Once you have filled out the README form for the first one, you can export it, select another run, and re-import the README. Then, you just have to edit this new README file to input the changes from the first run, rather than starting from scratch. A word of advice: never check-in a README file without properly checking all of its contents! If you choose to use the import/export procedure to duplicate a README file, please always check your inputs in the new README file, for the new observing run. Some content may apply to both of your runs, but the differences must be carefully pointed out, to maximize the efficiency at the telescope.
Let's have a look at an example: your program has two runs 075.A-0123(A) and 075.A-0123(B), which have very similar scientific goals and settings. Once we have filled out the README file for run (A), we want to be able to copy it into run (B), rather than having to start from scratch. To achieve this, here is the sequence to follow:
- with the run 075.A-0123(A) selected in the list of folders, in the main window of P2PP, you call the command Export Readme.
- A selection dialog appears, asking to choose a directory. You use the directory/subdirectory display to select the place where we want to save the README file for run (A).
- Once the first README file has been saved, you select run 075.A-0123(B) in the list of folders.
- Then, you call Import Readme. A file selection dialog appears, from which you choose the directory where you exported our first README file, and then the exported file itself. In this example, the file you are looking for is called 075.A-0123_A_.rdx and you select it.
- The README is then imported into run (B). A confirmation window will inform you whether the import was successful, or not.
- You can now proceed, and finalize the README file for your (B) run. As said above, it is essential that you carefully review your inputs, and emphasize the differences between the (A) and (B) observing runs.
This page is valid for all instruments