Facilities > VLA > Documentation > Manuals > OPT > Text Files and Catalogs in the OPT

Text Files and Catalogs in the OPT

« Return to page index

Observation Preparation Tool (OPT)

1. Text Files

Apart from direct manual editing in the fields exposed by the web interface, all components of the OPT web application can import and export ASCII text files that, e.g., can be created and manipulated or optimized by computer programs or scripts outside the OPT web application.

A source list can be prepared from external source catalogs and formatted such that the SCT can ingest it, or a source list can be exported to a text file. Similar catalog operations can be performed on resource catalogs as well.  Furthermore, (re)source lists can be extracted from an existing scheduling block and can be shared or loaded in either the RCT or the SCT.  The OPT can read and write scan lists or ingest script-generated scheduling blocks, etc.

This section describes the syntax that might be of interest to most users of this feature: importing source lists into the SCT and importing scan lists or complete scheduling blocks into the OPT. A properly formatted standardized list of spectral lines is also provided for upload. To be able to read in scans or scheduling blocks into the OPT without overloading the individual entries with too many variables, the source and resource catalogs must be defined beforehand (so that the scan parser can grab the (re)source definitions from the existing catalogs). If only VLA calibrators and NRAO default resources are required, no other additional (re)source catalogs need to be defined.

The following sections in this chapter of the OPT manual describe the syntax for importing source lists into the SCT, and for importing scan lists and scheduling blocks into the OPT. For information about importing source lists into the Proposal Submission Tool (PST), see the Sources Section of the PST manual.

 

General Syntax

