./guide
getfs.pro

Last modification date:

Wed Sep 28 13:27:09 2016

getfs

procedure getfs, scan, [ifnum=integer], [intnum=integer], [plnum=integer], [fdnum=integer], [sampler=string], [tsys=float], [tau=float], [ap_eff=float], [smthoff=integer], [units=string], [/nofold], [/blankinterp], [/nomask], [/eqweight], [tcal=float], [/quiet], [/keepints], [useflag=boolean or string], [skipflag=boolean or string], [instance=integer], [file=string], [timestamp=string], [status=variable]

This procedure retrieves and calibrates a frequency switched scan.

This code could be used as a template for the user who may wish to develop more sophisticated calibration schemes. The spectrum is calibrated in Ta (K) by default. Other recognized units are Ta* and Jy.

Summary

• Data are selected using scan, ifnum, intnum, plnum and fdnum or, alternatively, sampler and intnum if you know the specific sampler name (e.g. "A10").
• Individual integrations are processed separately. Each integration is processed using dofreqswitch
• The integrations are calibrated in Ta (K) by default. If units of Ta* or Jy are requested via the units keyword, then dcsetunits is used to convert to the desired units. This produces two spectra, one where the "sig" phase of the integration was used as the "signal" and one where the "ref" phase of the integration was used as the "signal".
• The two resulting data containers are combined using dcfold unless the nofold keyword is set. This step is also skipped if the there is no frequency overlap between the two spectra (the frequency switching distance is more than the total number of channels). In that case (out-of-band frequency switching), the data can not be "fold"ed and this step is skipped.
• Averaging of individual integrations is then done using dcaccum. By default, integrations are weighted as described in dcaccum. If the eqweight keyword is set, then integrations are averaged with an equal weight. If the nofold keyword is set or the data is out-of-band frequency-switched then the two results are averaged separately for each integration.
• The final average is left in the primary data container (buffer 0), and a summary line is printed. If the nofold keyword is set then the other result is left in buffer 1. These results can be combined later by the user using fold The printing of the summary line can be suppressed by setting the quiet keyword.
• The individual integration results can be saved to the currently opened output file by setting the keepints keyword. The final average is still produced in that case. If the nofold keyword is set, the "signal" result is kept first followed by the "reference" result for each integration, otherwise only the folded result is saved for each integration. In the case of out-of-band frequency-switched data only the "signal" result is saved unless the nofold keyword is explicitly set.

Parameters

The only required parameter is the scan number. Arguments to identify the IF number, polarization number, and feed number are optional.

If ifnum, fdnum, or plnum are not supplied then the lowest values for each of those where data exists (all combinations may not have data) will be used, using any user-supplied values. The value of ifnum is determined first, followed by fdnum and finally plnum. If a combination with data can not be found then showiftab is used to show the user what the set of valid combinations are. The summary line includes the ifnum, fdnum, and plnum used.

Tsys and Available Units

The procedure calculates Tsys based on the Tcal values and the data. The user can override this calculation by entering a zenith system temperature. The procedure will then correct the user-supplied Tsys for the observed elevation. If the data are calibrated to Ta* or Jy, additional parameters are used. A zenith opacity (tau) may be specified, and an aperture efficiency may be specified. The user is strongly encouraged to enter values for these calibration parameters, but they will be estimated if none are provided. The user can also supply a mean tcal using the tcal keyword. That will override the tcal found in the data.

Smoothing the Reference Spectra

A parameter called smthoff can be used to smooth the reference spectrum in dofreqswitch. In certain cases this can improve the signal to noise ratio, but it may degrade baseline shapes and artificially emphasize spectrometer glitches. Use with care. A value of smthoff=16 is often a good choice.

Weighting of Integrations in Scan Average

By default, the averaging of integrations is weighted using tsys, exposure, and frequency_resolution as described in the dcaccum documentation. To give all integrations equal weight instead of the default weighting based on Tsys, use the /eqweight keyword.

If the data were taken with out-of-band frequency switching then no folding will be done and the nofold argument is ignored.

Using or Ignoring Flags

Flags (set via flag) can be selectively applied or ignored using the useflag and skipflag keywords. Only one of those two keywords can be used at a time (it is an error to use both at the same time). Both can be either a boolean (/useflag or /skipflag) or an array of strings. The default is /useflag, meaning that all flag rules that have been previously set are applied when the data is fetched from disk, blanking data as described by each rule. If /skipflag is set, then all of the flag rules associated with this data are ignored and no data will be blanked when fetched from disk (it may still contain blanked values if the actual values in the disk file have already been blanked by some other process). If useflag is a string or array of strings, then only those flag rules having the same idstring value are used to blank the data. If skipflag is a string or array of strings, then all flag rules except those with the same idstring value are used to blank the data.

Dealing with flagged channels

When individual channels are flagged in the raw data (e.g. VEGAS spikes at the expected spike locations) the data values at those channels are replaced with Not a Number when the data is read from disk. That presents a challenge when processing frequency switched data to avoid a spike appearing at the flagged channel locations after the fold step done by this procedure (unless nofold is selected). When the data are combined at the fold step, each channel data average is the weighted average (using Tsys) of two data values, each from the same sky frequency but from different original channels in the raw data. When indivual channels are flagged, that average can consist of just one finite value because the frequency shift will seldom lead to overlapping flagged channels. If there is any significant baseline structure across the bandpass then that single finite channel will be noticeably different from the local average of two channels. That will lead to a noticable spike (positive or negative) at the location of a flagged channel, which is exactly the behavior that flagging the channel was trying to avoid.

