__init__(self, filename, average=None, unit=None)
(Constructor)

Create a scantable from a saved one or make a reference
Parameters:
    filename:    the name of an asap table on disk
                 or
                 the name of a rpfits/sdfits/ms file
                 (integrations within scans are auto averaged
                 and the whole file is read)
                 or
                 [advanced] a reference to an existing
                 scantable
    average:     average all integrations withinb a scan on read.
                 The default (True) is taken from .asaprc.
    unit:         brightness unit; must be consistent with K or Jy.
                 Over-rides the default selected by the reader
                 (input rpfits/sdfits/ms) or replaces the value
                 in existing scantables

Overrides:

asap._asap.Scantable.__init__

__div__(self, other)

__mul__(self, other)

__sub__(self, other)
(Subtraction operator)

add(self, offset, insitu=None)

Return a scan where all spectra have the offset added
Parameters:
    offset:      the offset
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

auto_poly_baseline(self, mask=[], edge=(0, 0), order=0, threshold=3, chan_avg_limit=1, plot=False, insitu=None)

Return a scan which has been baselined (all rows) by a polynomial.
Spectral lines are detected first using linefinder and masked out
to avoid them affecting the baseline solution.

Parameters:
    mask:       an optional mask retreived from scantable
    edge:       an optional number of channel to drop at
                the edge of spectrum. If only one value is
                specified, the same number will be dropped from
                both sides of the spectrum. Default is to keep
                all channels. Nested tuples represent individual
                edge selection for different IFs (a number of spectral
                channels can be different)
    order:      the order of the polynomial (default is 0)
    threshold:  the threshold used by line finder. It is better to
                keep it large as only strong lines affect the
                baseline solution.
    chan_avg_limit:
                a maximum number of consequtive spectral channels to
                average during the search of weak and broad lines.
                The default is no averaging (and no search for weak
                lines). If such lines can affect the fitted baseline
                (e.g. a high order polynomial is fitted), increase this
                parameter (usually values up to 8 are reasonable). Most
                users of this method should find the default value
                sufficient.
    plot:       plot the fit and the residual. In this each
                indivual fit has to be approved, by typing 'y'
                or 'n'
    insitu:     if False a new scantable is returned.
                Otherwise, the scaling is done in-situ
                The default is taken from .asaprc (False)

Example:
    scan2=scan.auto_poly_baseline(order=7)

auto_quotient(self, preserve=True, mode='paired')

This function allows to build quotients automatically.
It assumes the observation to have the same numer of
"ons" and "offs"
Parameters:
    preserve:       you can preserve (default) the continuum or
                    remove it.  The equations used are
                    preserve: Output = Toff * (on/off) - Toff
                    remove:   Output = Toff * (on/off) - Ton
    mode:           the on/off detection mode 
                    'paired' (default)
                    identifies 'off' scans by the
                    trailing '_R' (Mopra/Parkes) or
                    '_e'/'_w' (Tid) and matches
                    on/off pairs from the observing pattern
        'time'
           finds the closest off in time

average_beam(self, mask=None, weight='none')

Average the Beams together.
Parameters:
    mask:        An optional mask defining the region, where the
                 averaging will be applied. The output will have all
                 specified points masked.
    weight:      Weighting scheme. 'none' (default), 'var' (1/var(spec)
                 weighted), or 'tsys' (1/Tsys**2 weighted)

average_pol(self, mask=None, weight='none')

Average the Polarisations together.
Parameters:
    mask:        An optional mask defining the region, where the
                 averaging will be applied. The output will have all
                 specified points masked.
    weight:      Weighting scheme. 'none' (default), 'var' (1/var(spec)
                 weighted), or 'tsys' (1/Tsys**2 weighted)

average_time(self, mask=None, scanav=False, weight='tint', align=False)

Return the (time) weighted average of a scan.
Note:
    in channels only - align if necessary
Parameters:
    mask:     an optional mask (only used for 'var' and 'tsys'
              weighting)
    scanav:   True averages each scan separately
              False (default) averages all scans together,
    weight:   Weighting scheme.
              'none'     (mean no weight)
              'var'      (1/var(spec) weighted)
              'tsys'     (1/Tsys**2 weighted)
              'tint'     (integration time weighted)
              'tintsys'  (Tint/Tsys**2)
              'median'   ( median averaging)
              The default is 'tint'
    align:    align the spectra in velocity before averaging. It takes
              the time of the first spectrum as reference time.
