Text Files and Catalogs in the OPT Suite
1. Text Files
Apart from direct manual editing in the fields exposed by the web interface, all components of the OPT Suite (i.e., OPT, RCT, SCT) 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 Suite.
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 section of the OPT manual describe the syntax for importing source lists into the SCT, naming resources in the RCT, 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 Proposal Submission Guide. RCT resources, but only in XML format, are imported similarly.
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. Prohibited 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 prohibited characters in free-format text fields in the OPT Suite is given in the table below. Note the differences of accepted characters when using the VLA CASA Pipeline (prohibited characters would not appear in the data processing stage when the OPT is used); it may be best to avoid OPT Suite accepted characters (only) in observer and source names that are not accepted by the VLA CASA Pipeline, i.e., [ and ] nor #, and probably also parentheses:
OPT Suite acceptable characters* | VLA CASA Pipeline notes (if different from OPT Suite)** | ||
---|---|---|---|
a-z A-Z | lower and upper case letters | ||
0-9 | digits | ||
spaces | |||
+ - . = | plus, minus, period/decimal, and equal signs | ||
/ _ # * | slash, underscore, hashtag (octothorpe), and asterisk | does not accept # in Flux cal name, but does accept # in observer and other source names | |
( ) [ ] | open/close parentheses and square brackets | does not accept [ nor ] in any source name, but does accept [ and ] in observer name | |
OPT Suite prohibited characters | |||
' " | single quote and double quote | accepts " in observer name and ' in observer and any source name | |
{ } | curly brackets | accepts { and } in observer name | |
< > | less than and greater than | ||
end-of-line and non-printable characters (e.g., "tab"), rich-text formatted text or other non-ASCII characters |
accepts "tab" at the end of observer name |
||
\ @ % $ | backslash, at, percent and dollar signs | accepts \ in observer name and @ $ % in observer and source name | |
` ~ ! ^ & | : , ; ? | other textual and linguistic characters | accepts , in observer name and ` ~ ! ^ | : ; ? in observer and source name |
*) Anywhere in the text file that is uploaded, including Scheduling Block name, User Comments/Notes, etc.
**) Some characters (parentheses and most characters in the bottom row) used in the VLA CASA Pipeline (especially in the Phase calibrator name) may cause several of the plots in the plotsummary stage to differ slightly from when these characters do not appear in source names. This causes the numbers in the makeimages task to differ slightly as well.
2. SCT: Importing Source Lists
Syntax
Text files with source lists can be imported into the SCT if they use the following syntax. Note that this is the same format as for the PST, so if you have uploaded your source list into the PST, you can use the same file for uploading in the SCT. 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 an # (octothorpe)). An (optional) exception is if the very first line is starting with an * (asterisk); the string after the asterisk will replace the default source catalog name, where a leading space in the string is ignored. 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; note that the catalog name line, the one starting with the asterisk, should not contain any semi-colon.
Details and possible (predefined) values per field are described in the table below.
sourceName |
Mandatory, single value
|
groupNames |
Optional, unlimited number of comma-separated values
|
coordSystem |
Optional, single value (defaults to equatorial), not case-sensitive
|
epoch |
Optional, single value (defaults to J2000), not case-sensitive
|
longitude |
Mandatory, single value
|
latitude |
Mandatory, single value
|
refFrame |
Mandatory in combination with convention and velocity, single value, not case-sensitive
|
convention |
Mandatory in combination with refFrame and velocity, single value, not case-sensitive
|
velocity |
Mandatory in combination with refFrame and convention, single value
|
calibrator |
Optional single value (defaults to N), not case-sensitive
|
To ingest a text file with a source list, navigate to the SCT. Select from the menu FILE → IMPORT and then select 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 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 an * (asterisk) 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. RCT: Importing 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 in the table below.
lineName |
Mandatory, single value
|
restFreq |
Mandatory, single value larger than zero, unit defaults to GHz
|
refFrame |
Mandatory, single value, not case-sensitive
|
convention |
Mandatory, single value, not case-sensitive
|
velocity |
Mandatory, single value, unit defaults to km/s
|
velRange |
Mandatory, single value larger than zero, unit defaults to km/s, value defaults to 100 (i.e., 100.0km/s)
|
velSep |
Mandatory, single value larger than zero, unit defaults to km/s, value defaults to 1 (i.e., 1.0km/s)
|
polProd |
Mandatory, multi-value, not case-sensitive
|
other |
Optional, multi-value, not case-sensitive
|
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
4. OPT: Importing Scheduling Blocks
Note: due to a recent upgrade in Firefox (version 115.x), the functionality of uploading an SB as a text file has been broken. If you want to upload an SB as a text file, NRAO staff have determined that the following browsers and platforms will work: Safari (Mac), Chrome (Mac, Windows, Linux), Opera (Mac, Windows, Linux), and Microsoft Edge (Windows).
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 Science 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 6. If the line is omitted, versionNumber defaults to the latest version of the syntax. The documentation here is for the latest version.
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])
|
schedulingType |
Optional, single value (defaults to Dynamic), not case-sensitive
|
iterationCount |
Optional, single value (defaults to 1)
|
date |
Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type
|
timeOfDay |
Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type
|
shadowLimit |
Optional, single value (defaults to 0.0)
|
shadowCalcConfiguration |
Optional, single value (defaults to the first array configuration in the Program Block)
|
initTeleAz |
Optional, single value (defaults to 225)
|
initTeleEl |
Optional, single value (defaults to 35)
|
avoidSunrise? |
Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed
|
avoidSunset? |
Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed
|
windApi |
Mandatory for Dynamic scheduling type, single or dual value; leave blank for Fixed
|
commentsToOperator |
Optional, single value
|
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; 4;
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 ;;;;;;;;;
5. OPT: Importing Scan Lists into SBs
Scan Lists
Recall from the previous section that scan lists can only be uploaded into an existing scheduling block in the OPT; it will not create a new scheduling block. Before uploading make sure to select API/wind conditions that match your observing requirements. The following scan syntax is a description of the latest version (see previous section). To define a scan list, the standard case-sensitive(!) text file content must start with (boldface lines are mandatory):
VERSION; 6;
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 in the previous section (where it also says that specifying the version is optional). The following table contains a more extensive description:
Type of Line | Field | Description |
---|---|---|
SRC-CAT | sourceCatalogNames |
Mandatory, multi-value
|
HDWR-CAT | hardwareCatalogNames |
Mandatory, multi-value
|
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?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise?;pulsarRecording;VDIFrecording;scanIntents;comments;
PTG;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise;comments;
TIP;scanName;azimuth;resourceName;timeType;time;antennaWrap;tippingOrder;comments;
OTFM;scanName;sourceName(beg);sourceName(end);resourceName;timeType;time;numSteps;numIntPs;. . .
. . .RAdirection;antennaWrap;applyRefPtg?;applyPhase?;recordOnMark6?;allowOverTop?;use10HzNoise;comments; SOL;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise?;pulsarRecording;VDIFrecording;scanIntents;solarHwCfg;comments;
Standard, Pointing, On-the-fly Mosaicking, and Solar Mode Scans
Standard observing mode, or STD-scans, require 15 additional fields (in the numbered order below) and 16 semi-colons (;), including the last. Pointing mode scans, or PTG-scans, necessary only for observations at the higher frequencies (Ku, K, Ka, Q), have 12 additional fields and 13 semi-colons, including the last. Similarly, Tipping mode scans, or TIP-scans, are described with 8 additional fields and 9 semi-colons including the last. On-the-fly Mosaicking (OTFM, introduced in version 3) scans are defined with 16 additional fields and 17 semi-colons. These modes were complemented (in version 4) by Solar mode scans, or SOL-scans, and require 16 additional fields and 17 semi-colons (which fields aren't exactly the same as for OTFM). The following table contains a more extensive description of the fields for STD, PTG, OTFM or SOL lines (other scans further below):
Order | Field | Description | |||
STD | PTG | OTFM | SOL | ||
1 | 1 | 1 | 1 | scanName |
Optional, single value (defaults to the source name (below) or [New Scan])
|
2 | 2 | 2, 3 | 2 | sourceName |
Mandatory, single value
|
3 | 3 | 4 | 3 | resourceName |
Mandatory, single value
|
4 | 4 | 5 | 4 | timeType |
Optional, single value (defaults to Duration LST), not case-sensitive
|
5 | 5 | 6 | 5 | time |
Mandatory, single value
|
- | - | 7 | - | numSteps (OTFM-scan only) |
Mandatory, single value (introduced in version 3)
|
- | - | 8 | - | numIntPs (OTFM-scan only) |
Mandatory, single value (introduced in version 3)
|
- | - | 9 | - | RAdirection (OTFM-scan only) |
Mandatory, single character (introduced in version 3)
|
6 | 6 | 10 | 6 | antennaWrap |
Optional, single value (defaults to No Preference), not case-sensitive
|
7 | 7 | 11 | 7 | applyRefPtg? |
Mandatory, single value, not case-sensitive
|
8 | 8 | 12 | 8 | applyPhase? |
Optional and only for phased VLA observations, single value (defaults to N), not case-sensitive
|
9 | 9 | 13 | 9 | recordOnMark6? |
Optional and only for phased VLA VLBI observations, single value (defaults to N), not case-sensitive
|
10 | 10 | 14 | 10 | allowOverTop? |
Optional, single value (defaults to N), not case-sensitive
|
11 | 11 | 15 | 11 | use10HzNoise? |
Optional, single value (defaults to Y), not case-sensitive (introduced in version 5)
|
12 | - | - | 12 | pulsarRecording |
Optional, single value (defaults to N), not case-sensitive (introduced in version 6)
|
13 | - | - | 13 | VDIFrecording |
Optional, single value (defaults to N), not case-sensitive (introduced in version 6)
|
14 | - | - | 14 | scanIntents (STD-scan only) |
Mandatory, multi-value, not case-sensitive
|
- | - | - | 15 | solarHwCfg (SOL-scan only) |
Optional, single integer value (defaults to 1) (introduced in version 4)
|
15 | 12 | 16 | 16 | comments |
Optional, single value
|
Note that in principle only a single one of STD/PTG/TIP/OTFM/SOL 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 (as any science data calibration scan will be an STD scan).
Tipping Mode Scans
Please note that tipping scans are currently prohibited. Until further notice, there is no suggested path in CASA or AIPS to apply tipping scan solutions to the data. This documentation is for those who want to take the tipping data anyway during their observations. If you have questions about setting up TIP-scans please consult the NRAO Science Helpdesk.
Tipping mode scans will need a scan length of at least 1 minute and 50 seconds to perform the tip and to derive a useful measurement. Slew from the previous source to the anticipated azimuth needs to be added to the scan length and is not straightforward to estimate for a dynamic schedule; use the longest slew during any of your LST start times (which may need some experimenting with the assumed LST start of the SB in the Reports tab).
The following table contains the fields expected on a TIP line.
Order | Field | Description |
---|---|---|
1 | scanName |
Optional, single value
|
2 | azimuth |
Mandatory, single value
|
3 | resourceName |
Mandatory, single value
|
4 | timeType |
Optional, single value (defaults to Duration LST), not case-sensitive
|
5 | time |
Mandatory, single value
|
6 | antennaWrap |
Optional, single value (defaults to No Preference), not case-sensitive
|
7 | tippingOrder |
Mandatory, single value, not case-sensitive
|
8 | comments |
Optional, single value
|
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:
Order | Field | Description |
---|---|---|
1 | loopName |
Optional, single value (defaults to [New Loop])
|
2 | iterationCount |
Mandatory, single value
|
3 | bracketed? |
Optional, single value (defaults to N), not case-sensitive
|
4 | comments |
Optional, single value
|
Subarrays
Up to three subarrays can be generated using the syntax below; it is a kludge from the normal loop and thus a bit more clumsy (with 5 additional fields and 6 semi-colons). Subarrays cannot be nested, but loops in subarrays can. Every SUBARRAY-LOOP-START line must have a corresponding SUBARRAY-LOOP-END (with no other fields and a single semi-colon). The uppermost unpaired SUBARRAY-LOOP-END is taken to end the lowermost unpaired SUBARRAY-LOOP-START. Note that the number of pads in a 3-subarray observation cannot be 9+9+9; the closest possible subarray distribution is 8+9+10 antennas.
SUBARRAY-LOOP-START;subarrayName;1;N;;ListOfPads;
[some STD-scans and/or PTG-scans, TIP-scans, nested loops, etc.]
SUBARRAY-LOOP-END;
The following table describes fields expected on a SUBARRAY-LOOP-START line:
Order | Field | Description |
---|---|---|
1 | subarrayName |
Optional, single value (defaults to [New Subarray])
|
2 | [unused] |
Mandatory, 1
|
3 | [unused] |
Optional, single value (defaults to N), not case-sensitive
|
4 | [unused] |
Optional, single value
|
5 | listOfPads |
Mandatory, comma-separated list of pads
|
Holography
For completeness the following defines the holograpy line. This mode should not be used in general but is listed here as documentation for operations. Note that in the OPT there is a way to define the antenna wrap which is missing in the definition here, and that there is no implementation of rotating the grid yet (in this text line, nor in the OPT itself, only in the observing script). The UT scan duration and scan intent are automatically generated in the interface from this text line input.
HOLO;scanName;sourceName;resourceName;maxTime(h);refAnts;dwellTime(s);initDir(AZ/EL);. . .
. . .numbPtsAz;numbPtsEl;offsAz;offsEl;oversampAz;oversampEl;initDirAz;initDirEl;. . .
. . .calIntRow;calDur(s);ptgResource;ptgIntRow;ptgDur(s);comments;
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 (version 4) 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>