This procedure offers two ways of dealing with flagged channels to avoid that problem. The default makes sure that both the original flagged channel and the corresponding channel in the other spectrum, after one of them has been shifted to align in frequency, is also flagged so that the final average has no finite values for that channel (i.e. it appears as a flagged channel). Alternatively, the blankinterp keyword can be used to tell the fold procedure to interpolate across all blanked values before doing any shifting and averaging. In the case of individually flagged channels, the blanked channel is replaced by the average of the two adjacent channels. This obviously adds a new data value at the previously unknown (flagged) channel but it can make downstream data processing simpler by not having to worry that some of the channels contain non-finite values. That may be important if the data are exported out of GBTIDL. Finally, the nomask keyword can be used to turn off this special handling (masking) of flagged channels before the average (where spikes may result). If blankinterp is used then nomask has no effect because the data are interpolated before the masking step happens. If nofold is used then the data are never masked or interpolated.

Dealing With Duplicate Scan Numbers

There are 3 ways to attempt to resolve ambiguities when the same scan number appears in the data source. The instance keyword refers to the element of the returned array of scan_info structures that scan_info returns. So, if scan 23 appears 3 times then instance=1 refers to the second time that scan 23 appears as returned by scan_info. The file keyword is useful if a scan is unique to a specific file and multiple files have been accessed using dirin. If file is specified and instance is also specified, then instance refers to the instance of that scan just within that file (which may be different from its instance within all opened files when dirin is used). The timestamp keyword is another way to resolve ambiguous scan numbers. The timestamp here is a string used essentially as a label by the monitor and control system and is unique to each scan. The format of the timestamp string is "YYYY_MM_DD_HH:MM:SS". When timstamp is given, scan and instance are ignored. If more than one match is found, an error is printed and this procedure will not continue.

Examples

Typical use of getfs:

    getfs,76
    accum
    getfs,77
    accum
    ave
    show
 

In the following example, the spectrum is not folded and the two components of the calibration are shown overlaid on the plotter. Then the data are folded 'by hand'. This example also shows how /skipflag can be used to ignore all previously set flags.

    getfs,76,/nofold,/skipflag
    oshow,1
    fold
 

Uses

accumave accumclear calsummary check_calib_args data_free dcaccum dcfold dcscale dcsetunits dofreqswitch find_scan_info get_calib_data set_data_container showiftab

Version

$Id$

Parameters
scan in, required integer	scan number

Keywords
ifnum in, optional integer	IF number (starting with 0). Defaults to the lowest value associated with data taking into account any user-supplied values for fdnum, and plnum.
intnum in, optional integer	integration number, default is all integrations.
plnum in, optional integer	Polarization number (starting with 0). Defaults to the lowest value with data after determining the values of ifnum and fdnum if not supplied by the user.
fdnum in, optional integer	Feed number. Defaults to the lowest value with data after determining the value of ifnum if not supplied by the user and using any value of plnum supplied by the user.
sampler in, optional string	sampler name, this is an alternative way to specify ifnum,plnum, and fdnum. When sampler name is given, ifnum, plnum, and fdnum must not be given.
tsys in, optional float	tsys at zenith, this is converted to a tsys at the observed elevation. If not suppled, the tsys for each integration is calculated as described elsewhere.
tau in, optional float	tau at zenith, if not supplied, it is estimated using get_tau tau is only used when the requested units are other than the default of Ta and when a user-supplied tsys value at zenith is to be used.
ap_eff in, optional float	aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoff in, optional integer	smooth factor for reference spectrum
units in, optional string	takes the value 'Jy', 'Ta', or 'Ta*', default is Ta.
nofold in, optional boolean	When set, getfs does not fold the calibrated spectrum. Buffer 0 then contains the result of (sig-ref)/ref while buffer 1 contains the result of (ref-sig)/sig, calibrated independently and averaged over all integrations. Only data container 0 will be shown on the plotter. Default is unset (folded result).
blankinterp in, optional boolean	When set, blanks are replaced, before the fold step, by a linear interpolation using the finite values found in the two spectra. For isolated blanked channels, the replacement value is the average of the two adjacent channel values. This argument is ignored if nofold is used.
nomask in, optional boolean	When set, turn off the masking of blank channels from each spectrum on to the other, after the shift, when folding the data. This may result in spikes at the location of blanked channels. This was the original behavior of this routine. This keyword is ignored if /nofold is used.
eqweight in, optional boolean	When set, all integrations are averaged with equal weight (1.0). Default is unset.
tcal in, optional float	Cal temperature (K) to use in the Tsys calculation. If not supplied, the mean_tcal value from the header of the cal_off switching phase data in each integration is used. This must be a scalar, vector tcal is not yet supported. The resulting data container(s) will have it's mean_tcal header value set to this keyword when it is set by the user.
quiet in, optional boolean	When set, the normal status message on successful completion is not printed. This keyword will not affect error messages. Default is unset.
keepints in, optional boolean	When set, the individual integrations are saved to the current output file (as set by fileout). This keyword is ignored if an integration is specified using the intnum keyword. Default is unset.
useflag in, optional boolean or string	Apply all or just some of the flag rules? Default is set.
skipflag in, optional boolean or string	Do not apply any or do not apply a few of the flag rules? Default is unset.
instance in, optional integer	Which occurence of this scan should be used. Default is 0.
file in, optional string	When specified, limit the search for this scan (and instance) to this specific file. Default is all files.
timestamp in, optional string	The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
status out, optional variable	An output value to indicate whether the procedure finished as expected. A value of 1 means there were no problems, a value of -1 means there were problems with the arguments before any data was processed, and a value of 0 means that some of the individual integrations were processed (and possibly saved to the output file if keepints was set) but there was a problem with the final average, and the contents of the PDC remain unchanged.