Example:
    # time average the scantable without using a mask
    newscan = scan.average_time()

bin(self, width=5, insitu=None)

Return a scan where all spectra have been binned up.
Parameters:
    width:       The bin width (default=5) in pixels
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

convert_flux(self, jyperk=None, eta=None, d=None, insitu=None)

Return a scan where all spectra are converted to either
Jansky or Kelvin depending upon the flux units of the scan table.
By default the function tries to look the values up internally.
If it can't find them (or if you want to over-ride), you must
specify EITHER jyperk OR eta (and D which it will try to look up
also if you don't set it). jyperk takes precedence if you set both.
Parameters:
    jyperk:      the Jy / K conversion factor
    eta:         the aperture efficiency
    d:           the geomtric diameter (metres)
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

convert_pol(self, poltype=None)

Convert the data to a different polarisation type.
Parameters:
    poltype:    The new polarisation type. Valid types are:
                "linear", "stokes" and "circular"

copy(self)

Return a copy of this scantable.
Note:
    This makes a full (deep) copy. scan2 = scan1 makes a reference.
Parameters:
    none
Example:
    copiedscan = scan.copy()

create_mask(self, *args, **kwargs)

Compute and return a mask based on [min, max] windows.
The specified windows are to be INCLUDED, when the mask is
applied.
Parameters:
    [min, max], [min2, max2], ...
        Pairs of start/end points (inclusive)specifying the regions
        to be masked
    invert:     optional argument. If specified as True,
                return an inverted mask, i.e. the regions
                specified are EXCLUDED
    row:        create the mask using the specified row for
                unit conversions, default is row=0
                only necessary if frequency varies over rows.
Example:
    scan.set_unit('channel')
    a)
    msk = scan.create_mask([400, 500], [800, 900])
    # masks everything outside 400 and 500
    # and 800 and 900 in the unit 'channel'

    b)
    msk = scan.create_mask([400, 500], [800, 900], invert=True)
    # masks the regions between 400 and 500
    # and 800 and 900 in the unit 'channel'
    c)
    mask only channel 400
    msk =  scan.create_mask([400, 400])

drop_scan(self, scanid=None)

Return a new scantable where the specified scan number(s) has(have)
been dropped.
Parameters:
    scanid:    a (list of) scan number(s)

flag(self, mask=None)

Flag the selected data using an optional channel mask.
Parameters:
    mask:   an optional channel mask, created with create_mask. Default
            (no mask) is all channels.

freq_align(self, reftime=None, method='cubic', insitu=None)

Return a scan where all rows have been aligned in frequency/velocity.
The alignment frequency frame (e.g. LSRK) is that set by function
set_freqframe.
Parameters:
    reftime:     reference time to align at. By default, the time of
                 the first row of data is used.
    method:      Interpolation method for regridding the spectra.
                 Choose from "nearest", "linear", "cubic" (default)
                 and "spline"
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

freq_switch(self, insitu=None)

Apply frequency switching to the data.
Parameters:
    insitu:      if False a new scantable is returned.
                 Otherwise, the swictching is done in-situ
                 The default is taken from .asaprc (False)
Example:
    none

gain_el(self, poly=None, filename='', method='linear', insitu=None)

Return a scan after applying a gain-elevation correction.
The correction can be made via either a polynomial or a
table-based interpolation (and extrapolation if necessary).
You specify polynomial coefficients, an ascii table or neither.
If you specify neither, then a polynomial correction will be made
with built in coefficients known for certain telescopes (an error
will occur if the instrument is not known).
The data and Tsys are *divided* by the scaling factors.
Parameters:
    poly:        Polynomial coefficients (default None) to compute a
                 gain-elevation correction as a function of
                 elevation (in degrees).
    filename:    The name of an ascii file holding correction factors.
                 The first row of the ascii file must give the column
                 names and these MUST include columns
                 "ELEVATION" (degrees) and "FACTOR" (multiply data
                 by this) somewhere.
                 The second row must give the data type of the
                 column. Use 'R' for Real and 'I' for Integer.
                 An example file would be
                 (actual factors are arbitrary) :

                 TIME ELEVATION FACTOR
                 R R R
                 0.1 0 0.8
                 0.2 20 0.85
                 0.3 40 0.9
                 0.4 60 0.85
                 0.5 80 0.8
                 0.6 90 0.75
    method:      Interpolation method when correcting from a table.
                 Values are  "nearest", "linear" (default), "cubic"
                 and "spline"
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

