Source code for pipeline.hifa.cli.hifa_wvrgcalflag

##################### generated by xml-casa (v2) from hifa_wvrgcalflag.xml ##########
##################### 577ef4569f3102f11f91a2abff540f1d ##############################
from __future__ import absolute_import
import numpy
from casatools.typecheck import CasaValidator as _val_ctor
_pc = _val_ctor( )
from casatools.coercetype import coerce as _coerce
from .private.task_hifa_wvrgcalflag import hifa_wvrgcalflag as _hifa_wvrgcalflag_t
from casatasks.private.task_logging import start_log as _start_log
from casatasks.private.task_logging import end_log as _end_log

class _hifa_wvrgcalflag:
    """
    hifa_wvrgcalflag ---- 
    Generate a gain table based on Water Vapor Radiometer data, interpolating over
    antennas with bad radiometers.

    
    This task will first identify for each vis whether it includes at least 3
    antennas with Water Vapor Radiometer (WVR) data, and that the fraction of
    WVR antennas / all antennas exceeds the minimum threshold
    (ants_with_wvr_thresh).
    
    If there are not enough WVR antennas by number and/or fraction, then no WVR
    caltable is created and no WVR calibration will be applied to the corresponding
    vis. If there are enough WVR antennas, then the task proceeds as follows for
    each valid vis:
    
    First, generate a gain table based on the Water Vapor Radiometer data for
    each vis.
    
    Second, apply the WVR calibration to the data specified by 'flag_intent',
    calculate flagging 'views' showing the ratio
    'phase-rms with WVR / phase-rms without WVR' for each scan. A ratio < 1
    implies that the phase noise is improved, a score > 1 implies that it
    is made worse.
    
    Third, search the flagging views for antennas with anomalous high values.
    If any are found then recalculate the WVR calibration with the 'wvrflag'
    parameter set to ignore their data and interpolate results from other
    antennas according to 'maxdistm' and 'minnumants'.
    
    Fourth, after flagging, if the remaining unflagged antennas with WVR number
    fewer than 3, or represent a smaller fraction of antennas than the minimum
    threshold (ants_with_wvr_thresh), then the WVR calibration file is rejected
    and will not be merged into the context, i.e. not be used in subsequent
    calibration.
    
    Fifth, if the overall QA score for the final WVR correction of a vis file
    is greater than the value in 'accept_threshold' then make available the
    wvr calibration file for merging into the context and use in the
    subsequent reduction.

    --------- parameter descriptions ---------------------------------------------

    vis                  List of input visibility files.
                         
                         default: none, in which case the vis files to be used will be read
                                  from the context
                         example: vis=['ngc5921.ms']
    caltable             List of output gain calibration tables.
                         
                         default: none, in which case the names of the caltables will be
                                  generated automatically
                         example: caltable='ngc5921.wvr'
    offsetstable         List of input temperature offsets table files to subtract from
                         WVR measurements before calculating phase corrections.
                         
                         default: none, in which case no offsets are applied
                         example: offsetstable=['ngc5921.cloud_offsets']
    hm_toffset           If 'manual', set the 'toffset' parameter to the user-specified
                         value. If 'automatic', set the 'toffset' parameter according to the
                         date of the MeasurementSet; toffset=-1 if before 2013-01-21T00:00:00
                         toffset=0 otherwise.
    toffset              Time offset (sec) between interferometric and WVR data.
    segsource            If True calculate new atmospheric phase correction
                         coefficients for each source, subject to the constraints of
                         the 'tie' parameter. 'segsource' is forced to be True if
                         the 'tie' parameter is set to a non-empty value by the
                         user or by the automatic heuristic.
    sourceflag           Flag the WVR data for these source(s) as bad and do not produce
                         corrections for it. Requires segsource=True.
                         
                         example: sourceflag=['3C273']
    hm_tie               If 'manual', set the 'tie' parameter to the user-specified value.
                         If 'automatic', set the 'tie' parameter to include with the
                         target all calibrators that are within 15 degrees of it:
                         if no calibrators are that close then 'tie' is left empty.
    tie                  Use the same atmospheric phase correction coefficients when
                         calculating the WVR correction for all sources in the 'tie'. If 'tie'
                         is not empty then 'segsource' is forced to be True. Ignored unless
                         hm_tie='manual'.
                         
                         example: tie=['3C273,NGC253', 'IC433,3C279']
    nsol                 Number of solutions for phase correction coefficients during this
                         observation, evenly distributed in time throughout the observation. It
                         is used only if segsource=False because if segsource=True then the
                         coefficients are recomputed whenever the telescope moves to a new
                         source (within the limits imposed by 'tie').
    disperse             Apply correction for dispersion.
    wvrflag              Flag the WVR data for these antenna(s) as bad and replace its data
                         with interpolated values.
                         
                         example: wvrflag=['DV03','DA05','PM02']
    hm_smooth            If 'manual' set the 'smooth' parameter to the user-specified value.
                         If 'automatic', run the wvrgcal task with the range of 'smooth' parameters
                         required to match the integration time of the WVR data to that of the
                         interferometric data in each spectral window.
    smooth               Smooth WVR data on this timescale before calculating the correction.
                         Ignored unless hm_smooth='manual'.
    scale                Scale the entire phase correction by this factor.
    maxdistm             tance in meters of an antenna used for interpolation
                         from a flagged antenna.
                         
                         default: -1  (automatically set to 100m if >50% of antennas are 7m
                                  antennas without WVR and otherwise set to 500m)
                         example: maxdistm=550
    minnumants           Minimum number of nearby antennas (up to 3) used for
                         interpolation from a flagged antenna.
                         
                         example: minnumants=3
    mingoodfrac          Minimum fraction of good data per antenna.
                         
                         example: mingoodfrac=0.7
    refant               Ranked comma delimited list of reference antennas.
                         
                         example: refant='DV02,DV06'
    flag_intent          The data intent(s) on whose WVR correction results the search
                         for bad WVR antennas is to be based.
                         
                         A 'flagging view' will be calculated for each specified intent, in each
                         spectral window in each vis file.
                         
                         Each 'flagging view' will consist of a 2-d image with dimensions
                         ['ANTENNA', 'TIME'], showing the phase noise after the WVR
                         correction has been applied.
                         
                         If flag_intent is left blank, the default, the flagging views will be
                         derived from data with the default bandpass calibration intent i.e.
                         the first in the list BANDPASS, PHASE, AMPLITUDE for which the
                         MeasurementSet has data.
    qa_intent            The list of data intents on which the WVR correction is to be
                         tried as a means of estimating its effectiveness.
                         
                         A QA 'view' will be calculated for each specified intent, in each spectral
                         window in each vis file.
                         
                         Each QA 'view' will consist of a pair of 2-d images with dimensions
                         ['ANTENNA', 'TIME'], one showing the data phase-noise before the
                         WVR application, the second showing the phase noise after (both 'before'
                         and 'after' images have a bandpass calibration applied as well).
                         
                         An overall QA score is calculated for each vis file, by dividing the
                         'before' images by the 'after' and taking the median of the result. An
                         overall score of 1 would correspond to no change in the phase noise,
                         a score > 1 implies an improvement.
                         
                         If the overall score for a vis file is less than the value in
                         'accept_threshold' then the WVR calibration file is not made available for
                         merging into the context for use in the subsequent reduction.
    qa_bandpass_intent   The data intent to use for the bandpass calibration in
                         the qa calculation. The default is blank to allow the underlying bandpass
                         task to select a sensible intent if the dataset lacks BANDPASS data.
    accept_threshold     The phase-rms improvement ratio
                         (rms without WVR / rms with WVR) above which the wrvg file will be
                         accepted into the context for subsequent application.
    flag_hi              True to flag high figure of merit outliers.
    fhi_limit            Flag figure of merit values higher than limit * MAD.
    fhi_minsample        Minimum number of samples for valid MAD estimate/
    ants_with_wvr_thresh this threshold sets the minimum fraction of antennas
                         that should have WVR data for WVR calibration and flagging to proceed; the
                         same threshold is used to determine, after flagging, whether there remain
                         enough unflagged antennas with WVR data for the WVR calibration to be
                         applied.
                         
                         example: ants_with_wvr_thresh=0.5
    pipelinemode         The pipeline operating mode
    dryrun               Run the task (False) or display the command(True)
    acceptresults        Add the results to the pipeline context

    --------- examples -----------------------------------------------------------

    
    1. Compute the WVR calibration for all the MeasurementSets:
    
    hifa_wvrgcalflag(hm_tie='automatic')


    """

    _info_group_ = """pipeline"""
    _info_desc_ = """
    Generate a gain table based on Water Vapor Radiometer data, interpolating over
    antennas with bad radiometers.
"""

    def __call__( self, vis=[  ], caltable=[  ], offsetstable=[  ], hm_toffset='automatic', toffset=float(0), segsource=True, sourceflag=[  ], hm_tie='automatic', tie=[  ], nsol=int(1), disperse=False, wvrflag=[  ], hm_smooth='automatic', smooth='', scale=float(1), maxdistm=float(-1), minnumants=int(2), mingoodfrac=float(0.8), refant='', flag_intent='', qa_intent='BANDPASS,PHASE', qa_bandpass_intent='', accept_threshold=float(1.0), flag_hi=True, fhi_limit=float(10.0), fhi_minsample=int(5), ants_with_wvr_thresh=float(0.2), pipelinemode='automatic', dryrun=False, acceptresults=True ):
        schema = {'vis': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'caltable': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'offsetstable': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'hm_toffset': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'manual', 'automatic' ]}, 'toffset': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'segsource': {'type': 'cBool'}, 'sourceflag': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'hm_tie': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'automatic', 'manual' ]}, 'tie': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'nsol': {'type': 'cInt'}, 'disperse': {'type': 'cBool'}, 'wvrflag': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'hm_smooth': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'automatic', 'manual' ]}, 'smooth': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scale': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'maxdistm': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'minnumants': {'type': 'cInt', 'allowed': [ 1, 2, 3 ]}, 'mingoodfrac': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'refant': {'type': 'cStr', 'coerce': _coerce.to_str}, 'flag_intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'qa_intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'qa_bandpass_intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'accept_threshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'flag_hi': {'type': 'cBool'}, 'fhi_limit': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'fhi_minsample': {'type': 'cInt'}, 'ants_with_wvr_thresh': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'pipelinemode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'automatic', 'interactive', 'getinputs' ]}, 'dryrun': {'type': 'cBool'}, 'acceptresults': {'type': 'cBool'}}
        doc = {'vis': vis, 'caltable': caltable, 'offsetstable': offsetstable, 'hm_toffset': hm_toffset, 'toffset': toffset, 'segsource': segsource, 'sourceflag': sourceflag, 'hm_tie': hm_tie, 'tie': tie, 'nsol': nsol, 'disperse': disperse, 'wvrflag': wvrflag, 'hm_smooth': hm_smooth, 'smooth': smooth, 'scale': scale, 'maxdistm': maxdistm, 'minnumants': minnumants, 'mingoodfrac': mingoodfrac, 'refant': refant, 'flag_intent': flag_intent, 'qa_intent': qa_intent, 'qa_bandpass_intent': qa_bandpass_intent, 'accept_threshold': accept_threshold, 'flag_hi': flag_hi, 'fhi_limit': fhi_limit, 'fhi_minsample': fhi_minsample, 'ants_with_wvr_thresh': ants_with_wvr_thresh, 'pipelinemode': pipelinemode, 'dryrun': dryrun, 'acceptresults': acceptresults}
        assert _pc.validate(doc,schema), str(_pc.errors)
        _logging_state_ = _start_log( 'hifa_wvrgcalflag', [ 'vis=' + repr(_pc.document['vis']), 'caltable=' + repr(_pc.document['caltable']), 'offsetstable=' + repr(_pc.document['offsetstable']), 'hm_toffset=' + repr(_pc.document['hm_toffset']), 'toffset=' + repr(_pc.document['toffset']), 'segsource=' + repr(_pc.document['segsource']), 'sourceflag=' + repr(_pc.document['sourceflag']), 'hm_tie=' + repr(_pc.document['hm_tie']), 'tie=' + repr(_pc.document['tie']), 'nsol=' + repr(_pc.document['nsol']), 'disperse=' + repr(_pc.document['disperse']), 'wvrflag=' + repr(_pc.document['wvrflag']), 'hm_smooth=' + repr(_pc.document['hm_smooth']), 'smooth=' + repr(_pc.document['smooth']), 'scale=' + repr(_pc.document['scale']), 'maxdistm=' + repr(_pc.document['maxdistm']), 'minnumants=' + repr(_pc.document['minnumants']), 'mingoodfrac=' + repr(_pc.document['mingoodfrac']), 'refant=' + repr(_pc.document['refant']), 'flag_intent=' + repr(_pc.document['flag_intent']), 'qa_intent=' + repr(_pc.document['qa_intent']), 'qa_bandpass_intent=' + repr(_pc.document['qa_bandpass_intent']), 'accept_threshold=' + repr(_pc.document['accept_threshold']), 'flag_hi=' + repr(_pc.document['flag_hi']), 'fhi_limit=' + repr(_pc.document['fhi_limit']), 'fhi_minsample=' + repr(_pc.document['fhi_minsample']), 'ants_with_wvr_thresh=' + repr(_pc.document['ants_with_wvr_thresh']), 'pipelinemode=' + repr(_pc.document['pipelinemode']), 'dryrun=' + repr(_pc.document['dryrun']), 'acceptresults=' + repr(_pc.document['acceptresults']) ] )
        return _end_log( _logging_state_, 'hifa_wvrgcalflag', _hifa_wvrgcalflag_t( _pc.document['vis'], _pc.document['caltable'], _pc.document['offsetstable'], _pc.document['hm_toffset'], _pc.document['toffset'], _pc.document['segsource'], _pc.document['sourceflag'], _pc.document['hm_tie'], _pc.document['tie'], _pc.document['nsol'], _pc.document['disperse'], _pc.document['wvrflag'], _pc.document['hm_smooth'], _pc.document['smooth'], _pc.document['scale'], _pc.document['maxdistm'], _pc.document['minnumants'], _pc.document['mingoodfrac'], _pc.document['refant'], _pc.document['flag_intent'], _pc.document['qa_intent'], _pc.document['qa_bandpass_intent'], _pc.document['accept_threshold'], _pc.document['flag_hi'], _pc.document['fhi_limit'], _pc.document['fhi_minsample'], _pc.document['ants_with_wvr_thresh'], _pc.document['pipelinemode'], _pc.document['dryrun'], _pc.document['acceptresults'] ) )

hifa_wvrgcalflag = _hifa_wvrgcalflag( )