The import of text files is accomplished by parsing each line, where each line is assumed to define a complete instruction. Parsing occurs for plain ASCII characters so if a rich-text capable text editor is used (e.g., Word) please save without rich-text formatting in plain ASCII text or the import will fail without an error message. Empty or whitespace-only lines and lines where the first non-whitespace character is a hash (# symbol) are ignored. That is, hashes may be used to insert comments in the text file. Typical lines will have input fields delimited by semi-colons (;), where multi-variable fields have their variables separated by commas (,). The comma after the final value of a field is optional, but the final semi-colon after the final field is mandatory (except for spectral line lists). Leading and trailing whitespace around field variables is ignored, but whitespace between the first and last non-whitespace character of a variable is preserved (see examples). Optional fields may be left unspecified (i.e., no characters or whitespace-only characters) and will be assigned a default value where appropriate. Character fields are treated as case-sensitive unless otherwise specified. Illegal characters in (free-format text) fields are non-printable (tab) characters, including any form of end-of-line characters, variable delimiters (semi-colon and comma) and any of the specified ones in the table below; leading and trailing whitespace around free-format text variables is ignored, but whitespace within freeformat text is preserved. The full list of acceptable and illegal characters in free-format text fields is:

Acceptable characters
a-zA-Z lower and upper case letters
0-9 digits
space
+ - . = plus, minus, period/decimal and equal signs
/ _ # * slash, underscore, hash/sharp and "star"
( ) [ ] open/close parentheses and square braces
Illegal characters
' " single quote and double quote
{ } curly braces
< > less than and greater than

end-of-line and non-printable characters (e.g. "tab"),

rich-text formatted text or other non-ASCII characters

\ @ % $ backslash, at, percent and dollar signs
` ~ ! ^ & | : , ; other textual and linguistic characters

2. Source Lists

Syntax

Text files with source lists can be imported into the SCT (and PST) if they use the following syntax. Every line containing any source information in the file must define a separate source as:

sourceName;groupNames;coordSystem;epoch;longitude;latitude;refFrame;convention;velocity;calibrator;

The text file should only contain lines formatted as above, or lines that are known to be ignored by the parser (i.e., empty or whitespace-only lines and comment lines starting with a #-hash). An (optional) exception is if the very first line is starting with a *-star; the string after the star will replace the default source catalog name. Start with the catalog name syntax line before any source syntax line or any comment line or this source catalog name will not be picked up (and an "Unnamed Catalog" results):

* Source catalog name in the SCT
# this is a line with a comment and the previous line is the syntax used to include all sources into a non-default
# (the catalog name line will be ignored by the PST when uploading this file)
# the rest of the source list file contains source lines mandated as above and other ignored lines
<source1 line>
<source2 line>
...

Every data line must have ten semi-colons (;) , including the one after the final calibrator field. Details and possible (predefined) values per field are described here:

sourceName Mandatory, single value
Unique name for the source, free-format text. Multiple lines with the same source name, longitude, latitude and velocity information (below) will end up as a single source entry
groupNames Optional, unlimited number of comma-separated values
Group(s) or sub-catalog(s) to which this source belongs, free-format text. If no group name is given the source will be listed in the main (top-level) catalog only
coordSystem Optional, single value (defaults to equatorial), not case-sensitive
Coordinate system in which longitude and latitude angles below are defined, typically Equatorial for source coordinates in RA and Dec. (the default). Valid options are: Ecliptic, Equatorial, Galactic. Sources converted to other, e.g., equatorial coordinates will show an asterisk with the converted coordinates in the catalog
epoch Optional, single value (defaults to J2000), not case-sensitive
Epoch for which longitude and latitude angles below are defined, valid options are: B1950, J2000
longitude Mandatory, single value
An East-West angle, typically Right Ascension. Valid options are a numerical value in decimal degrees or a sexagesimal colon-delimited value in hh:mm:ss.sss. . . (with or without leading zeros) for hours : minute : seconds. Either form may be preceded by the plus (+) or minus (−) sign
latitude Mandatory, single value
A North-South angle, typically Declination. Valid options are a numerical value in decimal degrees or a sexagesimal colon-delimited value in dd:mm:ss.ss. . . (with or without leading zeros) for degrees : arcminute : arc-seconds. Either form may be preceded by the plus (+) or minus (−) sign
refFrame Mandatory in combination with convention and velocity, single value, not case-sensitive
The reference frame in which the velocity below should be interpreted. If any of refFrame, convention or velocity is specified, all three must be specified to make sense. Leave all three blank if no velocity information should be included in the source properties. Useful valid options with their abbreviations are: Barycentric (Bary), LSR Kinematic (LSR or LSRK), Topocentric (Topo)
convention Mandatory in combination with refFrame and velocity, single value, not case-sensitive
The frame definition in which the velocity below should be interpreted. Useful valid options are: Optical, Radio, Redshift
velocity Mandatory in combination with refFrame and convention, single value
A decimal number, optionally preceded by the plus (+) or minus (−) sign, to express the source velocity in km/s, or to express the source redshift in z if the convention above is Redshift
calibrator Optional single value (defaults to N), not case-sensitive
A value of Y or N to indicate whether a source is to be used as calibrator. The SCT will ignore this field; it is retained to maintain compability with the PST and other tools. Instead, calibrators for the VLA are identified with scan intents in the OPT.

 

To ingest a text file with a source list, navigate to the SCT. Select from the menu FILE - IMPORT and then PST for the import format. After providing a file to import, a new catalog with the default name “[Unnamed Catalog]” will be created. If the imported sources need to be included in a different catalog, or a different catalog group, use the general copy/paste method of the OPT web application to move the sources around. Alternatively, change the name of the new unnamed catalog in the SCT using the "Properties" tab of that catalog if a name was not specified with a *-star line.

Source List Examples (in SCT/PST format)

Minimalist. Source name and coordinates only, default coordinate system, epoch and unspecified velocity:

J0433+0521;;;;04:33:11.095535;05:21:15.619420;;;;;
J1119−0302;;;;11:19:25.3;−03:02:51.32;;;;;
<some_name> <4 times ";"> <RA_j2000> ; <Dec_j2000> <5 times ";">


Explicit. Same data as minimalist, above, but with coordinate system and epoch stated in long form, and spaces for ease of reading:

J0433+0521; ; equatorial; J2000; 04:33:11.095535;  05:21:15.619420; ; ; ; ;
J1119−0302; ; equatorial; J2000; 11:19:25.3 ; −03:02:51.32 ; ; ; ; ;


Full. All fields are specified, starting by naming the catalog "MyPrivateList" in which these sources should appear (instead of the default "Unnamed Catalog"); multiple values in those fields that allow it, with spaces in source and group name, some case-preserved and case-ignored variable names, and with optional trailing comma in velocities.

* MyPrivateList
# This is my private list of secret sources..
Secret Source; My Recipes, Private; equatorial; J2000; 12:34:56.789; 87.65432; lsR; Optical; −98.6,; y;

3. Importing Scheduling Blocks

Scheduling Blocks and Scan Lists

First, note the differences between importing scan lists and importing complete scheduling blocks:

  • A text file representing a complete scheduling block (SB) defines not only the scan list, but also defines the variables needed for a scheduling block
  • Importing scheduling blocks will create a new SB entry in the active Program Block, whereas importing a scan list will add the scans to an active Scheduling Block directly after the active scan, or at the start if the active field is the SB name.

In this section we discuss the scheduling block preamble, and in the next we describe importing scan lists. Note that we are creating experimental scripts that take an ordered list of source names and produce a text file for import into the OPT. This should be helpful to create simple observing schedules. Please let the NRAO Helpdesk know if you are interested in trying this out.

 

Scheduling Block Preamble

A text file defining a scheduling block has to begin with the following case-sensitive content (boldface lines are mandatory):

VERSION;versionNumber;
SCHED-BLOCK;schedBlockName;schedulingType;iterationCount;date;timeOfDay;shadowLimit;. . .
. . .shadowCalcConfiguration;initTeleAz;initTeleEl;avoidSunrise?;avoidSunset?;. . .
. . .windApi;commentsToOperator;


The VERSION line is optional, but if present it must be the first data line and include an integer versionNumber in the second field between two semi-colons (;). The current maximum versionNumber is 3. If the line is omitted, versionNumber defaults to the latest version of the syntax.

The SCHED-BLOCK line distinguishes a complete scheduling block input text file from a scan list input text file.  Only a single SCHED-BLOCK line is allowed in the file and has to precede any scan list lines (below). If it is not present the file will be interpreted as a scan list only file as described later. Apart from the data field identifier “SCHED-BLOCK”, this line includes 13 fields and exactly 14 semi-colons (;), including the last. Details and possible (predefined) values per field are described in the table below. Note that unless specified otherwise, the parsing of strings is case sensitive:

schedBlockName Optional, single value (defaults to [New Scheduling Block])
Name to give to the scheduling block, free-format text
schedulingType Optional, single value (defaults to Dynamic), not case-sensitive
Scheduling type, valid options are: Dynamic, Fixed
iterationCount Optional, single value (defaults to 1)
Integer, maximum number of times to observe the scheduling block (Dynamic scheduling type only)
date Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type
Fixed: an observing date, either in "yyyy-mm-dd" format for UTC or a five-digit integer that is interpreted as the VLA LST day (e.g., 2012-07-25 or 62859). The parser will bail out of creating the scheduling block if this date is not in the future
Dynamic: if provided, the earliest and latest UTC date and time that this scheduling block may be run; must be formatted as "yyyy-mm-dd hh:mm:ss, yyyy-mm-dd hh:mm:ss" where the ending date and hh:mm:ss parts are optional. If nothing is provided it defaults to the date that the OPT scheduling block is created for the early start, and a date far in the future for the latest start
timeOfDay Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type
Fixed: time of day in hh:mm:ss format at which the schedule must start. If the date is in yyyy-mm-dd format the time is interpreted as UTC but if the date is a five-digit integer (i.e., without thousand-separators) it will be interpreted as LST.
Dynamic: a comma-separated list of LST start ranges where each range takes the form “hh:mm - hh:mm” where all whitespace is ignored. It defaults to “00:00-24:00” which is only sensible for a scheduling block with only circumpolar sources (Declination > 64 degrees). This implies that any dynamic scheduling block with a standard VLA flux calibrator needs a non-default LST start range
shadowLimit Optional, single value (defaults to 0.0)
Numerical value in meters (0 to 25) for issuing shadowing warnings in the scheduling block report when an antenna is shadowed by another by this value or more
shadowCalcConfiguration Optional, single value (defaults to the first array configuration in the Program Block)
The array configuration for which the above shadowing calculation is performed. Valid values: A, B, C, D and Any (case-sensitive!). "Any" implies calculations for the worst case, i.e., "D". When provided, the array configuration has to match one of the array configurations in the program block or it will revert to the default value. The hybrid configurations (e.g., BnA) are also allowed but not in use anymore
initTeleAz Optional, single value (defaults to 225)
Assumed antenna pointing direction in degrees Azimuth at the start of the observation, used to calculate slewing time to the first source. Valid range: −85.0 to +445.0, where an Azimuth of 180° points toward the south
initTeleEl Optional, single value (defaults to 35)
Assumed antenna pointing direction in degrees Elevation at the start of the observation, used to calculate slewing time to the first source. Valid range: +8.0 to +90.0, where an Elevation of 90° points toward the Zenith and where the lower Elevation limit is 8.0°
avoidSunrise? Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed
Should this scheduling block avoid observing at sunrise, i.e., should this scheduling block not overlap in time between 10 minutes before and 60 minutes after the actual sunrise time? Valid values: Y, N. This field must be left blank for Fixed time scheduling blocks
avoidSunset? Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed
Should this scheduling block avoid observing at sunset, i.e., should this scheduling block not overlap in time between 10 minutes before and 60 minutes after the actual sunset time? Valid values: Y, N. This field must be left blank for Fixed time scheduling blocks
windApi Mandatory for Dynamic scheduling type, single or dual value; leave blank for Fixed
The maximum allowable wind speed and atmospheric phase fluctuations that are allowed to start observing this scheduling block. Valid entries are either the (case-sensitive!) character designations per observing band (Q, Ka, K, Ku, X, C, S, L or Any - for sub-GHz use Any), which provide pre-defined wind and API limits, or a direct numerical entry for both wind speed (in m/s) and API rms phase (in degrees) as a dual-valued entry.  The format for the latter is “w=#,p=#” (w and p in lower case) with # an appropriate non-negative numerical value (wind < 18 m/s, rms phase < 180 deg). Whitespace and reverse order are allowed as long as both variables with values are explicitly specified. This field must be left blank for Fixed time scheduling blocks
commentsToOperator Optional, single value
Comments to the operator, free-format text

 

To ingest a text file with a scheduling block, navigate to the OPT and activate (click) the program block or a scheduling block in the program block in which the new scheduling block should be placed. Select from the menu FILE - IMPORT SCHEDULING BLOCK. After providing a file name to import, a new scheduling block with the default name “[New Scheduling Block]” will be created if no predefined name is given in the first field of the SCHED-BLOCK line. Note that if FILE - IMPORT SCHEDULING BLOCK is grayed out, the wrong item in the project tree is selected (e.g., a scan).

Scheduling Block preamble Examples

Version line and fixed date observing specified in VLA LST day and time:

VERSION; 3;
SCHED-BLOCK; Orion Neb; Fixed; ; 72987; 13:45:30; ; ; ; ; ; ; ; Coord w/ HST;

Dynamic observing, with repeat, multiple LST start ranges, shadow calculations and weather settings for X band, and avoid sunset and sunrise with a comment to run with 20 antennas or more.

SCHED-BLOCK;Orion;Dynamic;3;2012-08-11;09:30-13:00,18:00-00:30;0;;180;45;y;y;X;>=20 antennas;

Absolute minimum specifies mandatory wind and API for Dynamic blocks with the receiver letter code only (but then one would be wise to edit the scheduling block name, etc., directly in the OPT).

SCHED-BLOCK;;;;;;;;;;;;Ka;;

Absolute minimum for a Fixed scheduling block includes a fixed starting time (here in LST) at the VLA.

SCHED-BLOCK; ; Fixed ; ; 72859 ; 08:45 ;;;;;;;;;

4. Importing Scan Lists

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>

5. RCT Spectral Line Lists

Syntax

The RCT uses rest frequencies and corresponding spectral line definitions when attempting to set up the WIDAR correlator and populate the subbands in the basebands. Filling out the line parameters takes some effort and has to be repeated for each new resource. Therefore, in the resource lines tab in the RCT, it has a feature to export and import line definitions using plain (editable) text files. Note that the main intended use is to export lines from one resource to import in another, not to create one from scratch (we give no guarantees that it will be parsed properly in that case). Another item to note is that the source position for Doppler setting is not retained in the text file export and thus cannot be defined for text file import. Note that we created a template at the bottom of this page. Every line containing any spectral information in the file must use the following syntax:

lineName;restFreq;refFrame;convention;velocity;velRange;velSep;polProd;other

The text file should only contain lines formatted as above, or lines that are known to be ignored by the parser (i.e., empty or whitespace-only lines and comment lines starting with a #-hash). Every data line must have eight semi-colons (;), which means that there is none after the final field. Multi-value fields use commas as item separators. Details and possible (predefined) values per field are described here:

lineName Mandatory, single value
Name for the setup definition, free-format text, e.g., "SiO v=1"
restFreq Mandatory, single value larger than zero, unit defaults to GHz
Rest frequency of the line to place, e.g., "43.122GHz". Note that a unit should not be separated from the value (i.e., no space between them). MHz, kHz and Hz are also accepted
refFrame Mandatory, single value, not case-sensitive
The reference frame in which the velocity below should be interpreted. Useful valid options with their abbreviations are: Barycentric (Bary), LSR Kinematic (LSR or LSRK), Topocentric (Topo)
convention Mandatory, single value, not case-sensitive
The frame definition in which the velocity should be interpreted. Useful valid options are: Optical, Radio, Redshift
velocity Mandatory, single value, unit defaults to km/s
A decimal number, optionally preceded by the plus (+) or minus (−) sign, to express the source velocity in km/s (or m/s), or to express the source redshift in Z if the convention above is Redshift. For Redshift including the unit "Z" is a must, e.g., "0.0443Z"
velRange Mandatory, single value larger than zero, unit defaults to km/s, value defaults to 100 (i.e., 100.0km/s)
The minimum velocity range, in km/s (or m/s), that this line should cover when converted to a subband. Essentially this is the subband width, in units of Hz, that is the upper rounded power of two matching this velocity range
velSep Mandatory, single value larger than zero, unit defaults to km/s, value defaults to 1 (i.e., 1.0km/s)
The maximum spectral channel separation, in km/s (or m/s), that this line should sample when converted to a subband. Essentially this is the channel width, in units of Hz, that is the lower rounded power of two matching this velocity sampling. Note that a small value may not be possible without requesting recirculation, as the maximum number of channels per subband (of any width) is 256 divided by the number of polarization products (see next)
polProd Mandatory, multi-value, not case-sensitive
Number of polarization products recognized as FULL, DUAL or a comma separated list of LL, RR, RL, LR. For linear polarization use either FULL or DUAL
other Optional, multi-value, not case-sensitive
This is a grab-all for other pre-defined items that can be specified. Currently it is only used to specify whether the line setup tool should attempt make use of recirculation or not. These options currently are parsed as "USE_RECIRCULATION=true" or "USE_RECIRCULATION=false" respectively. Using recirculation will put a smaller strain on the requirements for baseline board pairs. Note that this is not a comments field for personal notes

To export a line list from a resource, navigate to the lines tab for the resource in the RCT. At the bottom of the tab, use the "Download Spectral Lines" button. Similarly, use the "Import Spectral Lines" button to attach line definitions to a resource. In the latter case do not forget to specify the source position used for Doppler setting.

Spectral Line List Example

This is a single line list as exported from the RCT. A text editor can be used to add lines using the same syntax to be loaded back in to a (new) resource. Note that there is no space between values and units, and that there is no hook to specify the Doppler position.

# Line name ; Rest frequency ; Rest frame ; Velocity convention ; Velocity ; Minimum range ; Channel separation ; Polarization products ; Additional specifications
Google X; 14.99GHz; Barycentric; Optical; 87801.0km/s; 303.0km/s; 0.07km/s; DUAL; USE_RECIRCULATION=true

As a service, we have compiled a list of important lines (according to the IAU), supplemented with lines commonly observed with the VLA below. Copy/paste the lines of your interest (or the whole list) in a text editor to modify according to your specific requirements. Then upload the modified lines, after creating a new 8-bit or 3-bit resource in the RCT, using the resource Lines tab and "Import Spectral Lines" at the bottom of that tab.

IAU line frequency list formatted for the VLA OPT/RCT

#The IAU list of important spectral lines (www.craf.eu/iaulist.htm) below 120 GHz, supplemented by selected
#lines from the Lovas catalog (physics.nist.gov/cgi-bin/micro/table5/start.pl) below 50 GHz.
#Other lines can be obtained from the web pages above or e.g. the Splatalogue (www.cv.nrao.edu/php/splat/)
#
# Line name ; Rest frequency ; Rest frame ; Velocity convention ; Velocity ; Minimum range ; Channel separation ; Polarization products ; Additional specifications
#
#  --  P band  --
D;       327.384MHz; Topo; Redshift; 0.01Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  L band  --
H;      1420.406MHz; Topo; Redshift; 0.01Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     1612.2310MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     1665.4018MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     1667.3590MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     1720.5300MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  S band  --
CH;     3263.794MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH;     3335.481MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH;     3349.193MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  C band  --
OH;     4660.242MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     4750.656MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     4765.562MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
H2CO;   4829.6639MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     6016.746MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     6030.747MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     6035.092MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     6049.084MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH;  6668.5192MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     7761.747MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     7820.125MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  X band  --
OH;     8135.870MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;     8189.587MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
3HeII;  8665.650MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  Ku band  --
CH3OH; 12178.593MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;    13434.596MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
OH;    13441.4173MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
H2CO;  14488.4801MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  K band  --
SiS;   18154.888MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
C3H2;     18.343GHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 19967.396MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
H2O;   22235.1204MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 23121.024MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   23694.4700MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   23722.6336MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   23870.1296MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   24139.4169MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   24532.9887MHz; LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 25018.123MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   25056.025MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 25124.872MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   25715.182MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  Ka band  --
NH3;   26518.981MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   27477.943MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
NH3;   28604.737MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 36169.290MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiS;   36309.627MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 37703.696MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 38293.292MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 38452.653MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  Q band  --
SiO;   42519.375MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;   42820.570MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;   42879.941MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;   43122.090MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;   43423.853MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CH3OH; 44069.476MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CS;    48990.955MHz;  LSR; Radio;    0km/s; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
#  --  Only Redshifted lines  --
DCO+;     72.039GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;      86.243GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
H13CO+;   86.754GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
SiO;      86.847GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
C2H;      87.300GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
HCN;      88.632GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
HCO+;     89.189GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
HNC;      90.664GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
N2H;      93.174GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CS;       97.981GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CO;      109.782GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CO;      110.201GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CO;      112.359GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true
CO;      115.271GHz; Topo; Redshift; 2.00Z; 10km/s; 5km/s; Dual; USE_RECIRCULATION=true