get_abcissa(self, rowno=0)

Get the abcissa in the current coordinate setup for the currently
selected Beam/IF/Pol
Parameters:
    rowno:    an optional row number in the scantable. Default is the
              first row, i.e. rowno=0
Returns:
    The abcissa values and the format string (as a dictionary)

get_azimuth(self, row=-1)

Get a list of azimuths for the observations.
Return a float for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows.
Example:
    none

get_column_names(self)

Overrides:

asap._asap.Scantable.get_column_names

get_direction(self, row=-1)

Get a list of Positions on the sky (direction) for the observations.
Return a float for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows
Example:
    none

get_elevation(self, row=-1)

Get a list of elevations for the observations.
Return a float for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows.
Example:
    none

get_fit(self, row=0)

Print or return the stored fits for a row in the scantable
Parameters:
    row:    the row which the fit has been applied to.

get_inttime(self, row=-1)

Get a list of integration times for the observations.
Return a time in seconds for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows.
Example:
    none

get_parangle(self, row=-1)

Get a list of parallactic angles for the observations.
Return a float for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows.
Example:
    none

get_restfreqs(self)

Get the restfrequency(s) stored in this scantable.
The return value(s) are always of unit 'Hz'
Parameters:
    none
Returns:
    a list of doubles

get_scan(self, scanid=None)

Return a specific scan (by scanno) or collection of scans (by
source name) in a new scantable.
Note:
    See scantable.drop_scan() for the inverse operation.
Parameters:
    scanid:    a (list of) scanno or a source name, unix-style
               patterns are accepted for source name matching, e.g.
               '*_R' gets all 'ref scans
Example:
    # get all scans containing the source '323p459'
    newscan = scan.get_scan('323p459')
    # get all 'off' scans
    refscans = scan.get_scan('*_R')
    # get a susbset of scans by scanno (as listed in scan.summary())
    newscan = scan.get_scan([0, 2, 7, 10])

get_selection(self)

Get the selection object currently set on this scantable.
Parameters:
    none
Example:
    sel = scan.get_selection()
    sel.set_ifs(0)              # select IF 0
    scan.set_selection(sel)     # apply modified selection

get_sourcename(self, row=-1)

Get a list source names for the observations.
Return a string for each integration in the scantable.
Parameters:
    row:    row no of integration. Default -1 return all rows.
Example:
    none

get_time(self, row=-1, asdatetime=False)

Get a list of time stamps for the observations.
Return a datetime object for each integration time stamp in the scantable.
Parameters:
    row:          row no of integration. Default -1 return all rows
    asdatetime:   return values as datetime objects rather than strings
Example:
    none

get_tsys(self)

Return the System temperatures.
Returns:
    a list of Tsys values for the current selection

get_unit(self)

Get the default unit set in this scantable
Returns:
    A unit string

history(self, filename=None)

Print the history. Optionally to a file.
Parameters:
    filename:    The name  of the file to save the history to.

invert_phase(self)

lag_flag(self, frequency, width=0.0, unit='GHz', insitu=None)

Flag the data in 'lag' space by providing a frequency to remove.
Flagged data in the scantable gets set to 0.0 before the fft.
No taper is applied.
Parameters:
    frequency:    the frequency (really a period within the bandwidth) 
                  to remove
    width:        the width of the frequency to remove, to remove a 
                  range of frequencies aroung the centre.
    unit:         the frequency unit (default "GHz")
Notes:
    It is recommended to flag edges of the band or strong 
    signals beforehand.

mx_quotient(self, mask=None, weight='median', preserve=True)

Form a quotient using "off" beams when observing in "MX" mode.
Parameters:
    mask:           an optional mask to be used when weight == 'stddev'
    weight:         How to average the off beams.  Default is 'median'.
    preserve:       you can preserve (default) the continuum or
                    remove it.  The equations used are
                    preserve: Output = Toff * (on/off) - Toff
                    remove:   Output = Toff * (on/off) - Ton

opacity(self, tau, insitu=None)

