Importing Scan Lists

by Gustaaf Van Moorsel last modified Sep 21, 2017 by Lorant Sjouwerman

Scan lists

To define a scan list, the standard case-sensitive(!) text file content must start with (boldface lines are mandatory):

SRC-CAT;sourceCatalogNames;
HDWR-CAT;hardwareCatalogNames;

These catalog lines must be included before any scan line described below, and currently also before the SCHEDBLOCK line described from the previous section.  The following table contains a more extensive description:

type of linefielddescription
SRC-CAT sourceCatalogNames Mandatory, multi-value
Comma-separated list of names of source catalogs in order of priority, highest priority first. Source names below must be pre-defined with source properties in at least one of the included catalogs, where the first match will be the one that defines the source in this scan. In practice, one would list the personal source catalogs containing sources for this scheduling block and end with the standard “VLA” calibrator catalog if the calibrators to be used were not copied to the personal catalog
HDWR-CAT hardwareCatalogNames Mandatory, multi-value
Comma-separated list of names of resource catalogs in order of priority, highest priority first. Resource names below must be pre-defined with resource properties in at least one of the included catalogs, where the first match will be the one that defines the resource in this scan. In practice, one would list the personal resource catalogs containing resources for this scheduling block and end with the standard “NRAO Defaults” (note the upper-case D in Defaults) catalog for continuum and pointing setups

 

Text files with scan lists can be imported into the OPT if they use the following syntax. Every line containing any scan information in the file must define a separate scan as one of the following options:


STD;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark5?;allowOverTop?;scanIntents;comments;

PTG;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark5?;allowOverTop?;comments;
TIP;scanName;azimuth;resourceName;tippingOrder;comments;
OTFM;scanName;sourceName(beg);sourceName(end);resourceName;timeType;time;numSteps;numIntPs;. . .
. . .RAdirection;antennaWrap;applyRefPtg?;applyPhase?;recordOnMark5?;allowOverTop?;comments;

Standard, Pointing, and On-the-fly Mosaicking mode scans

Standard observing mode, or STD-scans, require 12 additional fields (in the numbered order below) and 13 semicolons (;), including the last. Pointing mode scans, or PTG-scans, necessary only for observations at the higher frequencies (Ku, K, Ka, Q), have 11 additional fields and 12 semi-colons (;), including the last. Similarly, Tipping mode scans, or TIP-scans, are described with 5 additional fields and 6 semi-colons (;), including the last. On-the-fly Mosaicking (OTFM) scans are defined with 15 additional fields and 16 semi-colons. The following table contains a more extensive description of the fields for STD, PTG or OTFM lines::

