P2PP: tutorial for the README file
This tutorial provides a step-by-step example to fill in the on-line README file available in P2PP 2.9 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.
Please note that the README file is a required input for Service Mode runs, with the ESO telescopes in Paranal and La Silla, but this tutorial does not apply to any Visitor Mode run.
Since Period 75, you can use the same tool to prepare your OBs, attach your finding charts, and also write the README file for your Service Mode observing runs. This allows you to check-in all of your Phase II material within a single application. 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. We will also explain how to finalize your Phase II submission, by sending a completion signal to the User Support Department.
In P2PP, the commands allowing you to manipulate your README file are gathered in a single menu, labeled Readme. 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 Readme button that appears in the P2PP toolbar.
- Verify Readme: when calling this command, a set of basic checks are made on your README file, mostly to verify that the mandatory sections are not empty. We will see an example of the error messages that you can get in the next section. If your README file does not pass these checks, you will not be able to check it into the ESO database, as it also happens for your OBs.
- CheckIn Readme: this command will allow you to check-in your README file into the ESO database. An automatic verification is made on your inputs, as described above. If check-in is successful, a lock icon will appear on the Readme button in the main toolbar. When the README is checked in, you can still view it by clicking on the README button, or by calling the View/Edit Readme command in the menu. 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. Upon completion of the operation, the lock icon disappears of the Readme button in the toolbar, and you can once again edit the contents of your README file.
- Export Readme: this function will create on your local disk an exported version of your README file. It is not per se a text-only, human-readable version of your README, but rather a backup copy of it. Also, it can be used to duplicate an existing README for another, similar observing run, without having to re-input everything. An exported README can be imported in P2PP with the Import function (see below).
- Import Readme: reverse function of the previous one. From your local disk, you can choose a previously exported README file, and use it to populate 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.
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
In this section, we will consider a real-life case of two ISAAC observing runs. We will go through all required steps to populate the README form for the first run, verify it 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.
Although we deal here with an observing program for ISAAC, the tutorial is easily transposed to any other instrument. Only the exact contents of the entry fields, and the label of the questions, changes from one instrument to the other.
Filling out the README form
Before being able to edit your README file, you will naturally need to start P2PP, and login to your account. Then, in the main P2PP window, select the appropriate run in the list of folders, for which you want to fill a README file. We will start the tutorial from this point.
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 naturally call up the README window. This can be done by using the Edit/View Readme command in the Readme menu, or more simply by clicking the README button in the main toolbar. When you do this, the window shown below appears (click on it to see it at full size). We have blurred out the actual run number and PI name, but this is unimportant for the purpose of this tutorial.
Let's review the main components of this README window, starting from the top. First, you find a menu bar, which sole purpose is to hold the File > Close command, which enables you to dismiss the README window. Please note that there is no need to save your data before closing the window. Indeed, just as for the edition of an individual OB, all your changes are automatically recorded into your local cache as soon as you type them in. Just underneath the menu bar, there is a non-editable section, containing general information about your observing run. It is fetched directly from the ESO database, and is presented to you as a reminder. It features your run ID, the instrument allocated to the run, the OPC rank class (A-, B- or C-class program), and the total execution time. Below are the proposal type (e.g. normal, DDT, large program...), and finally the name of the PI.
Let's now switch to the first editable part of the README. It is comprised of a set of tabs, each of which gives access to a section of the README file (see figure below). By clicking on a tab, the corresponding section is displayed on the right-hand side.
For every section, you can input free text in the white area. If you bring the mouse cursor on the title of a given tab, a small tooltip will pop up, that indicates the maximum allowed length for that section. The interface will prevent you from typing more characters than the allowed maximum. Likewise, if you are copying-and-pasting some material from an external file, it will only work if the number of characters that you want to paste does not make the total size of the concerned section exceed its maximum size. If the paste operation does not work, just grab a smaller section of text from the source that you are using.
To fill in this whole section, just select the tabs one after another, inputing the necessary information. The list of sections is as follows (the sections marked with a red star (*) are mandatory):
- General Description*: short summary of observing programme, providing ESO with any information needed to meet your science objective. Decision paths and/or OB modification requests that depend on the outcome of previously executed OBs are not allowed.
- Waiver Requests: short summary of any approved Phase II waiver requests, including when they were submitted and when they were approved.
- Critical Observing Condition Constraints*: any critical information about required observing conditions.
- Time-Critical Aspects*: if your OBs must be executed within specific time windows or in some time-specific sequence, please describe those constraints here. Note that in the case of specific time windows, these need to be indicated also under the Time Intervals information in the OB itself.
- 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.). In particular, you must provide the magnitude and spectral type for all user supplied photometric or spectrophotometric calibration stars.
- ToO Information: please indicate that this is a Target of Opportunity programme and give any special details.
- ToO Activators List: here you can input the list of people who are allowed to trigger the observations for this ToO run.
- Pre-imaging Requirements: if this is a pre-imaging run, please indicate it here and describe any special requirements. Please indicate also the source of the pre-imaging in the dedicated field of the README form (see next section).
Now, let's have a look at the lower part of the README window. It contains some additional entry fields, and 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.
First of all, we ask you to indicate the current e-mail address of the PI for this observing programme. This is to ensure smooth communication between ESO and the PI of the run. This field is mandatory, and it will be checked for correct formatting upon verification of the whole README. Just below, please give the total execution time that you have computed for the OBs of 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. However, you can input additional details here, should the need arise.
Just below are some informations related to pre-imaging. If your run is actually a pre-imaging run, tick 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). To do so, click on the button next to Source(s) of pre-imaging. This opens up a dialog window like the one depicted on the right. From the left column, select the instrument which was used for the pre-imaging, and then click the Add button. The selected instrument will show up in the list on the right. If you made a mistake, select the instrument in the list on the right, and click on Delete. You can repeat the operation several times, selecting an instrument on the left, and adding it to the list. Once you are done, click on OK. The selection window is dismissed, and your inputs are displayed in the main README form. 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 Pre-imaging sources not listed above. 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.
The rest of the README form is a check-list that you must go through, and select the appropriate answer for each question. This can be either Yes or No, 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.).
Verification of the README
Once you are done with filling out the README form, you can use the command Verify Readme to check its contents. An example of the report you get is depicted on the right. In this example, the report tells you that:
- the e-mail address of the PI is incorrect, it was probably mistyped. For example, the address john.smith@observatory will raise an error; it is fixed by typing email@example.com.
- the section Critical Observing Condition Constraints has been left empty, which is a cause of error. As already mentioned, this is one of the mandatory sections, that has to be filled in every case. If your run does not have specific, critical observing condition constraints, you must specify it explicitly.
- the section about Time-Critical Aspects is also empty. The reason for this error is the same as above. Please fill in this section in every case.
Once the verification report does not show any error messages anymore, you can safely check-in your README file...
Check-in (and check-out) of the README file
To submit your README file to ESO, you will use the command CheckIn Readme from the main Readme menu of P2PP. In any case, the 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.
If the check-in is successful, a lock icon will appear on top of the README button in the main toolbar. From this moment on, you cannot edit your README file anymore, although you can of course still view it.
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 CheckOut Readme. The lock icon will disappear from the README icon, and it will be possible to edit the README again.
You should not use the check-in / check-out facility as a convenience for preventing unwanted modifications on your side. Please use CheckIn Readme only when you have the final version of your README file, and you want to submit it to ESO. Indeed, each check-out operation triggers a signal to your ESO support astronomer, giving an indication that you are still working on your Phase II material. 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 immediately after input. 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 II 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 our example: it turns out that our 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, we call the command Export Readme.
- A selection dialog appears, asking to choose a directory. We 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, we select run 075.A-0123(B) in the list of folders.
- Then, we call Import Readme. A file selection dialog appears, from which we choose the directory where we exported our first README file, and then the exported file itself. In this example, the file we are looking for is called 075.A-0123_A_.rdx. We 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.
Finalizing your Phase II submission
As mentioned in our Service Mode guidelines, you need to send a signal to the ESO User Support Department (USD) to indicate that your Phase II preparation is finished. Only then, can the USD astronomers check your material, so that it can be certified and scheduled for execution at the telescope.
This signal will be sent by clicking on the p2pp-submit button, available from the main toolbar of P2PP (see the above screenshot). A confirmation dialog will appear before your action is actually executed: the p2pp-submit signal must be sent only when you have checked-in all the OBs and the README file for a given run. If, during the lifetime of the observing run, you should have to modify either some OBs, or the README file, you will have to re-send the signal once your modifications are done, by clicking again on the p2pp-submit button.
Please note that, as before, this completion signal has to be sent for every observing run. Just like for the check-in of your README file, the p2pp-submit command acts only for the run which is currently selected in P2PP. If you are submitting material for several runs, then please repeat the procedure as many times as needed.