Hello world¶
A flagging strategy script is a Lua script file that defines
one or more execution functions, normally named execute()
. It may
additionally define an options()
function to set options.
For a simple strategy, a flagging script can consist of a single execute
function:
function execute (data)
print("Hello world: " ..
data:get_antenna1_name() ..
" x " ..
data:get_antenna2_name() )
end
The Lua print
statement writes something to the console. Two dots are used in Lua to
concatenate strings. Let’s assume that the above
script is saved as helloworld.lua
. This strategy can now be run on a
dataset as follows:
aoflagger -strategy helloworld.lua observation.ms
When running this strategy on a WSRT dataset, the output looks like this:
$ aoflagger -strategy helloworld.lua observation.ms
AOFlagger 3.0-alpha (2020-03-06) command line application
Author: André Offringa (offringa@gmail.com)
Starting strategy on 2020-Jun-21 22:26:56.154492
Hello world: RT0 x RT2
Hello world: RT0 x RT1
Hello world: RT0 x RT3
Hello world: RT0 x RT5
Hello world: RT0 x RT4
Hello world: RT0 x RT7
Hello world: RT0 x RT6
Hello world: RT0 x RT9
Hello world: RT0 x RT8
Hello world: RT0 x RTB
Hello world: RT0 x RTA
Hello world: RT0 x RTD
Hello world: RT0 x RTC
Hello world: RT1 x RT3
Hello world: RT1 x RT2
...
As can be seen from the output,
the execute()
function is called for every pair of antennas (antennas are
named RT0/1/2/… for the WSRT). For every
antenna pair, the dynamic spectrum data is loaded and passed to execute()
.
Additionally, the existing flags and some metadata are loaded. These
data are all accessible through the data
object (see class Data
).
Because this strategy does not modify the data
object, the existing flags
are written back to the data set, so nothing is changed.
When the data set is from an interferometric telescope, such as in this example, the default option is to only flag the cross-correlations. Because the function is called from multiple independent threads, the order in which the baselines are processed can differ.
Defining options¶
If a function named options
exist, aoflagger
will call this function
before opening the dataset, and expects it to return a table with options.
Here is the same hello world strategy that processes both
auto-correlations and cross-correlations:
function execute (data)
print("Hello world for " ..
data:get_antenna1_name() ..
" x " ..
data:get_antenna2_name() )
end
function options ()
main_options = { }
main_options["baselines"] = "all"
return { ["main"] = main_options }
end
If aoflagger
is again used to run this strategy, the auto-correlations
are indeed also shown. This is achieved by setting the "baselines"
option
to "all"
. See the list of options for other
options.
The options()
function returns a table of tables. Elements of the first
table can enumerate one or more runs, whereas the second table define the
options. With this system, it is possible to define multiple execute functions.
These will process
the data one after each other. Be aware that the dataset is first completely
processed by the first function, then completely processed by the second
function, etc.
Note
Multiple execute functions cause the data to be read multiple times.
Multiple passes can be useful to e.g. first flag all baselines separately, and then perform flagging based on the integrated statistics.
The following script sets up the options to perform two runs through the data:
function execute_per_baseline (data)
-- Modify the 'data' object here
end
function execute_integrated (data)
-- Modify the 'data' object here
end
function options ()
opts1 = {
["baselines"] = "all"
["execute_function"] = "execute_per_baseline"
}
opts2 = {
["baselines"] = "cross"
["baseline_integration"] = "average"
["execute_function"] = "execute_integrated"
}
return {
["per baseline"] = opts1,
["baseline-integrated"] = opts2
}
end
rfigui
, aoflagger
and the API make use of the same Lua structure, i.e., a
script that runs in rfigui
can also be run by aoflagger
and by the
C++ and Python interfaces.
However, not all options are relevant for the rfigui
or interfaces.