order field description
STD PTG OTFM
1 1 1 scanName Optional, single value (defaults to the source name (below) or [New Scan])
The name to be given to the scan
2 2 2, 3 sourceName Mandatory, single value
A source name with its properties (such as sky coordinates) must pre-exist in one of the source catalogs included in the list in sourceCatalogNames in the SRC-CAT line. If you use an alias (B1950, NGC, 3C, Messier name, etc.) as source name instead of the standard 10-digit J2000 calibrator or target name in your scheduling block, please make sure to include this source name with the J2000 coordinates in one of your listed source catalogs. Note that for OTFM-scans, both a beginning and end source position name must be entered in two different columns. Also be alerted that calibrators in the VLA catalog use capital letters (J#, and 3C# for the standard flux density calibrators) in their designation
3 3 4 resourceName Mandatory, single value
A resource name with its properties (such as receiver observing band, etc.) must pre-exist in one of the resource catalogs included in the list in hardwareCatalogNames in the HDWR-CAT line. The special term prev (not case-sensitive) can be used to indicate that there is no resource change from the previous scan, though this term is not allowed in loops
4 4 5 timeType Optional, single value (defaults to Duration LST), not case-sensitive
The timing method used for the scan. Valid options with their 3-letter abbreviations are: Duration (LST) or DUR, On-Source (LST) or SRC, Stop Time (LST) or END, Duration (UT) or UTD, On-Source (UT) or UTS, Stop Time (UT) or UTE
5 5 6 time Mandatory, single value
Time measure for the scan, typically a scan length in the form of hh:mm:ss.s or αhβmγs, but for stop times an absolute hh:mm:ss.s time of (LST or UT) day. Note that 01:02 is interpreted as 1h 2m, and that 01:2.0 is interpreted as 1m 2.0s so it is safest to use the full h:m:s format with two colons (:) or explicitly write it as 1m 2.0s (with or without spaces) if that is what is meant
- - 7 numSteps Mandatory, single value
The number of steps, number of phase centers along a strip or stripe. See the OTFM mode description on the special modes page (OPT, section 5)
- - 8 numIntPs Mandatory, single value
The number of integrations per step, per phase center. See the OTFM mode description on the special modes page (OPT, section 5)
9 RAdirection Mandatory, single character
For any two points in the sky there is a shortest path between them in RA as well as a path to go the other way and take the long slew in RA (there is only one way allowed in Dec, the shortest way). Using the character '0' (zero) will select the shortest path between the starting point (2nd parameter) and the end point (3rd parameter). To explicitly fix the motion in RA, use a plus or a minus sign to observe in increasing RA direction ('+') or in decreasing RA direction ('-'), respectively. Valid values: +, -, 0 (zero)
6 6 10 antennaWrap Optional, single value (defaults to No Preference), not case-sensitive
Specified antenna azimuth wrap for the scan. Valid values: R, CW, Clockwise, No Preference, L, CCW, Counterclockwise
7 7 11 applyRefPtg? Mandatory, single value, not case-sensitive
Should this scan use previously determined reference (antenna) pointing offsets? Needs a preceding PTGscan to be effective. Valid values: Y, N
8 8 12 applyPhase? Optional and only for phased VLA observations, single value (defaults to N), not case-sensitive
Should this scan use previously determined delay and phase (autophasing) solutions? Needs a preceding STD-scan with DetAutoPh intent (see below) to be effective, and usually not used. Valid values: Y, N
9 9 13 recordOnMark5? Optional and only for phased VLA VLBI observations, single value (defaults to N), not case-sensitive
Does this scan need recording for correlation with other antennas? Do not use unless you know what this means and you really need it. Valid values: Y, N
10 10 14 allowOverTop? Optional, single value (defaults to N), not case-sensitive
Allow the antennas to tip to the other side of the zenith, to Az+180? Do not use unless you know what this means and you really need it. Valid values: Y, N
11 - - scanIntents (STD-scan only) Mandatory, multi-value, not case-sensitive

All intents for each scan should be listed. The full list of intents, including all intents for operations, is collected in the documentation mentioned above. The most useful valid options for normal observing, with their full meaning in parentheses are:
ObsTgt (observe the target, usually not combined with any other intent),
CalGain (calibrate phase and amplitude gains together, in particular for standard calibration loops on the target source),
CalFlux (determine the absolute flux density calibration, typical on the handful of standard VLA flux calibrator sources),
CalBP (bandpass calibration on a strong continuum source),
SetAtnGain (set various types of antenna gains),
CalDelay (delay calibration if the bandpass calibration scans are not suitable for delay calibration, or to explicitly name a scan for this purpose),
CalPolAng (scan on a source with a known polarization angle for calibration of the absolute polarization angle in polarized target sources),
CalPolLeak (calibration scans to resolve the differences and cross-contamination between the two orthogonally measured polarizations).

Note that the separate scan definition for a pointing scan or OTF only differs from a standard scan because the scan intent is fixed for those scans; pointing scans may indeed also be phased up and recorded for VLBI correlation

12 11 15 comments Optional, single value
Any comments for personal use such as reminders or purpose, free-format text

 

Note that in principle only a single one of STD/PTG/TIP/OTFM scans in the scan list is required, but it does not make sense to not have any STD-scan in a normal observation scheduling block.

Tipping mode scans

Please note that tipping scans currently are not supported. They are being re-implemented as continuous (versus discrete) tipping scans - this section will change in the near future as it reflects the implementation as it was in the past. If you have questions about using TIP-scans please consult the NRAO Helpdesk.

Tipping mode scans will use a fixed scan length of 5 minutes to be able to derive a useful measurement and therefore have no scan timing field. The following table contains the fields expected on a TIP line:

orderfielddescription
1 scanName Optional, single value
The name to be given to the scan
2 azimuth Mandatory, single value
Numerical value in degrees azimuth at which a tipping scan should be performed. Valid range: −85.0° to +445.0°
3 resourceName Mandatory, single value
A resource name with its properties (such as receiver observing band, etc.) must pre-exist in one of the resource catalogs included in the list in hardwareCatalogNames in the HDWR-CAT line. The special term prev (not case-sensitive) can be used to indicate that there is no resource change from the previous scan, though this term is not allowed in loops
4 tippingOrder Mandatory, single value, not case-sensitive
Elevation movement while performing the tipping scan. Valid values: Up or Low To High, Down or High To Low in elevation (underscores may be omitted). Scan length will be fixed to 5 minutes
5 comments Optional, single value
Any comments for personal use such as reminders or purpose, free-format text

Scan loops

Loops of scans can be defined (with 4 additional fields and 5 semi-colons) and nested without limitation, and every LOOP-START line must have a corresponding LOOP-END (with no other fields and a single semi-colon). The uppermost unpaired LOOP-END is taken to end the lowermost unpaired LOOP-START.

LOOP-START;loopName;iterationCount;bracketed?;comments;
[some STD-scans and/or PTG-scans, TIP-scans, nested loops, etc.]
LOOP-END;

The following table describes fields expected on a LOOP-START line:

orderfielddescription
1 loopName Optional, single value (defaults to [New Loop])
Name of the loop, e.g. to remind oneself of the content when collapsed in the scheduling block tree
2 iterationCount Mandatory, single value
Integer number, maximum number of times to observe the loop of scans at this point in the schedule
3 bracketed? Optional, single value (defaults to N), not case-sensitive
Specifies whether the loop is a “bracketed” loop, i.e., whether the first scan of the loop is repeated at the very end of all loop iterations. Valid values: Y, N
4 comments Optional, single value
Any comments for personal use such as reminders or purpose, free-format text

Importing a scan list

To ingest a text file with a scan list, navigate to the OPT and activate (click) the scheduling block or a scan in the scheduling block in/after which the new scans should be placed. Any lines relating to the scheduling block preamble will be ignored at this stage. Select from the menu FILE - IMPORT SCANS. After providing a file name to import, scans will be appended directly after the activated field, i.e., at the beginning of a scheduling block if the scheduling block is active, or after the activated scan. The imported scans can be moved around with the the general copy/paste method of the OPT web application.


Examples

Following are some very simple examples for 8-bit correlator modes; for 3-bit modes additional setup scans are needed and may be recommended for 8-bit as well. An example of an OTFM scheduling block is given in the OPT manual, OTFM section.

Example of a scan list with two (8-bit) low-frequency science resources (thus no pointing) starting with target observing and ending with flux calibration scans at the end of the observation:


# Start with defining which pre-defined source and resource catalogs to use
SRC-CAT; My Sources, VLA;
HDWR-CAT; My Resources, NRAO Defaults;
#
# Two one-minute 8-bit frequency setup scans, CW wrap, no cal.intents
STD; setupDummy1; J1404+6551; L full width; dur; 0:01:0.0; CW;n; ; ; ; SetAtnGain,;dummyL ;
STD; setupDummy2; J1404+6551; my S band; DUR; 0:01:0.0; CW;N; ; ; ; SetAtnGain;dummyS;
#
# Account for slew and wrap, may take ten mins minus above, alternate flux calibrator
LOOP-START; finish 10min startup loop; 2; N; ;
STD; ; J1404+6551; my S band ; ; 0:2:0; CW; N;;; ; CalGain;;
STD; ; J1404+6551; L full width; ; 0:2:0; CW; N;;; ; CalGain;;
LOOP-END;
#
# Target observing loop; save on some slewing time
LOOP-START; target+cal both freqs; 15; N; ;
LOOP-START;19min scan; 2; ;keep scans under 10min by repeating it;
STD; ; source1atL; L full width; ; 0:09:30.0;; N;;;; ObsTgt,,; ;
LOOP-END;
STD; ; source2atS; my S band; ; 0:07:30.0;; n;;;; ObsTgt,,; ;
STD; calS; J1404+6551; my S band ; ; 0:2:0; ; n; ;;; CalGain; ;
STD; calL; J1404+6551; L full width; ; 0:2:0; ; N; ;;; CalGain,;;
LOOP-END;
#
<etc>
#
# Slew to the flux calibrator, needs some extra time on first scan, deal with wrap issues
STD ; L FXBP ; J1331+3030 ; L full width; ; 0:07:20 ; CW; N; ; ; ; CalBP, CalFlux ; ;
STD ; S FXBP ; J1331+3030 ; my S band ; ; 0:2:0 ; CW; N; ; ; ; CalBP, CalFlux ; ;

Example of the start of a scan list with two (8-bit) high-frequency science resources, pointing and flux calibration at the start of the observation:


# Start with defining which pre-defined source and resource catalogs to use
SRC-CAT; My project sources, VLA;
HDWR-CAT; HIGHFreqCat, NRAO Defaults;
#
# Two one-minute 8-bit frequency setup scans, CCW wrap, no cal.intents
STD; setup–Q; J0137+3309; Q wide band; dur; 0:01:0.0; CCW;n;; ; ;SetAtnGain,;dum setup;
STD; setup–A; J0137+3309; special ka band; dur; 0:01:0.0; CCW;N;;; ; SetAtnGain;dum;
#
# Account for slew, add time for pointing, may take twelve mins minus above
PTG; pointing ; J0137+3309 ; Primary X band pointing; ; 0:10:0 ; CCW; N; ; ; ; ;
#
# Standard calibration, note the “Y” to apply pointing solutions
STD ; Q FXBP ; J0137+3309 ; Q wide band; ; 0:1:30 ; ; y; ; ; ; CalBP, CalFlux ; ;
STD ; A FXBP ; J0137+3309 ; special ka band; ; 0:1:30 ; ; Y; ; ; ; CalBP, CalFlux ; ;
#
# Slew to calibrator, need to do a new pointing scan (should have >2:30 on source for all start LST)
PTG; pointing ; TargPTG ; Primary X band pointing; ; 0:6:20 ; ; N; ; ; ; ;
#
# Bracketed loop in first frequency, switch on reference pointing
LOOP-START; qloop; 17; y; ;
STD; ; TargCAL ; Q wide band; ; 0:1:0; ; Y;;; ; calgain; ;
STD; ; myTarget; Q wide band; ; 0:2:30; ; y;;; ; obstgt;;
LOOP-END;
#
# New pointing scan (should have >2:30 on source for all start LST)
PTG; pointing ; TargPTG ; Primary X band pointing; ; 0:2:50 ; ; N; ; ; ; ;
#
# Non-bracketed loop to account for extra time to slew from pointing
STD; ; TargCAL ;special ka band;;0:1:20;;y;;;;calgain;;
LOOP-START; Ka-loop; 13; n; ;
STD;;myTarget;special ka band;;0:2:30;;Y;;;;obstgt;;
STD;;TargCAL ;special ka band;;0:1:00;;y;;;;calgain;;
LOOP-END;
#
<etc>