Apply an opacity correction. The data
and Tsys are multiplied by the correction factor.
Parameters:
    tau:         Opacity from which the correction factor is
                 exp(tau*ZD)
                 where ZD is the zenith-distance
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

poly_baseline(self, mask=None, order=0, plot=False, insitu=None)

Return a scan which has been baselined (all rows) by a polynomial.
Parameters:
    mask:       an optional mask
    order:      the order of the polynomial (default is 0)
    plot:       plot the fit and the residual. In this each
                indivual fit has to be approved, by typing 'y'
                or 'n'
    insitu:     if False a new scantable is returned.
                Otherwise, the scaling is done in-situ
                The default is taken from .asaprc (False)
Example:
    # return a scan baselined by a third order polynomial,
    # not using a mask
    bscan = scan.poly_baseline(order=3)

recalc_azel(self)

Recalculate the azimuth and elevation for each position.
Parameters:
    none
Example:

resample(self, width=5, method='cubic', insitu=None)

Return a scan where all spectra have been binned up.

Parameters:
    width:       The bin width (default=5) in pixels
    method:      Interpolation method when correcting from a table.
                 Values are  "nearest", "linear", "cubic" (default)
                 and "spline"
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)

rotate_linpolphase(self, angle)

Rotate the phase of the complex polarization O=Q+iU correlation.
This is always done in situ in the raw data.  So if you call this
function more than once then each call rotates the phase further.
Parameters:
    angle:   The angle (degrees) to rotate (add) by.
Examples:
    scan.rotate_linpolphase(2.3)

rotate_xyphase(self, angle)

Rotate the phase of the XY correlation.  This is always done in situ
in the data.  So if you call this function more than once
then each call rotates the phase further.
Parameters:
    angle:   The angle (degrees) to rotate (add) by.
Examples:
    scan.rotate_xyphase(2.3)

save(self, name=None, format=None, overwrite=False)

Store the scantable on disk. This can be an asap (aips++) Table,
SDFITS or MS2 format.
Parameters:
    name:        the name of the outputfile. For format "ASCII"
                 this is the root file name (data in 'name'.txt
                 and header in 'name'_header.txt)
    format:      an optional file format. Default is ASAP.
                 Allowed are - 'ASAP' (save as ASAP [aips++] Table),
                               'SDFITS' (save as SDFITS file)
                               'ASCII' (saves as ascii text file)
                               'MS2' (saves as an aips++
                                      MeasurementSet V2)
    overwrite:   If the file should be overwritten if it exists.
                 The default False is to return with warning
                 without writing the output. USE WITH CARE.
Example:
    scan.save('myscan.asap')
    scan.save('myscan.sdfits', 'SDFITS')

scale(self, factor, tsys=True, insitu=None)

Return a scan where all spectra are scaled by the give 'factor'
Parameters:
    factor:      the scaling factor
    insitu:      if False a new scantable is returned.
                 Otherwise, the scaling is done in-situ
                 The default is taken from .asaprc (False)
    tsys:        if True (default) then apply the operation to Tsys
                 as well as the data

set_dirframe(self, frame='')

Set the frame type of the Direction on the sky.
Parameters:
    frame:   an optional frame type, default ''. Valid frames are:
             'J2000', 'B1950', 'GALACTIC'
Examples:
    scan.set_dirframe('GALACTIC')

Overrides:

asap._asap.Scantable.set_dirframe

set_doppler(self, doppler='RADIO')

Set the doppler for all following operations on this scantable.
Parameters:
    doppler:    One of 'RADIO', 'OPTICAL', 'Z', 'BETA', 'GAMMA'

set_feedtype(self, feedtype)

Overwrite the feed type, which might not be set correctly.
Parameters:
    feedtype:     'linear' or 'circular'

set_freqframe(self, frame=None)

Set the frame type of the Spectral Axis.
Parameters:
    frame:   an optional frame type, default 'LSRK'. Valid frames are:
             'REST', 'TOPO', 'LSRD', 'LSRK', 'BARY',
             'GEO', 'GALACTO', 'LGROUP', 'CMB'
Examples:
    scan.set_freqframe('BARY')

set_instrument(self, instr)

Set the instrument for subsequent processing.
Parameters:
    instr:    Select from 'ATPKSMB', 'ATPKSHOH', 'ATMOPRA',
              'DSS-43' (Tid), 'CEDUNA', and 'HOBART'

