FAQ for Editing Observing Scripts

How do I generate an observing script?
CARMA observing scripts are written in Python. While you can write scripts from scratch, you are strongly encouraged to generate scripts using the CARMA script writer.
At minimum, you will need to enter the source name, coordinates, assigned project code, and contact information. You can optionally change the default integration times. Click on "Generate Observing Script" to see a listing of the adopted calibrators and the template script. You can download the script to an ascii file, and make further edits to the observing script as necessary.

Which parameters do I need to edit before submitting the script?
Assuming the script was created using the CARMA script writer, the remaining entries that are required to be edited are:
1. Instructions for the observers
  Any special instructions for the observers should be entered in the comment section of the observing script. This section can be left blank if no special instructions are needed.
2. restfreq
  Rest frequency in GHz for the observations. See the rest frequency section for additional information.
3. IFfreq
  The IF frequency in in GHz to place the specral line. See the IF frequency section for additional information.
4. Correlator configuration (configband)
  The configband commands set the correlator configuration. A configband() command should be issued for each correlator band (currently there are 3 bands). The precise correlator configuration depends on the details of science program. The CARMA script writer produced recommended setups for basic continuum or spectral line observing models.
  More information is available on the CARMA instrument web page for general correlator information, a program is available to visualize the correlator setup, and a detailed description of the correlator commands.
How did I submit an observing script?
Observing scripts, source catalogs, and mosaic files should be combined into a tar file and uploaded using the CARMA script uploader. A username and password is required to upload the scripts. External investigators should contact their internal CARMA contact for instructions on how to upload the scripts.
Observing scripts should be called projectCode_obsblock.obs (e.g. c0010_abaur.obs), where project code is the project assigned where your proposal was submitted and obsblock is the obsblock specified on the proposal cover sheet. If you have multiple scripts per obsblock, an additional identifier can be added to the script name (e.g. c0010_abaur_1.obs).
Source catalogs should be named projectCode.cat, where project code is the project code assigned when your proposal was submitted.
The files should be combined into a single file called projectcode.tar (e.g. c0010.tar). You may also include in the tar file a README_projectCode containing instructions for the observers.

What calibration steps does the observing script perform?
The observing script will perform the following calibrations (not necessarily in this order):
1. Observe the noise source, which is useful to calibrate narrow correlator bands.
2. Perform radio pointing at the start of the track and and every N-hours thereafter as specified by the PI for the project. Note: The current default is to skip radio pointing
3. Observe the passband calibrator to measure the sensitivity variations as a function of frequency within each band. A noise source integration is obtained before the passband observations.
4. Observe a primary flux calibrator if one is available during the track. A noise source integration is obtained before the flux observation.
5. Cycle between the source and phase calibrator. A noise source integration is obtained before each phase calibrator observation.
How can I observe multiple sources with a single phase calibrator?
As described in the sources dictionary, sources['target'] can be set to a list of names that will be observed after each phase calibrator observation.

How do I make a mosaic?
Mosaicking parameters are specified in the mosaic structure contained in the template observing script. One will need to edit the following parameters in the mosaic structure:
1. Set mosaic['doMosaic'] to True
2. Specify the mosaic positions by creating a file of offset positions (i.e. mosaic['offsetFile']) or by specifying a list of offsets (i.e. mosaic['offsets']).
3. Indicate the units of the mosaic offsets. The possible values are arcminutes or fraction of the primary beam width.
4. Set how many mosaic positions (mosaic['nphase']). should be observed between phase calibrator observations.
How can I observe different phase calibrators for the first and second half of the track?
See the section What is this parameter used for? for instructions on how to observe more than one phase calibrator within the track.
How often should I perform radio pointing?
The radio pointing model is based on an optical pointing model derived from observations of hundreds of stars, and further observations to measure the offset between the radio and optical pointing solutions. Currently the RMS residuals from the pointing model is 0.2 arcmin, which should be suitable for most 3mm observations.
If you would nonetheless like to perform radio pointing, you should be set pointing['doPoint'] to True. Radio pointing will then be performed at the start of the track, and every N hours thereafter as specified by the pointing['interval'] variable.
How is a radio pointing source selected? A suitable radio pointing source is selected based on the following criteria:
1. brighter than pointing['minflux'] Jy.
2. elevation greater than pointing['elmin'] and less than 80 degrees.
3. within pointing['maxsep'] of the target.
4. the pointing source and the science target are both in the south (dec < 37.2 deg) or both in the north (dec > 37.2 deg). This criteria is used to avoid 360 deg slew in the 10-m antennas.
If a source in the pointing['preferred'] list satisfies these criteria, that source is used. Otherwise the nearest source in the CARMA calibrator list is used. If no suitable sources are available, the observations proceed without radio pointing. The script will attempt to find a suitable radio pointing source after every phase calibrator observation.

How can I observe multiple flux calibrators? By default the script will observe a single flux calibrator. Multiple flux calibrators can be observed by setting parameters in fluxcal.

