Questions about Observing Scripts

This section describes some of the most common difficulties with the observing format. The questions and answers found here are likely to change as new difficulties arise and are addressed.

What is the proper layout order of commands in an observing script?
For most standard scripts, the user should first define all the setups. The setup definition section should be followed by the individual scan and/or loop commands.

How does specifying times relative to the project stop time work in practice?
When chosing a stop time, remember that the stop time that is referenced will determine what action is requested. There is a breakdown of the various stop times and how each one is applied. In practice, however, the user will probably just need to specify the stop times for the individual setups (i.e. how long to observe a particular source) and the stop time for any loop commands (to insure that time remains for any following observations). The other stop times would only be needed for more complicated observing scripts.

How do I know the time range I have for my project?
Every project can be thought to run from the project start time until the project stop time. Once the project stop time has been reached, the project will end; there are no exceptions! Since the current time will always be greater than or equal to the project starting time when the project begins, all relative times can be addressed in terms of either the current LST or the project stop time. The range of valid times for any project can always be viewed in terms of these two times. Therefore, since there is no way to know the exact time your observing file will begin (or what time will be assigned as the project stop time), it is best to arrange your observations based on the hhmm timing method .

How do I plan my observations based on this relative scheme?
A general rule of thumb is to specify stop times inside the individual setups relative to the current LST (for example, stop=+24) and optional stop times for the scan and loop commands as times relative to the project stop time (for example, stop="stop-30").

Should I set maxobs for each setup?
In general, the maxobs keyword can be omitted from most setups. The only time it needs to be included is when the number of times a setup should be executed during one run of the project needs to be limited. This can be used to help control multiple observations of a source in the case when a project script is terminated and then restarted or when the number of times it should be observed normally needs to be monitored. For example, if the user only wants to observe a passband source once at the beginning of the project, that setup should have maxobs set to 1. Then, if the script is terminated early (but after the passband has been observed) and then restarted, the passband observation will not be observed again (and waste valuable source observing time!).

Can the frequency and/or correlator be set just once for the entire project?
Some projects will only want to set the frequency and tune once or may only want to adjust the correlator once. Is there a simple way to set the frequency and/or correlator only once for a project? Yes.

Remember that if you include the keywords freq and iffreq in a setup, then the tuning program will be called every time you use this setup. This will be done regardless of whether tuning is necessary! Some observations do not call for tuning more than once for a project, so tuning each time the setup is used may not be desirable. To solve this, create a setup with just the tuning information . Also, add a call to scan at the beginning of your observations which uses this tuning setup as the setup argument. For example: 

# Setups follow:
setup name=tune freq=88.6318 iffreq=-770 obsline=hcn dopsrc=orimsr
### define other setups...
# Observing follows:
scan setup='tune'
### other observing commands....

Likewise, if any of the correlator keywords (cor*) are present in a setup, then the correlator program will be called every time this setup is used. This will be done regardless of whether or not the correlator characteristics have changed! Including the correlator keywords would be appropriate when the source and calibrator use different correlator modes. However, for those observations where the same correlator setup is used for all observations, this may not be desirable. In this case, like with the tuning, the correlator should be set once at the beginning of the observation and then not again. As in the example above for tuning, a single setup can also be created which defines the correlator setup and is then executed with a single call to scan at the beginning of the project observation.

Note: For more information regarding how to pick your correlator settings, refer to the Miriad tasks xcorf and corset.

Furthermore, if the tuning and the correlator are only set once per project, the setup in the above example can be modified to include both the tuning and correlator information and then set by running scan.

If a keyword appears in more than one nested setup, which one is used?
Nested setups are definitions that include other setups by use of the setup keyword. There is no restriction on the number of times a keyword can appear in a setup definition. The trick is in determining which one will actually be used when a command that uses that setup is run. A few example setups will serve to clarify this better than any other description. If a user defines their setups as: 
  setup name=A elevlim=30
  setup name=B setup=A elevlim=20
  setup name=C elevlim=20 setup=A
  setup name=D elevlim=20 elevlim=30
then only setup 'B' will use an elevation limit of 20 degrees; setups 'A', 'C', and 'D' will each use an elevation limit of 30 degrees. In other words, the "rightmost" keyword will ALWAYS take precedence.

How is my observing script executed?
When your script is tested within the checker environment (and also when it is executed at the observatory), it is passed as an argument to the project command. The project command controls the starting and stopping time of every project, determines the name of the archive directory, and deals with several other system management items. Your observing script should never be executed directly because many of the items necessary to run your tasks successfully will not be established. See the discussion of the project command in the checker guide for more details.
(up to Document Overview, back to Setting and Retrieving Variable Values, on to Putting it All Together into a Script)
James Morgan
 [an error occurred while processing this directive]
Page last modified: Thursday, 17-Mar-2016 13:48:30 EDT.