set_restfreqs(self, freqs=None, unit='Hz')

Set or replace the restfrequency specified and
If the 'freqs' argument holds a scalar,
then that rest frequency will be applied to all the selected
data.  If the 'freqs' argument holds
a vector, then it MUST be of equal or smaller length than
the number of IFs (and the available restfrequencies will be
replaced by this vector).  In this case, *all* data have
the restfrequency set per IF according
to the corresponding value you give in the 'freqs' vector.
E.g. 'freqs=[1e9, 2e9]'  would mean IF 0 gets restfreq 1e9 and
IF 1 gets restfreq 2e9.
You can also specify the frequencies via a linecatalog/

Parameters:
    freqs:   list of rest frequency values or string idenitfiers
    unit:    unit for rest frequency (default 'Hz')

Example:
    # set the given restfrequency for the whole table
    scan.set_restfreqs(freqs=1.4e9)
    # If thee number of IFs in the data is >= 2 IF0 gets the first
    # value IF1 the second...
    scan.set_restfreqs(freqs=[1.4e9, 1.67e9])
    #set the given restfrequency for the whole table (by name)
    scan.set_restfreqs(freqs="OH1667")

Note:
    To do more sophisticate Restfrequency setting, e.g. on a
    source and IF basis, use scantable.set_selection() before using
    this function.
    # provide your scantable is call scan
    selection = selector()
    selection.set_name("ORION*")
    selection.set_ifs([1])
    scan.set_selection(selection)
    scan.set_restfreqs(freqs=86.6e9)

set_selection(self, selection=<asap.selector.selector object at 0x41755874>)

Select a subset of the data. All following operations on this scantable
are only applied to thi selection.
Parameters:
    selection:    a selector object (default unset the selection)
Examples:
    sel = selector()         # create a selection object
    self.set_scans([0, 3])    # select SCANNO 0 and 3
    scan.set_selection(sel)  # set the selection
    scan.summary()           # will only print summary of scanno 0 an 3
    scan.set_selection()     # unset the selection

set_unit(self, unit='channel')

Set the unit for all following operations on this scantable
Parameters:
    unit:    optional unit, default is 'channel'
             one of '*Hz', 'km/s', 'channel', ''

shift_refpix(self, delta)

Shift the reference pixel of the Spectra Coordinate by an 
integer amount.
Parameters:
    delta:   the amount to shift by
Note:
    Be careful using this with broadband data.

Overrides:

asap._asap.Scantable.shift_refpix

smooth(self, kernel='hanning', width=5.0, insitu=None)

Smooth the spectrum by the specified kernel (conserving flux).
Parameters:
    kernel:     The type of smoothing kernel. Select from
                'hanning' (default), 'gaussian' and 'boxcar'.
                The first three characters are sufficient.
    width:      The width of the kernel in pixels. For hanning this is
                ignored otherwise it defauls to 5 pixels.
                For 'gaussian' it is the Full Width Half
                Maximum. For 'boxcar' it is the full width.
    insitu:     if False a new scantable is returned.
                Otherwise, the scaling is done in-situ
                The default is taken from .asaprc (False)
Example:
     none

stats(self, stat='stddev', mask=None)

Determine the specified statistic of the current beam/if/pol
Takes a 'mask' as an optional parameter to specify which
channels should be excluded.
Parameters:
    stat:    'min', 'max', 'sumsq', 'sum', 'mean'
             'var', 'stddev', 'avdev', 'rms', 'median'
    mask:    an optional mask specifying where the statistic
             should be determined.
Example:
    scan.set_unit('channel')
    msk = scan.create_mask([100, 200], [500, 600])
    scan.stats(stat='mean', mask=m)

stddev(self, mask=None)

Determine the standard deviation of the current beam/if/pol
Takes a 'mask' as an optional parameter to specify which
channels should be excluded.
Parameters:
    mask:    an optional mask specifying where the standard
             deviation should be determined.

Example:
    scan.set_unit('channel')
    msk = scan.create_mask([100, 200], [500, 600])
    scan.stddev(mask=m)

summary(self, filename=None)

Print a summary of the contents of this scantable.
Parameters:
    filename:    the name of a file to write the putput to
                 Default - no file output
    verbose:     print extra info such as the frequency table
                 The default (False) is taken from .asaprc

swap_linears(self)