agentflagger

NRAO Home > CASA > CASA Toolkit Reference Manual

2.2.1 agentflagger - Tool

Tool for manual and automated flagging
Requires:

Synopsis

Description

The agentflagger tool performs manual as well as automatic synthesis flagging operations within casapy. The agentflagger tool can operate on one measurement set at a time.

Open the Measurement Set or Calibration Table and Attach it to the Tool

The first thing to do is to open the MS or calibration table and attach it to the agentflagger tool. Use the af.open method, which requires the MS name and optionally the time interval, over which to buffer data before running the algorithm. The time interval is set by default to 0.0, which means a ’scan’ length. The ’ntime’ parameter is important for the modes tfcrop, rflag and extend.

af.open(’uid_X002.ms’)

Select the Data

Once the MS is open, the next step is to select the data. This step will use the MS selection tool to select the portion of the MS given by the parameters. There are two ways of selecting the data:

1) Create a Python dictionary which internally will be transformed into a record containing the selection parameters.

     # Select the whole MS.
     af.selectdata()

     Select a portion of the MS using a dictionary.
     myrecord={}
     myrecord[’scan’]=’1~3’
     myrecord[’spw’]=’0:1~10’
     af.selectdata(myrecord)

2) Parse the parameter names directly to the function.

af.selectdata(scan=’1~3’, spw=’0:1~10’)

Parse the Parameters for the Flagging Mode(s)

Each flagging mode is called an agent. The available agents are: manual, clip, quack, shadow, elevation, tfcrop, rflag, extend, unflag and summary. Each one of these agents may or may not take configuration parameters and data selection parameters. Once the desired flagging modes are chosen, it is time to give the configuration parameters to the tool. Ommited parameters will take default values as defined in each agent. There are two ways of parsing the agent’s parameters.

1) Using the general method af.parseagentparameters().

     Construct a dictionary with the parameters for each agent. Each agent’s
     parameters should go to a different ’key’ of the dictionary. Example:

     # Create a shadow agent:
     myagents = {}
     myagents[’mode’] = ’shadow’
     af.parseagentparameters(myagents)

     # Add a summary agent to the list.
     myagents = {}
     myagents[’mode’] = ’summary
     myagents[’spwchan] = True
     af.parseagentparameters(myagents)

     # Add a manual agent to the same internal list of agents.
     myagents = {}
     myagents[’mode’] = ’manual’
     myagents[’scan’] = ’1~3,18~20’
     af.parseagentparameters(myagents)

     # Add a clip agent to flag the zero-value data.
     myagents = {}
     myagents[’mode’] = ’clip’
     myagents[’clipzeros’] = True
     af.parseagentparameters(myagents)

     # Add another summary agent to the list.
     myagents = {}
     myagents[’mode’] = ’summary
     myagents[’spwchan] = True
     af.parseagentparameters(myagents)

2) The other way to parse agent’s parameters is to use the convenience functions. The above example would become:

     # Create a shadow agent:
     af.parseshadowparameters()

     # Add a summary agent to the list.
     af.parsesummaryparameters(spwchan=True)

     # Add a manual agent to the same internal list of agents.
     af.parsemanualparameters(scan=’1~3,18~20’)

     # Add a clip agent to flag the zero-value data.
     af.parseclipparameters(clipzeros=True)

     # Add another summary agent to the list.
     af.parsesummaryparameters(spwchan=True)

Initialize the Agents

The above step create a list of the agents that the tool will use to process the data. This step will check several parameters and apply constraints. It will set the iteration approach to COMBINE_SCANS_MAP_ANTENNA_PAIRS_ONLY if the agent is either tfcrop or extend and combinescans is set to True. Otherwise it will set it to COMPLETE_SCAN_MAP_ANTENNA_PAIRS_ONLY.

If the list contains agents that set ntime more than once, this method will get the maximum value of ntime and use it for all agents.

If a tfcrop agent is present, this method will create one agent per each polarization available, if correlation is set to ALL.

In the same way, if an agent tfcrop, rflag or clip is present, the asyncio mechanism will be switched on.

af.init()

Run the tool

Run the tool to apply or unapply the flags. The run method takes two parameters, writeflags and sequential. The parameter writeflags controls whether to write the flags or not to the MS. By default it is set to True. The sequential parameter tells to apply/unapply the flags in parallel or not. By default it is set to True, which means that the agents will run in sequential.

The run method gathers several reports, depending on wich agents are run. The display and summary agents produce reports that can be retrieved from calling the run method. The reports are returned via a Python dictionary.

myreports = af.run(writeflags=True)

The dictionary returned in ’myreports’ will contain four reports from the two summary agents that were added previously. The first report is the normal summary for each selection parameter. The second report gives the antenna positions for plotting.

Destroy the tool

Do not forget to destroy and close the tool at the end.

af.done()

Methods

agentflagger	Construct a flag tool
done	Destroy the flag tool
open	Open the MS or a calibration table and attach it to the tool.
selectdata	Select the data based on the given parameters. For unspecified parameters, the full data range is assumed. All data selection parameters follow the MS Selection syntax.
parseagentparameters	Parse the parameters for the agent (flagging mode).
init	Initialize the agents
run	Execute a list of flagging agents
getflagversionlist	Print out a list of saved flag_versions.
printflagselection	Print out a list of current flag selections.
saveflagversion	Save current flags with a version name.
restoreflagversion	Restore flags from a saved flag_version. versionname : name of flag version to restore to main table merge : Type of operation to perform during restoration. merge = replace : replaces the main table flags. merge = and : logical AND with main table flags merge = or : logical OR with main table flags Default : replace.
deleteflagversion	Delete a saved flag_version.
parsemanualparameters	Parse data selection parameters and specific parameters for the manual mode. Data selection follows the MS Selection syntax.
parseclipparameters	Parse data selection parameters and specific parameters for the clip mode. Data selection follows the MS Selection syntax.
parsequackparameters	Parse data selection parameters and specific parameters for the quack mode. Data selection follows the MS Selection syntax.
parseelevationparameters	Parse data selection parameters and specific parameters for the elevation mode. Data selection follows the MS Selection syntax.
parsetfcropparameters	Parse data selection parameters and specific parameters for the time and frequency mode. Data selection follows the MS Selection syntax.
parseextendparameters	Parse data selection parameters and specific parameters for the extend mode. Data selection follows the MS Selection syntax.
parsesummaryparameters	Parse data selection parameters and specific parameters for the summary mode. Data selection follows the MS Selection syntax.

[next] [prev] [prev-tail] [front] [up]

More information about CASA may be found at the CASA web page

This code is available under the terms of the GNU General Public Lincense