Source code for pipeline.hifa.cli.hifa_spwphaseup

##################### generated by xml-casa (v2) from hifa_spwphaseup.xml ###########
##################### 5c0718d79f445991a56ee17558899930 ##############################
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_spwphaseup import hifa_spwphaseup as _hifa_spwphaseup_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_spwphaseup:
    """
    hifa_spwphaseup ---- Compute phase calibration spw map and per spw phase offsets

    
    The spw map for phase calibration is computed. Phase offsets as a function of spectral
    window are computed using high signal to noise calibration observations.
    
    Previous calibrations are applied on the fly.
    
    
    hifa_spwphaseup performs two functions:
    o determines the spectral window mapping mode for the phase vs time
    calibrations and computes spectral window map that will be used to
    apply those calibrations
    o computes the per spectral window phase offset table that will be
    applied to the data to remove mean phase differences between
    the spectral windows
    
    If hm_spwmapmode = 'auto' the spectral window map is computed using the
    following algorithm:
    
    o estimate the per spectral window per scan signal to noise ratio of the phase
    calibrator observations
    o if the signal to noise of any single phase calibration spectral window is
    less than the value of 'phasesnr' hm_spwmapmode defaults to 'combine'
    o if all phase calibrator spectral windows meet the low  signal to noise
    criterion then hm_spwmapmode defaults to default'
    o if the phase calibrator signal to noise values cannot be computed for any
    reason, for example there is no flux information, then hm_spwmapmode defaults
    to 'combine'
    
    If hm_spwmapmode = 'combine' hifa_spwphaseup maps all the science windows to a
    single science spectral window. For example if the list of science spectral
    windows is [9, 11, 13, 15] then all the science spectral windows in the data
    will be combined and mapped to the science window 9 in the combined phase vs
    time calibration table.
    
    If hm_spwmapmode = 'simple', a mapping from narrow science to wider science
    spectral windows is computed using the following algorithm:
    
    o construct a list of the bandwidths of all the science spectral windows
    o determine the maximum bandwidth in this list maxbandwidth
    o for each science spectral window  with bandwidth less than maxbandwidth
    o construct a list of spectral windows with bandwidths greater than
    minfracmaxbw * maxbandwidth
    o select the spectral window in this list whose band center most closely
    matches the band center of the narrow spectral window
    o preferentially match within the same baseband if samebb is True
    
    If hm_spwmapmode = 'default' the spw mapping is assumed to be one to one.
    
    Phase offsets per spectral window are determined by computing a phase only gain
    calibration on the selected data, normally the high signal to noise bandpass
    calibrator observations, using the solution interval 'inf'.
    
    At the end of the task the spectral window map and the phase offset calibration
    table in the pipeline are stored in the context for use by later tasks.
    
    
    Output
    
    results -- If pipeline mode is 'getinputs' then None is returned. Otherwise
    the results object for the pipeline task is returned.

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

    vis                 The list of input MeasurementSets. Defaults to the list of
                        MeasurementSets specified in the pipeline context.
                        
                        example: vis=['M82A.ms', 'M82B.ms']
    caltable            The list of output calibration tables. Defaults to the standard
                        pipeline naming convention.
                        
                        example: caltable=['M82.gcal', 'M82B.gcal']
    field               The list of field names or field ids for which phase offset solutions
                        are to be computed. Defaults to all fields with the default intent.
                        
                        example: field='3C279', field='3C279, M82'
    intent              A string containing a comma delimited list of intents against
                        which the selected fields are matched. Defaults to the BANDPASS
                        observations.
                        
                        example: intent='PHASE'
    spw                 The list of spectral windows and channels for which gain solutions are
                        computed. Defaults to all the science spectral windows.
                        
                        example: spw='13,15'
    hm_spwmapmode       The spectral window mapping mode. The options are: 'auto',
                        'combine', 'simple', and 'default'. In 'auto' mode hifa_spwphaseup
                        estimates the SNR of the phase calibrator observations and uses these
                        estimates to choose between 'combine' mode (low SNR) and 'default' mode
                        (high SNR). In combine mode all spectral windows are combined and mapped to
                        one spectral window. In 'simple' mode narrow spectral windows are mapped to
                        wider ones using an algorithm defined by 'maxnarrowbw', 'minfracmaxbw', and
                        'samebb'. In 'default' mode the spectral window map defaults to the
                        standard one to one mapping.
                        
                        example: hm_spwmapmode='combine'
    maxnarrowbw         The maximum bandwidth defining narrow spectral windows. Values
                        must be in CASA compatible frequency units.
                        
                        example: maxnarrowbw=''
    minfracmaxbw        The minimum fraction of the maximum bandwidth in the set of
                        spws to use for matching.
                        
                        example: minfracmaxbw=0.75
    samebb              Match within the same baseband if possible.
                        
                        example: samebb=False
    phasesnr            The required gaincal solution signal to noise.
                        
                        example: phaseupsnr=20.0
    bwedgefrac          The fraction of the bandwidth edges that is flagged.
                        
                        example: bwedgefrac=0.0
    hm_nantennas        The heuristics for determines the number of antennas to use
                        in the signal to noise estimate. The options are 'all' and 'unflagged'.
                        The 'unflagged' options is not currently supported.
                        
                        example: hm_nantennas='unflagged'
    maxfracflagged      The maximum fraction of an antenna that can be flagged
                        before it is excluded from the signal to noise estimate.
                        
                        example: maxfracflagged=0.80
    combine             Data axes to combine for solving. Options are '', 'scan', 'spw',
                        'field' or any comma-separated combination.
                        
                        example: combine=''
    refant              Reference antenna name(s) in priority order. Defaults to most recent
                        values set in the pipeline context.  If no reference antenna is defined in
                        the pipeline context the CASA defaults are used.
                        
                        example: refant='DV01', refant='DV05,DV07'
    minblperant         Minimum number of baselines required per antenna for each solve.
                        Antennas with fewer baselines are excluded from solutions.
                        
                        example: minblperant=2
    minsnr              Solutions below this SNR are rejected.
    unregister_existing Unregister previous spwphaseup calibrations from the pipeline context
                        before registering the new calibrations from this task.
    pipelinemode        The pipeline operating mode. In 'automatic' mode the pipeline
                        determines the values of all context defined pipeline inputs automatically.
                        In interactive mode the user can set the pipeline context defined
                        parameters manually.  In 'getinputs' mode the user can check the settings
                        of all pipeline parameters without running the task.
    dryrun              Run the commands (True) or generate the commands to be run but
                        do not execute (False).
    acceptresults       Add the results of the task to the pipeline context (True) or
                        reject them (False).

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

    
    Examples
    
    1. Compute the default spectral window map and the per spectral window phase
    offsets:
    
    hifa_spwphaseup()
    
    2. Compute the default spectral window map and the per spectral window phase
    offsets set the spectral window mapping mode to 'simple':
    
    hifa_spwphaseup(hm_spwmapmode='simple')


    """

    _info_group_ = """pipeline"""
    _info_desc_ = """Compute phase calibration spw map and per spw phase offsets"""

    def __call__( self, vis=[  ], caltable=[  ], field='', intent='', spw='', hm_spwmapmode='auto', maxnarrowbw='300MHz', minfracmaxbw=float(0.8), samebb=True, phasesnr=float(32.0), bwedgefrac=float(0.03125), hm_nantennas='all', maxfracflagged=float(0.90), combine='', refant='', minblperant=int(4), minsnr=float(3.0), unregister_existing=False, 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]}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'hm_spwmapmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'auto', 'combine', 'simple', 'default' ]}, 'maxnarrowbw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'minfracmaxbw': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'samebb': {'type': 'cBool'}, 'phasesnr': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'bwedgefrac': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'hm_nantennas': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'all', 'unflagged' ]}, 'maxfracflagged': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'combine': {'type': 'cStr', 'coerce': _coerce.to_str}, 'refant': {'type': 'cStr', 'coerce': _coerce.to_str}, 'minblperant': {'type': 'cInt'}, 'minsnr': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'unregister_existing': {'type': 'cBool'}, 'pipelinemode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'automatic', 'interactive', 'getinputs' ]}, 'dryrun': {'type': 'cBool'}, 'acceptresults': {'type': 'cBool'}}
        doc = {'vis': vis, 'caltable': caltable, 'field': field, 'intent': intent, 'spw': spw, 'hm_spwmapmode': hm_spwmapmode, 'maxnarrowbw': maxnarrowbw, 'minfracmaxbw': minfracmaxbw, 'samebb': samebb, 'phasesnr': phasesnr, 'bwedgefrac': bwedgefrac, 'hm_nantennas': hm_nantennas, 'maxfracflagged': maxfracflagged, 'combine': combine, 'refant': refant, 'minblperant': minblperant, 'minsnr': minsnr, 'unregister_existing': unregister_existing, 'pipelinemode': pipelinemode, 'dryrun': dryrun, 'acceptresults': acceptresults}
        assert _pc.validate(doc,schema), str(_pc.errors)
        _logging_state_ = _start_log( 'hifa_spwphaseup', [ 'vis=' + repr(_pc.document['vis']), 'caltable=' + repr(_pc.document['caltable']), 'field=' + repr(_pc.document['field']), 'intent=' + repr(_pc.document['intent']), 'spw=' + repr(_pc.document['spw']), 'hm_spwmapmode=' + repr(_pc.document['hm_spwmapmode']), 'maxnarrowbw=' + repr(_pc.document['maxnarrowbw']), 'minfracmaxbw=' + repr(_pc.document['minfracmaxbw']), 'samebb=' + repr(_pc.document['samebb']), 'phasesnr=' + repr(_pc.document['phasesnr']), 'bwedgefrac=' + repr(_pc.document['bwedgefrac']), 'hm_nantennas=' + repr(_pc.document['hm_nantennas']), 'maxfracflagged=' + repr(_pc.document['maxfracflagged']), 'combine=' + repr(_pc.document['combine']), 'refant=' + repr(_pc.document['refant']), 'minblperant=' + repr(_pc.document['minblperant']), 'minsnr=' + repr(_pc.document['minsnr']), 'unregister_existing=' + repr(_pc.document['unregister_existing']), 'pipelinemode=' + repr(_pc.document['pipelinemode']), 'dryrun=' + repr(_pc.document['dryrun']), 'acceptresults=' + repr(_pc.document['acceptresults']) ] )
        return _end_log( _logging_state_, 'hifa_spwphaseup', _hifa_spwphaseup_t( _pc.document['vis'], _pc.document['caltable'], _pc.document['field'], _pc.document['intent'], _pc.document['spw'], _pc.document['hm_spwmapmode'], _pc.document['maxnarrowbw'], _pc.document['minfracmaxbw'], _pc.document['samebb'], _pc.document['phasesnr'], _pc.document['bwedgefrac'], _pc.document['hm_nantennas'], _pc.document['maxfracflagged'], _pc.document['combine'], _pc.document['refant'], _pc.document['minblperant'], _pc.document['minsnr'], _pc.document['unregister_existing'], _pc.document['pipelinemode'], _pc.document['dryrun'], _pc.document['acceptresults'] ) )

hifa_spwphaseup = _hifa_spwphaseup( )