Source code for casatasks.flagging.flagmanager

#
# stub function definition file for docstring parsing
#

[docs]def flagmanager(vis, mode='list', versionname='', oldname='', comment='', merge='replace'): r""" Enable list, save, restore, delete and rename flag version files. [`Description`_] [`Examples`_] [`Development`_] [`Details`_] Parameters - vis_ (path) - Name of input visibility file (MS) - mode_ (string='list') - Operation: list, save, restore, delete, rename .. raw:: html <details><summary><i> mode = save </i></summary> - versionname_ (string='') - Flag version name - comment_ (string='') - Short description of a versionname - merge_ (string='replace') - Merge option: replace will save or over-write the flags .. raw:: html </details> .. raw:: html <details><summary><i> mode = restore </i></summary> - versionname_ (string='') - Flag version name - merge_ (string='replace') - Merge option: replace will save or over-write the flags .. raw:: html </details> .. raw:: html <details><summary><i> mode = delete </i></summary> - versionname_ (string='') - Flag version name .. raw:: html </details> .. raw:: html <details><summary><i> mode = rename </i></summary> - oldname_ (string='') - Flag version to rename - versionname_ (string='') - Flag version name - comment_ (string='') - Short description of a versionname .. raw:: html </details> .. _Returns: Returns versions (dict) - names and comments of all flag versions, when mode='list' .. _Description: Description This task can manage flag backups of a MeasurementSet. flag backups (or versions) are copies of the FLAG column of a MeasurementSet, which are saved as a directory on disk with the same basename of the MS from which it was created, with a \*.flagversions suffix. The flag backups can be restored to the data set from which they were created in order to get back to a previous flag version. On running **importasdm**, a flag version called 'Original' is produced by default. It is recommended to save a flag backup at the beginning or after serious editing. .. warning:: The flag versions created from one MS should not be restored to another MS. They are unique to the MS from which they were created. In the case of flags created from a `Multi-MS <../../notebooks/parallel-processing.ipynb#The-Multi-MS>`__, it is not possible to restore the flag versions to a serial MS and vice versa. flagmanager also returns a dictionary for mode='list', returning the flag version names and comments. More information on flagmanager is also available in the `Data Examination and Editing <../../notebooks/data_examination.ipynb#Manage-flag-versions>`__ pages of CASAdocs. .. rubric:: Parameter description *vis* Name of input MeasurementSet or Multi-MS from where the flags were created. *mode* Flag version operation. Below is the list of options for the *mode* parameter: - 'list': list existing flag versions - 'save': save the FLAG column from *vis* to a specified flag file. If the name given in *versionname* already exists, the task will give a warning and rename it to a name with a suffix '.old.timestamp'. The respective entry in FLAG_VERSION_LIST will also be updated. - 'restore': restore the specified flag file into the MeasurementSet given in *vis* - 'delete': delete the specified flag file - 'rename': will rename a specified flag file .. rubric:: *mode='save', 'restore', 'delete', 'rename'* expandable parameters *versionname* Flag version name. The default is none *.* There should be no embedded blanks in the *versionname*. .. rubric:: *mode='save', 'rename'* expandable parameters *comment* Short description of a *versionname*, when mode is 'save' or 'rename'. .. rubric:: *mode='save', 'restore'* expandable parameters *merge* Merge operation to use when saving the flags. Options available are: 'replace', and the experimental 'or', 'and'. Use the last two options at your own risk. .. rubric:: *mode='rename'* expandable parameters *oldname* This parameter give the *oldname* of the flag versions when *mode='rename'*. .. _Examples: Examples Examples of using **flagmanager** to manipulate the flag versions of a MeasurementSet First save the flags from a MS using **flagdata** :: flagdata('my.ms', mode='manual', autocorr=True, flagbackup=True) List the existing flag versions of the above MS :: flagmanager('my.ms', mode='list') The output of the above command can be seen below. Note that the first flag versions is called 'Original", which was saved at import time using **importasdm**. The second entry called 'flagdata_1' is the flag versions from the above manual flagging. :: 2018-04-23 18:47:19 INFO flagmanager::agentflagger:: + MS : /Users/casadir/work/my.ms 2018-04-23 18:47:19 INFO flagmanager::agentflagger:: main : working copy in main table 2018-04-23 18:47:19 INFO flagmanager::agentflagger:: Original : Original flags at import into CASA 2018-04-23 18:47:19 INFO flagmanager::agentflagger:: flagdata_1 : Flags autosave on 2018-04-23 20:47:14 A captured Python dictionary returns the same content but is machine readable: :: myflaglist = flagmanager('myvis.ms', mode='list') :: {0:{'name': 'Original', 'comment': 'Original flags at import into CASA'}, 1:{'name': 'flagdata_1', 'comment': 'Flags autosave on 2018-04-23 20:47:14'}} Rename the flag version to a more meaningful name :: flagmanager('my.ms', mode='rename', oldname='flagdata_1', versionname='autocorr', comment='Flags from autocorrelation') Restore the original flags to the MS :: flagmanager('my.ms', mode='restore', versionname='Original') .. _Development: Development No additional development details .. _Details: Parameter Details Detailed descriptions of each function parameter .. _vis: | ``vis (path)`` - Name of input visibility file (MS) .. _mode: | ``mode (string='list')`` - Operation: list, save, restore, delete, rename .. _versionname: | ``versionname (string='')`` - Flag version name .. _oldname: | ``oldname (string='')`` - Flag version to rename .. _comment: | ``comment (string='')`` - Short description of a versionname .. _merge: | ``merge (string='replace')`` - Merge option: replace will save or over-write the flags """ pass