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.
parsesummaryparametersParse data selection parameters and specific parameters for the summary mode. Data selection follows the MS Selection syntax.

    agentflagger.agentflagger - Function
    agentflagger.done - Function
    agentflagger.open - Function
    agentflagger.selectdata - Function
    agentflagger.parseagentparameters - Function
    agentflagger.init - Function
    agentflagger.run - Function
    agentflagger.getflagversionlist - Function
    agentflagger.printflagselection - Function
    agentflagger.saveflagversion - Function
    agentflagger.restoreflagversion - Function
    agentflagger.deleteflagversion - Function
    agentflagger.parsemanualparameters - Function
    agentflagger.parseclipparameters - Function
    agentflagger.parsequackparameters - Function
    agentflagger.parseelevationparameters - Function
    agentflagger.parsetfcropparameters - Function
    agentflagger.parseextendparameters - Function
    agentflagger.parsesummaryparameters - Function


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

Copyright 2016 Associated Universities Inc., Washington, D.C.

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


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search