How do I make a source catalog?
The source catalog should be generated as an ascii text file in the CARMA catalog format. The name of the catalog should be distinctive for your program, and is usually given as projectCode.cat, where project code is the project code assigned when your proposal was submitted.
If you do not already have a source catalog, you should send the source along with the observing script when submitting your observing program.
What observing issues should I consider when editing the observing script?
1. Gain calibrating narrow bandwidths
  One often does not have adequate signal to noise to perform gain-calibration on the phase calibrator in the narrow spectral bands. There are two limiting cases in calibrating narrow bands:
  1. At least one correlator band is set to 500 MHz
    In this case, the 500 MHz band can be used to gain calibrate the narrow bands. Observations of a bright source are needed to solve for any calibrations offsets between the narrow and broad bandwidths. These offsets appear to constant over a track and can be determined from the passband or phase calibrator observations.
  2. All correlator bands are set to narrow bandwidths
    In this case, one generally does not have adequate signal to noise on the gain calibrators. Therefore, one needs to reconfigure the correlator to continuum mode for the phase, flux, and passband calibrator observations. To do this, set the parameter reconfig(mode) in the observing template and specify the correlator configuration in the function setCorrCal() in the observing template.
    If mode=od.CORR_BW500, all correlator bands are set to 500 MHz bandwidth when observing the calibrator at the same IF frequency.
    If mode=od.CORR_BW500LO6, all correlator bands are set to 500 MHz bandwidth and and the IF frequency is changed such that the bands do not overlap within the 6-m IF band.
    If mode=od.CORR_BW500LO, all correlator bands are set to 500 MHz bandwidth and and the IF frequency is changed such that the bands do not overlap.
    1. At 3mm only, two bands are placed in the optimum 6-m IF, and the third band is in the optimum 10-m IF. In this case, the third band is outside the 6-m IF and would not contain any signal from the 6-m antennas.
    2. At 1mm only, all three bands are within the IF for the 6-m and 10-m antennas.
    The passband for the narrow spectral line models can be solved for using the noise source. In addition, the template script will observe the passband calibrator in both correlator configurations to help measure phase offsets between the different correlator configurations.
2. Cable wrap when observing sources in both the north and south
  Occasionally the best phase calibrators for a source will be north of the observatory latitude of 37.23 degrees while the source will be south of this limit (or vice versa). As the phase calibrator and source transits, the cable wraps on the 10-m antennas will reach a limit, and it will be necessary to slew the antennas 360 degrees so that they can observe both the southern and northern sources. In the worst case (but not infrequent) scenario, the 10-m antennas will slew 360 degrees every time when switching between the phase calibrator and the source. A common situation when this occurs is in Taurus, where 3c111 is a convenient calibrator, but it north of the terminus while Taurus is south.
  In these instances, the best situation is to use two calibrators: 3c111 for the first part of the track before it transits, and a second calibrator in the south after 3c111 transits. See the section on listing phase calibrators for instructions on how to specify multiple phase calibrators in a track.
Can I edit the python script to fine-tune my observations?
While the template script will handle most observations, some programs will need a specialized observing script. Investigators can edit the observing scripts as needed.
Custom modified scripts that do not execute properly may not be re-scheduled.
You may wish to contact CARMA staff or a CARMA collaborator and arrange for a short test of a customized script before submitting the script. If you edit the observing script, please enclose your changes with the comment lines:
```
# BEGIN CUSTOM
code changes...
# END CUSTOM
    
```
These comments will help the observers diagnose any problems with the script, and also provide ideas on how to improve the template script.
Investigators needs to be extremely careful modifying the script, since the script is designed to give the observers considerable flexibility in running the track.

What is this parameter used for?
1. correlator
2. fluxcal
  The fluxcal dictionary controls how many primary and flux calibrators are observed in a flux calibration cycle, and how many cycles to observe in a track. The default parameters are set to observe one primary flux calibrator if available, or one secondary flux calibrator otherwise. The fluxcal options can be modified to attempt multiple flux calibration cycles in a track. Given that most primary flux calibrators are found around 22 hours LST, there is no guarantee a primary flux calibrator will be observed.
  1. count
    count, in combination with fluxcal['waiton'], indicates how many antennas should be tracking the source before beginning the integration. The default value is waiton=COUNT and count=-2
    If, for example, count = -2 (i.e. is less than zero), then the integration will begin when all but two antennas arrive on source.
    If, for example, count = 2 (i.e. is greater than zero), then the integration will begin when any two antennas arrive on source.
    The count parameter is only used when waiton = COUNT. Otherwise, the value of count is ignored.
    count is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['count'] unless it is explictly added to the fluxcal dictionary.
    For example, to begin integrating when all but 3 antennas are on source, set:
```
limits = { 
   ...
   'waiton' : COUNT,
   'count'  : -3,
   ...
  } 
```
  2. doBoth
    If doBoth is True and doprimary and dosecondary are also True, then the script will attempt to observe both primary and secondary calibrators.
    If doBoth is False, a secondary calibrator will be observed only if dosecondary is True and a primary flux calibrator is not observed.
  3. doPoint
    If doPoint is True, then radio pointing is performed on the flux calibrator before integrating if needed. The parameters in the pointing dictionary are used, except for fluxcal['doPoint'] and fluxcal['maxsep'] override the corresponding pointing parameters.
    The following criteria are used to determine if pointing is needed on the calibrator:
    1. the last pointing source was more than pointing['interval'] hours ago;
    2. the last pointing source was more than pointing['maxsep'] degrees from the calibrator;
    3. the last pointing source was on the opposite side of the north/south terminus relative to the calibrator;
    If either (1), (2), or (3) is True, then pointing is performed on the calibrator.
  4. doPrimary
    If doPrimary is True, the script attempts to observe a primary flux calibrator during a flux calibration cycle.
  5. doSecondary
    If doSecondary is True, the script attempts to observe a secondary flux calibrator if (a) no primary flux calibrator has been observed or (b) doBoth is True.
  6. elmax
    elmax is the maximum elevation in degrees to observe a flux calibrator.
    elmax is a hidden variable that assumes the value and functionality specified in limits['maxElevationCal'] unless it is explicity added to the fluxcal dictionary.
    Example:
```
fluxcal = {
   ...
   'elmax' : 80.0,
   ...
  }
```
  7. elmin
    elmin is the minimum elevation in degrees to observe a flux calibrator.
    elmin is a hidden variable that assumes the value and functionality specified in limits['minElevationCal'] unless it is explicity added to the fluxcal dictionary.
    Example:
```
fluxcal = {
   ...
   'elmin' : 30.0,
   ...
  }
```
  8. interval
    interval indicates how often in hours to complete a flux calibration cycle.
  9. maxsep
    The maximum allowed separation in degrees between the pointing source and the flux calibrator. If the previous pointing source is more than maxsep degrees, then the pointing is repeated if fluxcal['doPoint'] is True.
    maxsep is a hidden variable that assumes the value in pointing['maxsep'] unless it is explicity added to the fluxcal dictionary.
    Example, to set the maximum separation to 30 degrees:
```
fluxcal = {
   ...
   'maxsep' : 30.0,
   ...
  }
```
  10. middle
    If middle = True, flux calibration cycles will be executed in the middle of the phase-calibrator/source cycle if necessary.
  11. ncal
    The maximum number of flux calibrators to observe in a cycle. If ncal > 1, there will be no duplicate observations within a cycle.
  12. ncycles
    ncycles indicates the maximum number of successful cycles to observe during a track. A successful calibration is defined to be when at least once one primary or secondary calibrator is observed.
  13. preferredPri
    By default, the script will automatically choose suitable flux calibrators based on vicinity to the target source and the elevation limits. Investigators can indicate the preferred primary flux calibrator with the preferredPri variable.
    For example, if you prefer to observe the flux calibrator Uranus or Neptune, set:
```
fluxcal = {
   ...
   'preferredPri' : 'Uranus, Neptune',
   ...
  }
```
    This implies that when it is time to observe the flux calibrator, the script will observe Uranus if it is above the elevation limit specified by fluxcal['elmin']. If it is not, the script will attempt to observe Neptune, and if that source is not available, the script will attempt any calibrators listed in primaryFluxCalibrators.
  14. preferredSec
    By default, the script will automatically choose suitable secondary flux calibrators based on vicinity to the target source and the elevation limits. Investigators can indicate the preferred secondary flux calibrators with the preferredSec variable. Woojin Kown is maintaining a list of bright secondary calibrators that are observed periodically at CARMA.
    For example, if you prefer to observe the secondary flux calibrator 3c279 or 3c273, set:
```
fluxcal = {
   ...
   'preferredSec' : '3c279, 3c273',
   ...
  }
```
    This implies that when it is time to observe the secondary flux calibrator, the script will observe 3C279 if it is above the elevation limit specified by fluxcal['elmin']. If it is not, the script will attempt to observe 3C 273. If that source is not available, the script will attempt to observe any of the secondary calibrators (except MWC 349, which is in the primary flux calibrator list).
  15. record
    record indicates the record length in seconds for the flux calibrator integrations.
    record is a hidden variable that assumes the value and functionality described in limits['record'] unless it is explicity added to the fluxcal dictionary.
    Example:
```
fluxcal = {
   ...
   'record' : 30.0,
   ...
  }
```
  16. tint
    Total integration time in minutes for the flux calibrator.
    The RMS noise for the amplitudes and phases are given in equations (1)-(4). channel is about 8 degrees per baseline.
  17. tsys
    tsys indicates how often (in minutes) to perform a full tsys measurement.
    tsys is a hidden variable that assumes the value and functionality described in limits['tsys'] unless it is explicity added to the fluxcal dictionary.
    Example:
```
fluxcal = {
   ...
   'tsys' : 10.0,
   ...
  }
```
  18. waiton
    waiton, in combination with fluxcal['count'], indicates how many antennas should be tracking the source before beginning the integration. The default values are waiton=COUNT and count=-2.
    waiton=ALL means all antennas must be tracking the source before beginning the integration.
    waiton=ANY means that a minimum of two antennas must be tracking the source before beginning the integration.
    waiton=COUNT means that the integration will begin when the number of antennas specified by fluxcal['count'] arrive on source.
    waiton is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['waiton'] unless it is explictly added to the fluxcal dictionary.
    For example, to begin integrating when all antennas arrive on source, set:
```
fluxcal = { 
   ...
   'waiton' : ALL,
   ...
  } 
```
  Example #1:
  To observe two flux calibrators (primary and secondary) in a single calibration cycle:
```
fluxcal = {
   'doPrimary' : True,
   'doSecondary' : True,
   'doBoth' : True,
   'ncal'   : 2,
   'ncycle' : 1,
  }
```
  Example #2:
  To observe a flux calibrator (priamry or secondary) at the beginning of the track, and again at the end of the track, set:
```
fluxcal = {
   'doPrimary' : True,
   'doSecondary' : True,
   'doBoth' : False,
   'ncal'   : 1,
   'ncycle' : 2,
  }
```
  Example #3:
  To observe a single flux calibrator every 2 hours:
```
fluxcal = {
   'doPrimary'   : True,
   'doSecondary' : True,
   'doBoth'      : False,
   'ncycles'     : 200,  # Set to a large number
   'ncal'        : 1,
  }
```
3. limits
  The limits data dictionary contains sets various limits used in the observing scripts.
  1. count
    count, in combination with limits['waiton'], indicates how many antennas should be tracking the source before beginning the integration. The default value is waiton=COUNT and count=-2
    If, for example, count = -2 (i.e. is less than zero), then the integration will begin when all but two antennas arrive on source.
    If, for example, count = 2 (i.e. is greater than zero), then the integration will begin when any two antennas arrive on source.
    The count parameter is only used when waiton = COUNT. Otherwise, the value of count is ignored.
    count is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of count = -2 unless it is explictly added to the limits dictionary.
    For example, to begin integrating when all but 3 antennas are on source, set:
```
fluxcal = { 
   ...
   'waiton' : COUNT,
   'count'  : -3,
   ...
  } 
```
  2. maxElevationCal
    Maximum allowed elevation limit in degrees for flux calibration, passband calibration, and radio pointing. These limits can be overridden in the individual dictionaries for these calibration steps by setting the elmax variable (i.e. fluxcal['elmax'], passband['elmax'], and pointing['elmax']). Example:
```
limits = {
   ...
   'maxElevationCal' : 80.0,
   ...
  }
```
    The elevation limit to observe phase calibrators and science targets are controlled separately by the observers. In general, the source and phase calibrator will be observed above an elevation of 30 degrees or an hour angle of +/3 hours, which ever is longer.
  3. minElevationCal
    Minimum allowed limit in degrees for flux calibration, passband calibration, and radio pointing. These limits can be overridden in the individual dictionaries for these calibration steps by setting the elmin variable (i.e. fluxcal['elmax'], passband['elmax'], and pointing['elmax']). Example:
```
limits = {
   ...
   'minElevationCal' : 30.0,
   ...
  }
```
    The elevation limit to observe phase calibrators and science targets are controlled separately by the observers. In general, the source and phase calibrator will be observed above an elevation of 30 degrees or an hour angle of +/3 hours, which ever is longer.
  4. record
    The record length in seconds for the observations. For example, if the record length is 30 seconds, and the source integration time is 5 minutes, the 5 minute integration will contain 10 records (= 5 min / 30 sec). The record length can be overridden in the individual dictionaries for these calibration steps by setting the record variable (i.e. fluxcal['record'], mosaic['record'], passband['record'], and sources['record']). Example:
```
limits = {
   ...
   'record' : 30.0,
   ...
  }
```
  5. tmoTrack
    When moving to a new source (e.g. slewing from the phase calibrator to the source position), the integration will not start until all antennas acquire the source position or until tmo seconds have elapsed, which ever is shorter. The tmo time should be several minutes since the 10-m antennas have relatively long slew times relative to the 6-m antennas.
    limits['tmoTrack'] sets the default limits for sources, passband, and fluxCal dictionaries. The limits can be overridden by adding the 'tmo' variable to the individual dictionaries (i.e. fluxcal['tmo'], passband['tmo'], and sources['tmo']).
    Example:
```
limits = { 
   ...
   'tmoTrack' : 500.0,
   ...
  } 
```
  6. trackingThreshold
    Maximum tracking threshold when flagging data, given in beam widths. If an antenna has a tracking error of X arcseconds, such that X/beamWidth > trackingThreshold, the data for that antenna are flagged in the miriad dataset.
    As example, a tracking threshold of 0.1 implies that data will be flagged if the tracking error is larger than 6 arcsec on a 10.4 m antenna at 115 GHz (or 3 arcsec at 230 GHz).
    A tracking threshold of 0.1 would imply a loss of 3% if two antennas are off by the maximum amount. For 0.15 it is 6% and 0.2 it is 10%. Depending on the calibration requirements for your program, you may wish to increase the tracking threshold.
    IMPORTANT: Data are currently NOT flagged is the tracking error is larger than the trackingThreshold. Flagging will likely be enabled in the future, and therefore this parameter should be set to a reasonable value. In the meantime, the current procedure is for individual investigators to flag their own data using miriad that have a large value of the axis RMS, indicating the antenna was not tracking properly on source.
  7. tsys
    The tsys parameter specifies how often in minutes a full system temperature measurement (including sky and ambient load) should be obtained. The tsys parameter is
    limits['tsys'] sets the default value for the sources, passband, and fluxCal dictionaries. The limits can be overridden by adding the 'tsys' variable to the individual dictionaries (i.e. fluxcal['tsys'], passband['tsys'], and sources['tsys']).
  8. waiton
    waiton, in combination with limits['count'], indicates how many antennas should be tracking the source before beginning the integration. The default values are waiton=COUNT and count=-2.
    waiton=ALL means all antennas must be tracking the source before beginning the integration.
    waiton=ANY means that a minimum of two antennas must be tracking the source before beginning the integration.
    waiton=COUNT means that the integration will begin when the number of antennas specified by limits['count'] arrive on source.
    waiton is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of waiton=COUNT unless it is explictly added to the limits dictionary.
    For example, to wait for all antennas to arrive on source before integrating, set:
```
limits = { 
   ...
   'waiton' : ALL,
   ...
  } 
```
4. mosaic
  The mosaic data dictionary contains the relevant parameters for mosaic observations. If you are not making a mosaic, set mosaic['doMosaic'] = False (the default value) and ignore the remaining mosaic parameters.
  1. arcminUnits
    If arcminUnits = True, the positions in the offsetsFile or the offsets list are given in arcminutes.
    If arcminUnits = False, the positions in the offsetsFile or the offsets list are given in fraction of the primary beam width.
  2. count
    count, in combination with mosaic['waiton'], indicates how many antennas should be tracking the source before beginning the integration. The default value is waiton=COUNT and count=-2
    If, for example, count = -2 (i.e. is less than zero), then the integration will begin when all but two antennas arrive on source.
    If, for example, count = 2 (i.e. is greater than zero), then the integration will begin when any two antennas arrive on source.
    The count parameter is only used when waiton = COUNT. Otherwise, the value of count is ignored.
    count is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of mosaic['count'] unless it is explictly added to the mosaic dictionary.
    For example, to begin integrating when all but 3 antennas are on source, set:
```
mosaic = { 
   ...
   'waiton' : COUNT,
   'count'  : -3,
   ...
  } 
```
  3. doMosaic
    If True, a mosaic is performed on the source listed in sources['target'].
    The integration time per pointing is indicated by sources['tintTarget'].
    If sources['target'] lists multiple sources, a mosaic if performed around the first target, and the remaining sources in the list are observed once.
    Example #1:
```
sources = { 
   'target'       : 'NGC1333',
   'phaseCal'     : '3c111',
   'tintTarget'   : 2.5
   'tintPhaseCal' : 3.0
  } 
mosaic = { 
   'doMosaic' : True,
   'nphase'   : 5,
   ...
  }
```
    In this example, the phase calibrator 3c111 is first observed for 3 minutes, followed by 5 positions in the NGC1333 mosaic which are observed for 2.5 minutes each, and followed by the phase calibrator again.
    Example #2:
```
sources = { 
   'target'       : 'NGC1333, 0336+323, 0303+472',
   'phaseCal'     : '3c111',
   'tintTarget'   : [2.5, 1.0, 1.0]
   'tintPhaseCal' : 3.0
  } 
mosaic = { 
   'doMosaic' : True,
   'nphase'   : 5,
   ...
  }
```
    In this example, the phase calibrator 3c111 is first observed for 3 minutes, followed by 5 positions in the NGC1333 mosaic which are observed for 2.5 minutes each, followed by 1 a minute integration on 0336+323, a 1 minute integration on 0303+472, and then by a 3 minute phase calibrator observation.
  4. nphase
    Number of mosaic positions to observe between phase calibrators. The general observing sequence is:
    1. observe the phase calibrator for sources['tintPhaseCal'] minutes
    2. observe the next nphase mosaic positions for sources['tintTarget'] minutes each
    3. Go back to step (1)
    If nphase=0, all of the mosaic positions are observed before going back to the phase calibrator. It is recommended that the phase calibrator be observed every 15-30 minutes depending on the array configuration. For large mosaics, nPhase should be set to a fraction of the total number of mosaic positions.
  5. offsets
    Instead of providing an offsets file, the offsets can be listed in the offsets variable. For example, the seven pointing grid offset above is:
```
mosaic = {
...
...
    offsets : [ [-0.500, -0.866], [ 0.500, -0.866], [1.000,  0.000], [0.000,  0.000],
                [-1.000,  0.000], [-0.500,  0.866], [0.500,  0.866] ]
}
```
    Note the use of brackets in specifying the mosaic positions.
  6. offsetsFile
    The name of the file containing the mosaic offsets positions. The offsets file should be submitted along with the observing script. The offsets should be listed one line per file, and represent the equatorial offsets on the sky relative to the position of the source.
    For example, here is a seven point offset grid in arcminutes (this is an example only, and the actual spacing for a Nyquist sample mosaic will depend on the observed frequency):
```
-0.500 -0.866
 0.500 -0.866
 1.000  0.000
 0.000  0.000
-1.000  0.000
-0.500  0.866
 0.500  0.866
 
```
  7. record
    record indicates how frequently the data are recorded in the output data file.
    record is a hidden parameter that does not appear in the default template. By default, it assumes the value and functionality specified by limits['record'] unless it is explictly added to the mosaic dictionary.
    Example:
```
mosaic = { 
   ...
   'record' : 30.0,
   ...
  } 
```
  8. startpos
    Starting position to observe first in the mosaic grid. startpos can have a value from 1 to N, where N is the number of positions in the mosaic.
  9. tmoMosaic
    When offseting to a new mosaic position, the integration will not start until all antennas acquire the source position or until tmoMosaic seconds have elapsed, which ever is shorter. The tmoMosaic time can be relatively short since the antennas generally have small distances to slew in mosaics. However, the value is too small, then most of the data are flagged or blanked since the antennas do not have a change to arrive on source. Observing tests indicate values less than tmoMosaic < 6 seconds are not useful.
    tmoMosaic is a hidden parameter that does not appear in the default template. By default, it has a value 15 seconds unless is explictly added to the mosaic dictionary.
  10. tmoTrack
    tmotrack specified the maximum time to allow the antennas to slew to a source before starting the integration.
    tmoTrack is a hidden parameter that does not appear in the default template. By default, it assumes the value and functionality specified by limits['tmoTrack'] unless it is explictly added to the mosaic dictionary.
    Example:
```
mosaic = { 
   ...
   'tmoTrack' : 500.0,
   ...
  } 
```
  11. waiton
    waiton, in combination with mosaic['count'], indicates how many antennas should be tracking the source before beginning the integration. The default values are waiton=COUNT and count=-2.
    waiton=ALL means all antennas must be tracking the source before beginning the integration.
    waiton=ANY means that a minimum of two antennas must be tracking the source before beginning the integration.
    waiton=COUNT means that the integration will begin when the number of antennas specified by mosaic['count'] arrive on source.
    waiton is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['waiton'] unless it is explictly added to the mosaic dictionary.
    For example, to begin integrating when all antennas arrive on source, set:
```
mosaic = { 
   ...
   'waiton' : ALL,
   ...
  } 
```
5. noise
  The noise data dictionary contains the relevant parameters for noise integrations. Noise integrations will be obtained at the begining of the track, and immediately before every flux and passband calibrator.
  1. record
    The record length in seconds for the noise integrations. For example, if the record length is 10 seconds, a 30 second integration will contain 3 records (= 30 seconds / 10 sec).
    Example:
```
noise = { 
   ...
   'record' : 30.0,
   ...
  } 
```
  2. tint
    The integration time in seconds for the noise source integration. Normally 10 seconds will provide sufficient signal to noise for the noise source data.
    Example:
```
noise = { 
   ...
   'tint' : 30.0,
   ...
  } 
```
6. passband
  The passband data dictionary contains the relevant parameters for passband observations. If you do not need passband observations (e.g. your phase calibrator is bright enough to use as a passband source), set passband['doPassband'] = False and ignore the remaining passband parameters. In a passband cycle, the passband calibrator is observed in the following correlator modes:
  1. the nominal correlator configuration set in the observing script
  2. the correlator configuration set by reconfig
  3. each of the correlator configurations specified in hybrid
  1. count
    count, in combination with passband['waiton'], indicates how many antennas should be tracking the source before beginning the integration. The default value is waiton=COUNT and count=-2
    If, for example, count = -2 (i.e. is less than zero), then the integration will begin when all but two antennas arrive on source.
    If, for example, count = 2 (i.e. is greater than zero), then the integration will begin when any two antennas arrive on source.
    The count parameter is only used when waiton = COUNT. Otherwise, the value of count is ignored.
    count is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['count'] unless it is explictly added to the passband dictionary.
    For example, to begin integrating when all but 3 antennas are on source, set:
```
passband = { 
   ...
   'waiton' : COUNT,
   'count'  : -3,
   ...
  } 
```
  2. doPassband
    If True, observe a passband calibrator. If False, passband observations are skipped.
  3. doPoint
    If doPoint is True, then radio pointing is performed on the passband calibrator before integrating if needed. The parameters in the pointing dictionary are used, except for passband['doPoint'] and passband['maxsep'] override the corresponding pointing parameters.
    The following criteria are used to determine if pointing is needed on the calibrator:
    1. the last pointing source was more than pointing['interval'] hours ago;
    2. the last pointing source was more than pointing['maxsep'] degrees from the calibrator;
    3. the last pointing source was on the opposite side of the north/south terminus relative to the calibrator;
    If either (1), (2), or (3) is True, then pointing is performed on the calibrator.
  4. elmax
    elmax is the maximum elevation in degrees to observe a passband calibrator.
    elmax is a hidden variable that assumes the value and functionality specified in limits['maxElevationCal'] unless it is explicity added to the passband dictionary.
    Example:
```
passband = {
   ...
   'elmax' : 80.0,
   ...
  }
```
  5. elmin
    elmin is the minimum elevation in degrees to observe a passband calibrator.
    elmin is a hidden variable that assumes the value and functionality specified in limits['minElevationCal'] unless it is explicity added to the passband dictionary.
    Example:
```
passband = {
   ...
   'elmin' : 30.0,
   ...
  }
```
  6. interval
    interval indicates how often in hours to observe a passband calibrator. At most ncal calibrators will be observed in the track.
  7. maxsep
    The maximum allowed separation in degrees between the pointing source and the passband calibrator. If the previous pointing source is more than maxsep degrees, then the pointing is repeated if passband['doPoint'] is True.
    maxsep is a hidden variable that assumes the value in pointing['maxsep'] unless it is explicity added to the passband dictionary.
    Example, to set the maximum separation to 30 degrees:
```
passband = {
   ...
   'maxsep' : 30.0,
   ...
  }
```
  8. middle
    If True, the passband calibrator will be observed in the middle of the track if necessary.
  9. minflux
    The minimum acceptable 3mm flux density when selecting a phase calibrator from the CARMA calibrator catalog. The signal to noise on the passband calibrator as a function of brightness can be estimated from Equation (1)-(4).
    The flux density is specified for the LO frequency of the science observations, unless pointing['tune95'] is True, in which case 95 GHz is used.
  10. ncal
    The maximum number of passband calibrators to observe in a cycle.
  11. preferred
    By default, the script will automatically choose suitable passband calibrators based on vicinity to the target source, elevation limits, and the minimum flux density. Investigators can indicate the preferred passband calibrator within the preferred variable.
    For example, if you prefer that the passband be measured on 3c279 or 3c273, you can set:
```
passband = {
   ...
   'preferred' : '3c279  3c273'
   ...
  }
```
    This implies that when it is time to observe the passband, the script will observe 3c279 if it is above the elevation limit specified by elmin. If it is not, it will then try 3c273, and if that source is not available, the script will automatically choose a suitable calibrator. If not calibrator is found, then passband calibration is skipped.
  12. record
    The record length in seconds for the mosaic observations. For example, if the record length is 30 seconds, and the mosaic integration time is 2.5 minutes, the 2.5 minute integration will contain 5 records (= 2.5 min / 30 sec). It can be useful to have a short record length of the passband['tint'] time is also short.
    record is a hidden parameter that does not appear in the default template. By default, it assumes the value and functionality specified by limits['record'] unless it is explictly added to the passband dictionary.
    Example:
```
passband = { 
   ...
   'record' : 30.0,
   ...
  } 
```
  13. tint
    Total integration time in minutes for the passband calibrator.
    The RMS noise for the amplitudes and phases are given in equations (1)-(4), where the bandwith (BW) should be replaced by the channel width for your correlator setup. For example, the 500 MHz correlator mode has 33 MHz wide channels. In 15 minutes integration time, the rms amplitude per channel in 15 minutes integration time will be approximately 0.14 Jy per baseline, or about 5% accuracy for a 3 Jy source. Similary, the rms phase per channel is about 8 degrees per baseline.
    For narrow bandwidths, it is often not feasible to obtain adequate signal to noise even on a bright quasar. Instead, one should use the electronic noise source to remove the channel to variations, and a bright quasar to remove any DC offsets between the noise source and the astronomical source. The necessary noise source integrations will be obtained automatically within the track.
  14. tmo
    When slewing to the passband calibrator, the integration will not start until all antennas acquire the source position or until tmo seconds have elapsed, which ever is shorter. The tmo time should be several minutes since the 10-m antennas have relatively long slew times relative to the 6-m antennas.
    tmo is a hidden parameter that does not appear in the default template. By default, it assumes the value and functionality specified by limits['tmoTrack'] unless it is explictly added to the passband dictionary.
    Example:
```
passband = { 
   ...
   'tmo' : 500.0,
   ...
  } 
```
  15. tsys
    The tsys parameter specifies how often in minutes a full system temperature measurement (including sky and ambient load) should be obtained when observing a passband calibrator.
    tsys is a hidden parameter that does not appear in the default template. By default, it assumes the value and functionality specified by limits['tsys'] unless it is explictly added to the passband dictionary.
    Example:
```
passband = { 
   ...
   'tsys' : 10.0,
   ...
  } 
```
  16. waiton
    waiton, in combination with passband['count'], indicates how many antennas should be tracking the source before beginning the integration. The default values are waiton=COUNT and count=-2.
    waiton=ALL means all antennas must be tracking the source before beginning the integration.
    waiton=ANY means that a minimum of two antennas must be tracking the source before beginning the integration.
    waiton=COUNT means that the integration will begin when the number of antennas specified by passband['count'] arrive on source.
    waiton is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['waiton'] unless it is explictly added to the passband dictionary.
    For example, to begin integrating when all antennas arrive on source, set:
```
passband = { 
   ...
   'waiton' : ALL,
   ...
  } 
```
7. pointing
  The pointing dictionary controls how often radio pointing is performed.
  1. count
    count, in combination with pointing['waiton'], indicates how many antennas should be tracking the source before beginning the integration. The default value is waiton=COUNT and count=-2
    If, for example, count = -2 (i.e. is less than zero), then the integration will begin when all but two antennas arrive on source.
    If, for example, count = 2 (i.e. is greater than zero), then the integration will begin when any two antennas arrive on source.
    The count parameter is only used when waiton = COUNT. Otherwise, the value of count is ignored.
    count is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['count'] unless it is explictly added to the pointing dictionary.
    For example, to begin pointing when all but 3 antennas are on source, set:
```
pointing = { 
   ...
   'waiton' : COUNT,
   'count'  : -3,
   ...
  } 
```
  2. doPoint
    If doPoint is True, then radio pointing is performed on a pointing source if needed.
    The parameters in the pointing dictionary are used to select a pointing source.
    The following criteria are used to determine if pointing is needed:
    1. the last pointing source was more than pointing['interval'] hours ago;
    2. the last pointing source was more than pointing['maxsep'] degrees from the science target;
    3. the last pointing source was on the opposite side of the north/south terminus relative to the science target;
    If either (1), (2), or (3) is True, then radio pointing is performed.
  3. elmax
    elmax is the maximum elevation in degrees to observe a pointing source.
    elmax is a hidden variable that assumes the value and functionality specified in limits['maxElevationCal'] unless it is explicity added to the pointing dictionary.
    Example:
```
pointing = {
   ...
   'elmax' : 80.0,
   ...
  }
```
  4. elmin
    elmin is the minimum elevation in degrees to observe a pointing source.
    elmin is a hidden variable that assumes the value and functionality specified in limits['minElevationCal'] unless it is explicity added to the pointing dictionary.
    Example:
```
pointing = {
   ...
   'elmin' : 30.0,
   ...
  }
```
  5. interval
    interval indicates how often in hours to perform radio pointing within a track. interval may be superceded during the daytime by pointing['intervalDay'].
  6. intervalDay
    intervalDay indicates how often in hours to perform radio pointing within a track during the daytime. Daytime is defined as when the Sun is above 0 degrees elevation. If intervalDay is not set, then it assumes the value of pointing['interval'].
  7. intervalTran
    intervalTran indicates how often in hours to perform radio pointing during the transition period between ±2 hours around sunrise and sunset. During this time period the pointing can change quite rapidly. If intervalTran is not set, then it assumes the value of pointing['intervalDay'].
    intervalTran is a hidden parameter that does not appear in the default template. It has a value of None by default unless it is explictly added to the pointing dictionary.
  8. mapPoints
    mapPoints indicates how many pointing positions in azimuth and elevation are made during a pointing cycle. For example, npos=5 will observe the pointing source at 5 different azimuth positions centered at the source position and 5 elevation positions.
  9. maxsep
    Maximum allowed separation in degrees between the pointing source and the science target. Section How a pointing source is selected discusses the criteria used to select a radio pointing source.
  10. minflux
    The minimum acceptable flux density when selecting a pointing source from the CARMA calibrator catalog. The signal to noise on the pointing calibrator as a function of brightness can be estimated from Equation (1)-(4).
    The flux density is specified for the LO frequency of the science observations, unless pointing['tune95'] is True, in which case 95 GHz is used.
  11. nrepCross
    nrepCross indicates the number of times to repeat the pointing cross observations. Currently the overhead on each pointing cross is about 10 minutes, and it is strongly recommended that investigators use nrepCross=1. If the calibrator is faint, the value of pointing['nrepInt'] should be increased rather than nrepCross.
    nrepCross is a hidden parameter that does not appear in the default template. It has a value of 1 by default unless it is explictly added to the pointing dictionary.
  12. nrepInt
    nrepInt indicates the number of integrations to obtain at each pointing position. The default value of 1 is sufficient for pointing sources brighter than 4 Jy, but may be increased for fainter sources.
  13. preferred
    By default, the script will automatically choose suitable pointing source based on vicinity to the target source, elevation limits, and the minimum flux density. Investigators can indicate the preferred pointing source within the preferred variable.
    For example, if you prefer that the pointing be measured on 3c279 or 3c273, you can set:
```
pointing = {
   ...
   'preferred' : '3c279  3c273'
   ...
  }
```
    This implies that when it is time to point, the script will observe 3c279 if it is above the elevation limit specified by elmin. If it is not, it will then try 3c273, and if that source is not available, the script will automatically choose a suitable pointing source. If not pointing source is found, then pointing is skipped.
  14. sunriseset
    The pointing can change rapidly around sun rise and sun set. If sunriseset is True and pointing['doPoint'] is True, then radio pointing is attempted at sunrise and sunset (define as when the sun is at 0 degrees elevation), and also at ± 2 hours around sunrise and sunset.
  15. tune95
    If True, then the receivers are tuned to 95 GHz before radio pointing. The receivers are set back to the original frequency after pointing.
  16. waiton
    waiton, in combination with pointing['count'], indicates how many antennas should be tracking the source before beginning the integration. The default values are waiton=COUNT and count=-2.
    waiton=ALL means all antennas must be tracking the source before beginning the integration.
    waiton=ANY means that a minimum of two antennas must be tracking the source before beginning the integration.
    waiton=COUNT means that the integration will begin when the number of antennas specified by pointing['count'] arrive on source.
    waiton is a hidden parameter that does not appear in the default observing script. By default, it assumes the value of limits['waiton'] unless it is explictly added to the pointing dictionary.
    For example, to begin pointing when all antennas arrive on source, set:
```
pointing = { 
   ...
   'waiton' : ALL,
   ...
  } 
```
8. primaryFluxCalibrators
  This parameter is used to specify which sources can be used as primary flux calibrators. If False is indicated, the source will not be observed by the script unless it is specified in the fluxcal['preferredPri'] list.
  The primary flux calibrators are Uranus, Neptune, Mars, and MWC 349. Jupiter and Saturn are generally not used as flux calibrators since they often resolved by CARMA on most baselines. Note that the angular size of Mars can vary substantially throughout the year and may not always be an appropriate calibrator depending on the array configuration. The angular diameter of solar system bodies can be looked up using the online calculators at the U.S. Naval Observatory or Jet Propulsion Laboratory (JPL).
  Additional primary flux calibrators can be specified by adding to the primaryFluxCalibrators list or by specifying the source in fluxcal['preferredPri'].
9. projectInfo
10. sources
11. tuning

Last updated: March 22, 2007 by John Carpenter

Frequently Asked Questions : Editing Observing Scripts

Contents

Answers to frequently asked questions