GBTIDL guide commands

GBTIDL guide commands#

`accum`	This procedure adds a data container to an accum buffer, in
`add`	This procedure adds the data from two data containers stored in the
`addstack`	Add entries to "the stack", which is a list of numbers that can
`appendstack`	Append entries to the stack. See also `addstack`.
`astack`	Function to return the value of a specific element of the stack.
`ave`	Get the average from an ongoing accumulation.
`avgstack`	Average the records listed in the stack.
`baseline`	Fit and subtract a polynomial baseline. The procedure works on
`bias`	This procedure adds a scalar bias to the data container's data.
`bmodel`	Fill in the indicated data container at modelbuffer using the
`boxcar`	Smooth the primary data container (the PDC, !g.s[0]) with a boxcar
`bshape`	Fit a polynomial baseline to the contents of the primary data
`bshow`	Overplot a baseline using the stored coefficients in `!g.polyfit` and
`bsubtract`	Subtract a baseline using the stored coefficients in `!g.polyfit`
`clearfind`	Clear a selection parameter or several selection parameters used by
`clip`	This procedure truncates, or clips, data values above and below
`copy`	Copy the data from the in buffer to the out buffer. Anything in
`decimate`	This procedure thins the spectrum at the primary data container (the
`delete`	Remove specific values from the stack.
`deselect`	This procedure is used to remove previously selected index numbers
`dirin`	Specify a directory from which data will be read. Compare to
`divide`	This procedure divides the data from two data containers stored in
`emptystack`	Clear the stack.
`filein`	Specify the SDFITS file from which data will be read.
`fileout`	Specify the file to which data will be written.
`files`	Prints the file names being used for I/O.
`find`	Put entries in to the stack based on the given selection criteria in
`find_paired_info`	Find the scan_info associated with the paired scan implied by the
`fitgauss`	An interactive procedure that allows the user to fit gaussians.
`flag`	Flag some data in the currently opened spectral line data file or
`flagrec`	Flag a specific record or records in the currently open spectral
`flagspurs`	Set the flags for the VEGAS spurs in the currently opened input data
`fold`	Average two parts of in-band frequency switching (signal and
`fshift`	Function to calculate the shift, in channels, necessary to align in
`gauss`	Fits Gaussians to the data in the primary data container (`!g.s[0]`)
`gconvol`	A GUIDE front-end to the standard IDL CONVOL function.
`get`	Get data from the input data file and put that into the primary data
`get_scan_numbers`	Function to return scan numbers for the input file.
`getbasemodel`	Function to return the polynomial using the most recently fitted
`getbs`	Procedure getbs retrieves and calibrates a beam switched Nod scan pair.
`getcal`	This procedure retrieves the "cal" signal from a cal-switched scan.
`getchunk`	A function to get several data containers from an input file in one call.
`getdata`	Extract some or all of the data array from one of the global buffers.
`getfs`	This procedure retrieves and calibrates a frequency switched
`getnod`	Procedure getnod retrieves and calibrates a total power nod scan
`getps`	Procedure getps retrieves and calibrates a total power, position
`getrec`	Gets the data associated with a given index number in the
`getscan`	Gets the data associated with a given scan number. In general this
`getsigref`	This procedure retrieves a pair of total power scans and calibrates the
`gettp`	This procedure retrieves and calibrates a total power scan.
`gfft`	Do an FFT or an inverse FFT on the data container(s) indicated by
`ginterp`	Interpolate across blanked channels in the primary data container
`gmaxiter`	Sets the maximum iterations for fitting guassians: `!g.gauss.maxiter`
`gmeasure`	Procedure to measure the area, width, and velocity of a galaxy
`gmoment`	Find the first 3 moments of a region of the data in buffer 0.
`gparamvalues`	Procedure to put values into the `!g.gauss.params` container.
`gregion`	Set some regions for use by GUIDE gaussian procedures and functions.
`gshift`	Procedure to shift data in a GUIDE data buffer by a given
`gshow`	Show the most recently fit gaussians and annotate the plot with
`gsmooth`	Smooth the data with a GAUSSIAN such that the spectrum in the given
`gstatus`	Summarize the status of GBTIDL as found in the global structure used
`hanning`	This procedure smooths a spectrum with a hanning filter.
`header`	Show header information for the primary data container or any other
`invert`	Flip the data end-to-end in the indicated buffer in the global data
`keep`	Save a spectrum to the output file.
`kget`	Retrieves data from the output data file and places it in the
`kgetrec`	Gets the data associated with a given index number in the
`kgetscan`	Gets the data associated with a given scan number in the
`lastrec`	Returns the record number (index) of the most recently
`lastscan`	Returns the scan number of the most recently retrieved data
`list`	Lists columns from the index of the input file (or
`listfind`	List a specified selection parameter or all selection parameter
`listflags`	List flags associated with the current input spectral line data file
`listids`	List all of the idstring values in the flag file of the current
`liststack`	List the index information using the first !g.acount values of
`ls`	List files (defaults to *.fits in the current directory). This
`mediansub`	Subtract the median filtered values of the given width, in channels,
`molecule`	Plot the molecular line frequencies for previously detected
`move`	Move the data from the in location to the out location. Anything in
`multiply`	This procedure multiplies the data from two data containers stored
`nfit`	Set the order of the polynomial to be fit as a baseline.
`ngauss`	Sets the value of !g.gauss.ngauss. Must set this before fitting
`nget`	Get a previously saved data container with the matching
`nrecords`	Retrieve the number of records associated with an i/o object.
`nregion`	Set some regions for use by other GUIDE procedures and functions.
`nsave`	Save a data container to the current fileout with the indicate NSAVE
`offline`	This is a convenient way to find the previously auto-filled data
`online`	Set the line io object to look at the online file.
`powspec`	Compute the power spectrum for the indicated data container, which
`putchunk`	This saves several data containers into the output file
`qdflag`	Generate flag table entries using QuadrantDetector columns in the
`recomball`	Plot the Hydrogen, $\alpha$, $\beta$, $\gamma$, helium $\alpha$, $beta$ and carbon $\alpha$ recombination lines.
`recombc`	Plot the Carbon recombination lines for quantum jump of dN.
`recombh`	Plot the Hydrogen recombination lines for quantum jump of dN.
`recombhe`	Plot the Helium recombination lines for quantum jump of dN.
`recombn`	Plot the Nitrogen recombination lines for quantum jump of dN.
`recombo`	Plot the Oxygen recombination lines for quantum jump of dN.
`replace`	Replace spectral channels by interpolation, or with zero values or
`report_gauss`	Procedure for printing what the current regions and gaussians are in
`resample`	Resample a spectrum data container onto a new frequency axis using
`samplerinfo`	Find the if, feed, and polarization numbers which corresponds to the
`scale`	This procedure scales the data container's data by a scalar value.
`scan_info`	Get scan information structure from the appropriate I/O object.
`sclear`	Clears one of the global accum buffers (frees the pointer, zeros
`select`	This procedure is used to select data from the current data file for
`set_data_container`	Set the element of the appropriate GUIDE data structure array.
`setdata`	Convenience function for setting data array of a data container.
`setfframe`	Procedure to reset the frequency reference frame of the indicated
`setfind`	Set a selection parameter to be used later by `find`.
`showiftab`	Summarize the valid `ifnum`, `fdnum`, `plnum` combinations for a scan.
`spurinterp`	Replace data values at the known locations of VEGAS ADC spurs with
`stats`	Procedure to display some simple statistics.
`subtract`	This procedure subtracts the data from two data containers stored in
`summary`	This procedure lists a summary of the input dataset. The listing
`table`	List the displayed data container or a global data container in
`unflag`	Remove all flags with the same idstring value, or id number,
`vshift`	Function to calculate the shift, in channels, necessary to align in
`whichsampler`	Find the sampler name which corresponds to the given IF, feed, and
`xshift`	This function returns a value that, when given as the argument to

pro accum(accumnum, weight=weight, dc=dc)#

This procedure adds a data container to an accum buffer, in preparation for averaging. The primary data container (!g.s[0], the PDC) is used by default but an alternate data container can be specified using the ‘dc’ keyword.

The first data container accum’ed in a buffer is used as a template for that buffer and subsequent data containers accum’ed to that buffer must match in number of channels. On subsequent uses of accum, a warning is printed if the channel spacing (frequency_interval) or frequency resolution differs from the values already in the buffer. The accumulation proceeds even when a warning is printed. Use resample to change the frequency_interval and gsmooth to change the frequency_resolution.

There are four accum buffers available to this and related GUIDE-layer procedures. Users can use these to have several averages proceeding simultaneously, but separately, when it is useful to do so (e.g. polarizations). Use the accumnum keyword to specify which buffer to use (defaults to 0).

The default weight for each spectrum is exposure*frequency_resolution/Tsys^2. A different weight can be given using the weight keyword. Alternatively, each channel can be given a separate weight by providing a vector of weights in the weight argument. In that case, the number of elements in weight must be the same as in the data. This can be used to re-start an accum from a previous average where the weight was retrieved from that average. See ave for more details. See dcaccum for additional information on how the header parameters are weighted during the accumulation.

Blanked channels (Not a Number data values) are excluded from the average. An entirely blanked spectrum (all values are NaNs - e.g. bad lags from the GBT spectrometer) is completely ignored by the accumulation (the contents of that accum buffer are unchanged).

Params:

accumnumin, optional, type=integer, default=0: accum buffer. Defaults to the primary buffer (accumnum = 0). There are 4 buffers in all so this value must be between 0 and 3, inclusive.

Keywords:

weightin, optional, type=float: The weight to use for averaging this data. If not set, a weight of exposure*frequency_resolution/Tsys^2 is used. This can also be a vector of weights, one per channel.
dcin, optional, type=spectrum or integer: The data container to accum. If not supplied, use the PDC. If this is an integer, then use the data container at that buffer number in !g.s.

Examples:

A simple averaging operation:

sclear
getrec,1
accum
getrec,2
accum
ave

Average two polarizations separately for some position switched scans

sclear                  ; clears accum buffer 0;
sclear, 1               ; clears accum buffers 1
getps,32,plnum=0
accum, 0
getps,32,plnum=1
accum, 1
getps,34,plnum=0
accum, 0
getps,34,plnum=1
accum, 1
ave,1                   ; Average plnum=1 data and store the result in the PDC
copy,0,1                ; Copy the result to DC 1
ave, 0                  ; Average plnum=0 data
oshow, 1                ; Overplot the plnum=1 average

Average some data, remember the vector weights at the average, and then average some more data.

sclear
getrec,1
accum
getrec,2
accum
ave, wtarray=wtave1_3
copy, 0, 10              ; save average for later use
sclear                   ; no necessary, but better to be sure
getrec,3
accum
getrec,4
accum
ave, wtarray=wtave3_4
copy, 0, 11              ; save this for later use
; other things could happen here
; average 11 and 10 using appropriate weighting
; they might not be scalars if some part of each was flagged or blanked
sclear
accum, dc=10, weight=wtave1_3
accum, dc=11, weight=wtave3_4
ave, wtarray=wtave_all4

Uses:

data_valid dcaccum

pro add(in1, in2, out)#

This procedure adds the data from two data containers stored in the global buffers 0-15. If no parameters are passed, then the data from global buffers 0 and 1 are added and the result is stored in global buffer 0. If two parameters are supplied, those two global buffers are added together and the result of the addition is stored in global buffer 0. If three parameters are supplied, then the first two are global buffers that are added together and the third is the global buffer where the result should be stored.

out = in1 + in2

Params:

in1in, optional, type=integer: Input buffer number, first argument.
in2in, optional, type=integer: Input buffer number, second argument.
outin, optional, type=integer: Output buffer number.

Examples:

getrec,1
copy,0,1
getrec,2
add            ; The two records are added and the result is stored in buffer 0

getrec,1
copy,0,10
getrec,2
copy,0,11
add,10,11,12   ; The data from buffers 10 and 11 are added and the result is stored in buffer 12

Uses:

dcadd dcpaircheck

pro addstack(first, last, step)#

Add entries to “the stack”, which is a list of numbers that can be used in batch operations. The list is stored in the variable !g.astack. The new entries are appended on to the existing list. Use astack to get values from the stack.

Params:

firstin, required, type=integer: The first value to be added to the stack.
lastin, optional, type=integer: The last value to be added to the stack. If this is omitted, only a single entry equal to first will be appended.
stepin, optional, type=integer: The increment between values. If omitted, a step of 1 will be used.

Examples:

add numbers 25, 30 through 39, and the odd indexes from 41 through 51 to the stack.

addstack, 25
addstack, 30, 39
addstack, 41, 51, 2

Uses:

appendstack

pro appendstack(index)#

Append entries to the stack. See also addstack.

Params:

indexin, required, type=long integer: Entries to add

Examples:

addstack,10,14,2
appendstack,20
appendstack,[25,28]
tellstack
; The stack now contains [ 10,  12,  14,  20,  25, 28]

function astack(elem, count=count)#

Function to return the value of a specific element of the stack.

Params:

elemin, optional, type=long integer: The index of the element to return. If elem is omitted, the entire contents of the stack up through (!g.acount-1) is returned as an array.

Keywords:

countout, optional, type=long integer: The number of elements returned (0, 1 or !g.acount).

Returns:

-1 : on error (out of limits), a warning message also appears.

Examples:

A simple use of astack:

; stack contains [ 10,  12,  14,  20,  25, 28] to begin
my_elem = astack(3)
; my_elem contains the value 20

A more substantive use. The following procedure averages all of the data from scans listed in the stack.

pro myavg,_extra=extra
freeze
for i=0,!g.acount-1 do begin
    getnod,astack(i),plnum=0,units='Jy',_extra=extra
    accum
    getnod,astack(i),plnum=1,units='Jy',_extra=extra
    accum
endfor
ave
unfreeze
end

In this example, select is used with astack to flag data using flagrec. This is useful if the data isn’t easily described using the parameters available in the flag procedure. The end result here is that all of the data having a source equal to “Orion” and polarization equal to “RR” in IF number 3 is flagged from channel 500 through channel 520.

emptystack  ; clear the stack first
select, source='Orion', polarization='RR', ifnum=3 ; populate the stack
a = astack(count=count)
if count gt 0 then flagrec,a,bchan=500,echan=520,idstring='RFI-Orion'

pro ave(accumnum, noclear=noclear, quiet=quiet, wtarray=wtarray, count=count)#

Get the average from an ongoing accumulation.

The result is put into the primary data container (buffer 0). The contents of the accum buffer are cleared as a consequence of calling ave, unless the noclear keyword is set.

Note: It is a good idea to use sclear to clear the accum buffer before using it the first time so that you can be certain it is starting from a cleared (empty) state.

Params:

accumnumin, type=integer, default=0: Use this accum buffer. Defaults to the primary buffer, 0. There are 4 buffers total so this value must be between 0 and 3, inclusive.

Keywords:

noclearin, optional, type=boolean, default=F: When set, the contents of the accum buffer are not cleared. This is useful when you want to see what the current average is but also plan on continuing to add data to that average. If this is not set, you would need to restart the accumulation to average more data.
quietin, optional, type=boolean, default=F: Normally, ave announces how many spectra were averaged. Setting this turns that announcement off. This is especially useful when multiple accum buffers are used within a procedure.
wtarrayout, optional, type=float array: This is the contents of the weight array at the time of the average - one value per channel. If no blanked data went into accumulation, then all values in wtarray will be the same. If an entire spectrum was blanked (e.g. bad data from the GBT Spectrometer) then that spectrum was ignored during the accumulation and again, all of the wtarray values will be the same. This quantity is only important if some channels were blanked in at least one spectrum in the accumulation and you expect to use the result of this accumulation at a later time in part of another accumulation. If you keep the wtarray around in an IDL variable, then you can use it again to weight this result in that new accumulation.
countout, optional, type=integer: The number of spectra that have been averaged. Returns -1 on an error. If count=0 then the the PDC and wtarray are unchanged by this procedure.

Examples:

Average some data

sclear
get,index=1
accum
get,index=2
accum
ave 

Average some data using another accum buffer

sclear, 2 
get,index=1
accum, 2
get,index=2
accum, 2
ave, 2

Average some data, look at an intermediate result

sclear
get,index=1
accum
get,index=2
accum
ave,/noclear  ; accum buffer is NOT clear here
get,index=3
accum
ave     ; accum buffer IS clear here

Uses:

accumave accumclear set_data_container DATA_FREE

pro avgstack(noclear=noclear, useflag=useflag, skipflag=skipflag, keep=keep)#

Average the records listed in the stack.

The data retrieval is done using getchunk. See the documentation there for a longer discussion on the useflag and skipflag keywords also found here.

Keywords:

noclearin, optional, type=boolean: If this is set, the accum buffer is not cleared prior to averaging the records
useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?
keepin, optional, type=boolean: If this is set, the records are fetched from the keep file.

Examples:

Add index number 25, 30 through 39, and the odd indexes from 41 through 51 to the stack, and average them.

addstack, 25
addstack, 30, 39
addstack, 41, 51, 2
avgstack

An example showing the use of the /noclear keyword.

addstack, 25
addstack, 30, 39
avgstack, /noclear      ; see the result so far, do not clear it
emptystack
addstack, 50, 90, 2 
avgstack                ; builds on the previous result
                        ; cleared after this use of avgstack

pro baseline(nfit=nfit, modelbuffer=modelbuffer, ok=ok)#

Fit and subtract a polynomial baseline. The procedure works on the contents of buffer 0 (the primary data container). Both continuum and line data are supported.

See the notes for bshape for more details since this procedure uses bshape for much of its work.

Use bshape if you want to fit the baseline and (usually) show the fit on the plotter without actually subtracting the fit from the data.

Use bsubtract to subtract a baseline using the baseline coefficients stored previously in the !g structure. Coefficients are stored in !g, for example, by running bshape.

Use bmodel to generate a baseline model from the coefficients and store it in the buffer specified in modelbuffer.

Use bshow to overplot a baseline model.

Use subtract to subtract the data of one buffer (which might contain a baseline model) from another.

Keywords:

nfitin, optional, type=integer: The order of the polynomial to fit. Defaults to the value stored in !g.nfit, which can be set by the nfit procedure or, if nfit is set here, then the value of !g.nfit is set too.
modelbuffer ; in, optional, type=integer: The buffer number to hold the evaluated fit (the model).
okout, optional, type=boolean: 1 on success, 0 on failure.

Examples:

; Get some data, set some regions, fit and subtract a 2nd order
; polynomial, storing the model (fitted baseline) into buffer 10.

getrec,20
nregion,[100,500,700,1000,1600,2000]
nfit,2
baseline,modelbuffer=10

; The step involving nfit can be omitted as follows:
baseline,nfit=2,modelbuffer=10

; Examine a fit first, then subtract it.

getnod, 10  ; first get some data
setregion   ; set the baseline region with the cursor
nfit, 5
bshape
baseline

Uses:

bshape bsubtract

pro bias(factor, buffer)#

This procedure adds a scalar bias to the data container’s data.

Equivalent to: !g.s[0].data_ptr = !g.s[0].data_ptr + factor

Params:

factorin, required, type=float: scalar value to be added
bufferin, optional, type=int: The global buffer number containing the data to be adjusted.

Examples:

getrec,1
show
bias,1.3  ; all values in the PDC are now larger by 1.3
show
copy,0,5
bias,2.4,5 ; all values in buffer 5 now larger by 2.4
show

Uses:

dcbias

pro bmodel(modelbuffer=modelbuffer, nfit=nfit, ok=ok)#

Fill in the indicated data container at modelbuffer using the primary data container and the most recently fit parameters in !g.polyfit and !g.nfit. Optionally use a smaller nfit than !g.nfit.

Note: bmodel does not do any fitting. Use baseline or bshape to generate a new fit.

Since orthogonal polynomials are used internally, using up to any nfit less than or equal to the value of nfit used when the polynomials was generated is itself the fit that would have resulted had that smaller nfit been used in the first place. In this way, bmodel can be used to generate the model fit for any value of nfit up to the nfit actually used to generate the most recently fit polynomial.

Keywords:

modelbufferin, optional, type=integer, default=1: The buffer number of the data container to use to hold the model. Defaults to 1 if not supplied.
nfitin, optional, type=integer: Only use at most nfit parameters. If !g.nfit is less then nfit, then only !g.nfit parameters will be used and a warning will be issued.
okout, optional, type=boolean: 1 on success, 0 on failure.

Examples:

; put the model in !g.s[1]
bmodel
; put the model in !g.s[10], using nfit=5
nfit,5
bmodel, modelbuffer=10
; put the model with nfit=2 into buffer 11
bmodel modelbuffer=11, nfit=2

Uses:

DATA_VALID getbasemodel

pro boxcar(width, buffer=buffer, decimate=decimate)#

Smooth the primary data container (the PDC, !g.s[0]) with a boxcar of a certain width, in channels.

Replaces the contents of the data being smoothed with the smoothed data.

For odd width, this uses the built-in idl SMOOTH function. For even widths this uses doboxcar1d and the reference channel is moved left by 1/2 channel width.

Other buffers (0 to 15) can be used instead of the PDC by supplying a value for the buffer keyword.

For spectrum data containers, the frequency_resolution is set using estboxres

Params:

widthin, required, type=integer: Width of boxcar in channels.
bufferin, optional, type=integer, default=0: global buffer number to use (0-15).
decimatein, optional, type=boolean: If set, the data container is reduced - taking every width channels starting at channel 0.

Examples:

getps, 25            ; get some data into the PDC
copy,0,10            ; for use later in this example
copy,0,11            ; also for use later
boxcar, 3            ; 3 channel boxcar smooth
boxcar, 5, buffer=10 ; 5 channel smooth on buffer 10
show,10              ; show the smoothed result
copy,11,0            ; unsmoothed copy back to the PDC
boxcar, 5, /decimate ; with decimation

Uses:

doboxcar1d dcextract

pro bshape(nfit=nfit, noshow=noshow, modelbuffer=modelbuffer, ok=ok, color=color)#

Fit a polynomial baseline to the contents of the primary data container (the PDC, buffer 0) and optionally overplot that fit on to the current plot.

This fits a set of orthogonal polynomials with a maximum order given by the !g.nfit value to the data values in the primary data container. The range of channels to use is given by !g.regions and !g.nregion. The parameters of the fit are placed in to !g.polyfit and the polynomial is evaluated over all channels. That evaluation is placed into the data container at modelbuffer (see the comments for that keyword for more details), which is otherwise a copy of the header information in global buffer 0.

Keywords:

nfitin, optional, type=integer: The order of polynomial to fit. Defaults to !g.nfit. If set, then this also sets the value of !g.nfit.
noshowin, optional, type=boolean: If set, the result is not shown (overplotted). If the plotter is frozen, then nothing is overplotted even if this keyword is not set.
modelbufferin, optional, type=integer: The buffer number to hold the fit evaluated at all channels (the model). If not set then no global buffer will hold the model after this procedure is used.
okout, optional, type=boolean: This is set to 1 on success and 0 on failure.
colorin, optional, type=color: The color to use when overplotting the baseline fit. This defaults to the same default used by gbtoplot

Examples:

; fit, using the value of !g.nfit, set using nfit
nfit,3
bshape
; Or specify an nfit here, keeping the fit in buffer 10
bshape,nfit=3, modelbuffer=10

Uses:

dcbaseline getbasemodel DATA_VALID bmodel

pro bshow(nfit=nfit, ok=ok, color=color)#

Overplot a baseline using the stored coefficients in !g.polyfit and !g.nfit and the data in the primary data container (number of channels only).

Note that bshow does not itself do any fitting. This only show the result of the most recent fit. Since the fitted polynomials are orthogonal, using up to !g.nfit of them is itself a valid fit at the lower order.

Keywords:

nfitin, optional, type=integer: Only use at most nfit parameters. If !g.nfit is less then nfit, then only !g.nfit parameters will be used and a warning will be issued.
okout, optional, type=boolean: This is set to 1 on success and 0 on failure.

colorin, optional, type=color, default=!g.oshowcolor: The color to use for the overplot.

Examples:

bshape, nfit=7, /noshow     ; fit a 7th order polynomial
bshow                       ; show it
bshow, nfit=5, color=!blue  ; show the 5th order fit 

Uses:

getbasemodel gbtoplot

pro bsubtract(nfit=nfit, ok=ok)#

Subtract a baseline using the stored coefficients in !g.polyfit and !g.nfit from the data in the primary data container.

Note that bsubtract does not itself do any fitting. This only subtracts the result of the most recent fit. Since the fitted polynomials are orthogonal, using up to !g.nfit of them is itself a valid fit at the lower order.

Keywords:

nfitin, optional, type=integer: Only use at most nfit parameters. If !g.nfit is less then nfit, then only !g.nfit parameters will be used and a warning will be issued.
okout, optional, type=boolean: 1 on success, 0 on failure.

Examples:

nfit=7
bshape                        ; generate a 7th order fit
copy,0,10                     ; keep for later use
; subtract the baseline
bsubtract
; or, subtract a lower order fit
copy,10,0
bsubtract, nfit=2

Uses:

getbasemodel

pro clearfind(param)#

Clear a selection parameter or several selection parameters used by find

Use setfind to set a selection parameter.

Use listfind to list a selection parameter.

Params:

paramin, optional, type=string: The selection parameter(s) to clear. Minimum-matching is used to find the selection parameters matching this value. If param is not supplied or is an empty string, all parameters are cleared. If all parameters are to be cleared (param is not set or is an empty string) then only those parameters appropriate for the given mode (line or continuum) are cleared.

Examples:

find

pro clip(datamin, datamax, buffer=buffer, blank=blank)#

This procedure truncates, or clips, data values above and below specified limits. Data value can alternatively be blanked using the /blank flag. In that case, data values outside the limits are replaced by blanks (NaN).

Params:

dataminin, required, type=float: min value to clip
datamaxin, required, type=float: max value to clip

Keywords:

bufferin, optional, type=integer, default=0: which global buffer to use.
blankin, optional, type=boolean: Replace clipped values with NaN instead of the clipping limit.

Examples:

getps,101,plnum=1,ifnum=1
show
clip,-0.3,1.4,/blank
show

Uses:

dcclip

pro copy(in, out)#

Copy the data from the in buffer to the out buffer. Anything in out is lost.

This uses the value of !g.line. If it is set (1) then the array of line data (!g.s) is used, otherwise the array of continuum data (!g.c) is used. The contents of the in buffer remain unchanged by this operation.

There are 16 buffers total, numbered from 0 through 15.

Params:

inin, required, type=integer: The buffer to copy values from.
outin, required, type=integer: The buffer to copy the values to.

Examples:

Copy the contents of buffer 0 to buffer 10. Then copy the contents of 9 to buffer 0.

copy, 0, 10
copy, 9, 0

Uses:

set_data_container

pro decimate(nchan, startat=startat, buffer=buffer, ok=ok)#

This procedure thins the spectrum at the primary data container (the PDC, buffer 0) by selecting out and keeping the data at every nth channel. This can also operate on other buffers.

The frequency interval and reference channel are adjusted appropriately so that the x-axis labels for the decimated data are still appropriate.

This can not be used on continuum data containers.

Params:

nchanin, optional, type=integer, default=2: Thin the spectrum by keeping the value at every nchan channels starting from the startat channel. This defaults to 2.

Keywords:

startatin, optional, type=integer, default=0: The starting channel. This defaults to 0.
bufferin, optional, type=buffer, default=0: The buffer to decimate. This defaults to buffer 0 (the PDC).
okout, optional, type=boolean: Returns 1 if everything went ok, 0 if it did not (invalid or empty dc at buffer).

Examples:

getrec,1
show
decimate,2
show
decimate,3,startat=1
show
decimate,2,buffer=1
show, 1

Uses:

dcdecimate show

pro delete(index)#

Remove specific values from the stack.

Params:

indexin, required, type=integer: The values to be removed. Any value in the stack that matches a value in this parameter is removed from the stack.

Examples:

addstack, 10,30,2
delete, [16,18,20]
tellstack
; result is ...
; [ 10, 12, 14, 22, 24, 26, 28, 30]

pro deselect(keep=keep, _EXTRA=ex)#

This procedure is used to remove previously selected index numbers from the stack.

Data can be de-selected by using selection criteria in the same way as in select.

Data can be de-selected based on entries in the index file, such as source name, polarization type, IF number, etc. For a complete list of eligible parameters use the procedure listcols.

See the discussion on “Select” in the GBTIDL manual for a summary of selection syntax.

The selection criteria are ultimately passed to the io class’s search_index via the _EXTRA parameter.

Keywords:

keepin, optional, type=boolean: If set, the selection comes from the keep file. If not set, the selection comes from the input file.
_EXTRAin, optional, type=extra keywords: These are the selection parameters.

Examples:

select, source="ORION"    ; select all ORION data
deselect, scan=15         ; remove scan 15, perhaps it's bad
deselect, ifnum=1         ; remove the IFNUM=1 data

Uses:

select_data delete

pro dirin(dir_name, new_index=new_index)#

Specify a directory from which data will be read. Compare to filein, which identifies a single file as the input source.

When dirin is used, data can be retrieved from any of the SDFITS files in that dir without the need to issue a new filein command.

In line mode, this sets the line input data directory, in continuum mode, this sets the continuum input data directory. Both directories can be opened at the same time and the mode (line or continuum) determines where data is retrieved from (e.g. get). Only one line and one continuum data source (single file or single directory) can be opened at the same time. Use of dirin or filein always first closes any previously opened line or continuum data source before opening a new one.

The opened input file or directory name is stored in !g.line_filein_name (line mode) or !g.cont_filein_name (continuum mode).

Params:

dir_namein, optional, type=string: The directory name to use. If omitted, a file selector GUI will appear and you can select the directory to use. You must select a directory in that case. If the dir_name isn’t a directory, the underlying code will recognize that and it will be as if you had used filein instead.

Keywords:

new_indexin, optional, type=boolean: When set, a new index is generated, whether it needed to be or not. By default, the io code tries to re-use an existing index unless it is seen to be out of date. Regenerating the index file can take some time, but no information should be lost in the process. Usually, the io code can be trusted to regenerate the index file only when necessary.

Examples:

dirin            ; Use a GUI to select the directory
cont             ; switch to continuum mode
dirin,'mydcr'    ; open up all FITS files in a specific directory

Uses:

sdfitsin

pro divide(in1, in2, out)#

This procedure divides the data from two data containers stored in the global buffers 0-15. If no parameters are passed, then the data from buffer 0 is divided by buffer 1 and the result is stored in buffer 0. If two parameters are supplied, the data at the first buffer number is divided by the data at the second buffer number and the result is stored in buffer 0. If three parameters are supplied, the result is stored in the third (output) buffer number.

out = in1 / in2

Params:

in1in, optional, type=integer: First input data buffer number
in2in, optional, type=integer: Second input data buffer number
outin, optional, type=integer: Output data buffer number

Examples:

getrec,1
copy,0,1
getrec,2
divide

getrec,1
copy,0,10
getrec,2
copy,0,11
divide,10,11,12     ; The data from buffer 10 is divided by buffer 11
                    ; and the result is stored in buffer 12

Uses:

dcdivide dcpaircheck

pro emptystack(reset=reset, shrink=shrink)#

Clear the stack.

Normally this simply sets !g.acount to 0, and this is all that is needed for typical use of the stack. Optionally, the procedure can also reset the stack array to zeros and it can shrink the size of the stack to it’s initial size of 5120 elements. That could be useful if the stack grew to an unexpectedly large size and you want to release the memory. The stack will grow as needed when addstack and appendstack are called. Only the !g.acount elements are ever used.

Keywords:

resetin, optional, type=boolean: When set, the values will be reset to 0. This is not required for typical use of the stack.
shrinkin, optional, type=boolean: When set, the size of the array will be reset to its initial size of 5120 elements. This is to reverse any automatic expansion that may have occurred during previous stack operations.

Examples:

addstack,1,100
emptystack
addstack,1,100000
emptystack,/shrink   ; reduce it to 5120 elements

pro filein(file_name, new_index=new_index)#

Specify the SDFITS file from which data will be read.

In line mode, this sets the line input data file, in continuum mode, this sets the continuum input data file. Both files can be opened at the same time and the mode (line or continuum) determines where data is retrieved from (e.g. get). Only one line and one continuum data source (single file or single directory) can be opened at the same time. Use of filein or dirin always first closes any previously opened line or continuum data file or directory before opening a new one.

The opened input file or directory name is stored in !g.line_filein_name (line mode) or !g.cont_filein_name (continuum mode).

Params:

file_namein, optional, type=string: The file name to use. If omitted, a file selector GUI will appear and you can select the file to use. You can not select a directory in that case. If the file_name is a directory, the underlying code will recognize that and it will be as if you had used dirin instead.

Keywords:

new_indexin, optional, type=boolean: When set, a new index is generated, whether it needed to be or not. By default, the io code tries to re-use an existing index unless it is seen to be out of date. Regenerating the index file can take some time, but no information should be lost in the process. Usually, the io code can trusted to regenerate the index file only when necessary.

Examples:

filein                          ; Use a GUI to select the 
                                ; SDFITS file to open
filein,'mydata.fits',/new_index ; force a new index

Uses:

sdfitsin

pro fileout(file_name, new=new)#

Specify the file to which data will be written.

The filename is stored in the !g.line_fileout_name field. At startup, this is set to “GBTIDL_KEEP.fits” so that it is possible to save data without ever using this procedure. The output file name must use the “.fits” suffix.

Note: It is currently not possible to save continuum data.

Params:

file_namein, required, type=string: The file to which data will be written. If the file does not exist, it will be created when the first spectrum is saved to this file (e.g. using keep).

Keywords:

newin, optional, type=boolean: When set a new output file will be created. If file_name already exists, it will first be removed. If there is a problem in removing that file this procedure will return without opening the file_name.

Examples:

getrec,1
show
fileout,'savedfile.fits'
keep

pro files(full=full)#

Prints the file names being used for I/O.

Note: This relies on the information at !g.line_filein_name, !g.cont_filein_name and !g.line_filout_name to be correct. gstatus can also be used to show the files currently in use (along with other GBTIDL information).

Keywords:

fullin, optional, type=boolean: When set, expand the file names to their full paths using the IDL file_expand_path function.

Examples:

filein, '/home/line.fits'
cont
filein, '/home/continuum.fits'
files, /full ; print full path names

spectral line  in : /home/fsfold.fits
spectral line out : /home/GBTIDL_KEEP.fits

continuum  in : /home/continuum.fits

Note: GBTIDL_KEEP.fits is the default output file and it is opened automatically on startup.

pro find(keep=keep, append=append)#

Put entries in to the stack based on the given selection criteria in the global find structure. This is an alternative to select.

Use setfind to set specific selection criteria. Once set, they remain set until cleared using clearfind. FIND uses those selection criteria and select to add entries to the stack corresponding to items in the data source that match the selection criteria. The stack can then be iterated through to process just the most recently found data.

Note: unlike select, find clears the stack unless the /append keyword is used. This has been done to make the behavior of FIND more like the CLASS version of FIND.

Keywords:

appendin, optional, type=boolean: When set, the stack is not first cleared before select is used to add values to the stack. Use this with some caution since this may cause the same entries to appear more than once in the stack unless the selection criteria used by FIND are changed carefully.
keepin, optional, type=boolean: Select entries from the currently attached output (keep) file.

Examples:

; define the selection
setfind,'scan',100,200          ; scans 100 through 200
find
; refine it
setfind,'polarization','LL'     ; only the LL polarization
find
; refine it
setfind,'int','2:3'             ; only integrations 2 and 3
find
; refine it
setfind,'int',4,/append         ; add integration 4 to the set
find
; this is equivalent to the previous 2 setfind examples.
; note that any valid selection string can be used
setfind,'int','2:3,4'
setfind,'polarization','RR'     ; the other polarization
find,/append                    ; the LL selection is still there due to /append
clearfind,'int'                 ; clear the integration parameter
find                            ; all integrations, RR polarization, scans 100 to 200.

If you often set the same parameter, you can write a procedure, as in this example, to save yourself time. You might add optional feedback to the user that the parameter was set and you might add additional parameter checks.

pro setsrc,src
    setfind,'source',src
end

Uses:

emptystack select

function find_paired_info(info, keep=keep)#

Find the scan_info associated with the paired scan implied by the supplied scan_info structure. See scan_info for a description of the contents of the structure expected as the info argument as well as the structure returned by this function.

Scan’s often come in pairs (OnOff,OffOn,Nod). When the possibility of repeated scan numbers at different times and in different files (in the case of the use of dirin to open more than one fits file at a time) is taken into account, it becomes non-trivial to find the scan that is paired with a known scan. This routine uses that known scan’s scan_info structure to find the scan_info structure associated with the best guess as to the location of that scan’s pair. This returns -1 if no suitable paired scan could be found.

The paired scan must have the appropriate relative scan number as implied by info.procseqn. Since this works for scans taken as a pair by the same procedure then only procseqns of 1 or 2 are allowed. If the procseqn in the info parameter (info.procseqn) is 1, then the paired scan must have a procseqn of 2. Similarly, if info.procseqn is 2 then the paired scan must have a procseqn of 1.

The paired scan must be found in the same file as given by info.file.

When file and procseqn are not sufficient to resolve all ambiguities, then the scan closest to the info.timestamp in the appropriate direction is used to identify the best guess at the paired scan. Appropriate direction means that if info.procseqn implies that the paired scan came after the scan described by info, then it’s timestamp must be after info.timestamp. Similarly, if the paired scan must have come before the scan described by info, then it’s timestamp must come before info.timestamp.

This is primarily useful inside of the calibration routines (e.g. getps) but it may also be useful to users writing their own processing routines.

Params:

infoin, required, type=structure: The scan_info structure of the scan who’s pair is desired.

Keywords:

keepin, optional, type=boolean: When present, search the output file.

Returns:

The paired scan’s scan_info structure. If no pair could be found, returns -1

pro fitgauss(fit, fitrms, modelbuffer=modelbuffer, highlightcolor=highlightcolor)#

An interactive procedure that allows the user to fit gaussians.

The user should first subtract a baseline from the data prior to using this procedure. Next, use the plotter zoom feature to narrow in on the region of interest. Then run fitgauss. Click the left mouse button to mark the regions to be considered in the fit. Then click the middle mouse button, twice for each gaussian to be fit, first at the (guessed) peak of the line, and then at the half-power point. Repeat the middle mouse clicks as many times as you like to fit multiple components. Finally click the right mouse button to actually do the fit and display the results.

Each guassian (middle mouse clicks) must be found in an already set region (left mouse button). Use the right mouse button to exit at any time (will require 2 right clicks to quit the procedure in the middle of a step - marking a region or identifying a gaussian).

Params:

fitout, optional, type=array: An output array giving the results of the fit. Also stored in !g.gauss.fit.
fitrmsout, optional, type=array: An output array giving the uncertainties of the fit. Also stored in !g.gauss.fitrms.

Keywords:

modelbufferin, optional, type=long, default=-1: The buffer number to hold the resulting model. If not set (the default) then the model is not saved to a global buffer.
highlightcolorin, optional, type=color, default=!g.highlightcolor: The color to use after the region of interest has been selected to highlight the data.

Examples:

fitgauss,modelbuffer=10   ; fit gaussian and store model in buffer 10
show
subtract,0,10,11          ; store residual in buffer 11
oshow, 11                 ; overlay residual
oshow, 10, color=!yellow  ; overlay gaussian model

pro flag(scan, intnum=intnum, plnum=plnum, ifnum=ifnum, fdnum=fdnum, sampler=sampler, bchan=bchan, echan=echan, chans=chans, chanwidth=chanwidth, idstring=idstring, scanrange=scanrange, keep=keep)#

Flag some data in the currently opened spectral line data file or output (keep) data file.

A scan number or array of scan numbers is required and can be entered either in the parameter scan or the parameter scanrange. The other keywords allow for additional refinements in the scope of the flag. When a keyword is not supplied, it defaults to all values of that keyword in the data for the given scans. In some cases, when you know which specific record needs some or all of its data flagged, flagrec may be more appropriate.

Flags are applied when the data is actually read into a data container (e.g. using get, getrec, getps, getnod, etc). At that point, any flagged data is replaced with the special value for blanked data (NaN, or “not a number”). GBTIDL ignores blanked data. If that data is saved back to a data file, it will be saved as blanked values and no further flagging is necessary. Flags are associated with the data in the file, not with the data in a data container. Once the data is in GBTIDL in a data container, it can have additional blanking applied (e.g. replace) but not flagged.

The sampler argument can be used to specify a specific sampler name to flag. The samplerinfo function is used to translate that name into a single plnum, ifnum, -and fdnum combination which is then used to set this flag. The listing of data flagged by sampler name will only show these integer values, not the original sampler name. When sampler is used, it is an error to also use plnum, ifnum or fdnum in the same call to flag. A single scan (not a scan range) must be used if sampler is supplied.

Continuum flagging is not supported.

See also the “Introduction to Flagging and Blanking Data” in the GBTIDL manual.

Params:

scanin, optional, type=integer: M&C scan numbers to flag. This is required if scanrange is not used.

Keywords:

intnumin, optional, type=integer: Integration number (default=all)
plnumin, optional, type=integer: polarization number (default=all)
ifnumin, optional, type=integer: IF number (default=all)
fdnumin, optional, type=integer: Feed number (default=all)
samplerin, optional, type=string: Sampler name, used only as a short-hand for a specific plnum, ifnum, fdnum combination. When sampler is supplied it is an error to also supply ifnum, plnum, or fdnum. Sampler must be single-valued (no arrays).
bchanin, optional, type=integer: Starting channel number(s) (default=0)
echanin, optional, type=integer: Ending channel number(s) (default=last channel)
chansin, optional, type=integer: Channel to flag. Mutually exclusive to bchan and echan keywords.
chanwidthin, optional, type=integer: Buffer of channels surrounding the channels specified in chans keyword. (default=1)
idstringin, optional, type=string, default=”unspecified”: A short string describing the flag.
scanrangein, optional, type=integer array: A 2-element array giving the first and last scan numbers that describe the range of scans to flag. This is ignored if the scan parameter is used. If only one integer is supplied then this is equivalent to giving that integer as the scan parameter argument.
keepin, optional, type=boolean: Flag the keep (output) data source.

Examples:

; flags all the channels in scan number one
flag, 1 

; flags just the first ten channels in scan two
flag, 2, echan=10, idstring="flag first 10 channels"

; flags the first ten channels, and channels 50 to 60
flag, 3, bchan=[0,50], echan=[10,60]

; flags the same channels as the above example in scan four
flag, 4, chans=[5,55], width=5

; flag all channels in scan 5, integrations 1 through 4
flag, 5, intnum=[1,2,3,4], idstring="RFI"

; flag just this one channel for scan 6, for just the first polarization
flag, 6, plnum=0, chans=2999

; flag first polarization, second feed, third IF, all channels
flag, 7, plnum=0, fdnum=1, ifnum=2, idstring="Bad Lags"

; If the previous example corresponded to sampler "B17" then
; this example would produce the same flag rule
flag, 7, sampler="B17", idstring="Bad Lags"

pro flagrec(record, bchan=bchan, echan=echan, chans=chans, chanwidth=chanwidth, idstring=idstring, keep=keep)#

Flag a specific record or records in the currently open spectral line data file.

A record number or array of record numbers must be supplied. This routine will flag the indicated channels (or all channels, if bchan and echan are not used) in those record numbers. This is appropriate if you know exactly which specific records need to be flagged. It is usually easier to use flag and let it work out which records should be flagged. A record number is simply the index number for that spectrum in the input data set.

Flags are applied when the data is actually read into a data container (e.g. get, getrec, getps, getnod, etc). At that point, any flagged data is replaced with the blanked value (not a number, NaN). GBTIDL ignores blanked data. If that data is saved back to a data file, it will be saved as blanked values and no further flagging is necessary. Flags are associated with the data in the file, not with the data in a data container. Once the data is in GBTIDL in a data container, it can be blanked (e.g. replace) but not flagged.

Continuum flagging is not supported.

See also the “Introduction to Flagging and Blanking Data” in the GBTIDL manual.

Params:

recordin, required, type=integer: The record numbers to be flagged.

Keywords:

bchanin, optional, type=integer: Starting channel number (default=0)
echanin, optional, type=integer: Ending channel number (default=last channel)
chansin, optional, type=integer: Channels to flag. Mutually exclusive to bchan and echan keywords.
chanwidthin, optional, type=integer: Buffer of channels surrounding the channels specified in chans keyword. (default=1)
idstringin, optional, type=string, default=”unspecified”: A short string describing the flag.
keepin, optional, type=boolean: Flag the keep (output) data source.

Examples:

; flags all the channels in record number one
flagrec, 1

; flags just the first ten channels in record two
flagrec, 2, echan=10, idstring="flag first 10 channels"

; flags the first ten channels, and channels 50 to 60
flagrec, 3, bchan=[0,50], echan=[10,60]

; flags the same channels as the above example in record four
flagrec, 4, chans=[5,55], width=5

pro flagspurs(flagcenteradc=flagcenteradc)#

Set the flags for the VEGAS spurs in the currently opened input data source (either a single sdfits file or a directory).

VEGAS produces spurs (spikes) at channels corresponding to integer multiples of the ADC sampler frequency divided by 64. The normal behavior of sdfits is to flag these channels when the data are filled (use listflags to see the list of flags for the currently opened input data set). This routine can be used to recreate those flags if the original flag file has been lost or corrupted.

A spur is also produced at the center channel (NCHAN/2 when counting from 0). That spur does not arise in the ADC in VEGAS and so does not move as the spectral window is tuned across the ADC bandpass. This routine does not flag that spur. Normal sdfits use will replace that spur with the average of the two adjacent channels and so it generally is not necessary to flag that spur. Since that spur does not move as the spectral window is tuned it can be flagged using the standard flag command if necessary.

The routine first unflags all flags with the idstring “VEGAS_SPUR”

This routine expects to encounter uncalibrated VEGAS data filled by sdfits. It checks that there is both an SDFITVER keyword and an INSTRUME keyword on the primary header of all SDFITS files. The value of the INSTRUME keyword must be “VEGAS”.

This spur locations are determined using the VSPDELT, VSPRPIX, and VSPRVAL columns. For data filled using older versions of sdfits, these values are not present in the SDFITS tables. Such older data should be refilled using the most recent version of sdfits to make use of this procedure.

Keywords:

flagcenteradcin, optional, type=boolean: When set, the center ADC spur is also flagged. Normally that spur is left unflagged because sdfits usually replaces the value at that location with an average of the two adjacent channels and so that spur does not need to be flagged since it’s been interpolated.

pro fold(sig, ref, ftol=ftol, blankinterp=blankinterp, nomask=nomask)#

Average two parts of in-band frequency switching (signal and reference phases, with the cal-switching phases already calibrated).

Typically this happens during or after getfs. The two data containers are assumed to be in 0 and 1. It does not matter which data container contains which part since their relative distance in frequency is used to determine how one is shifted to align with the other. The result is always placed in data container 0. If the two data containers do not overlap in frequency, then there is nothing to fold and an error message will be printed.

The ref data container is shifted to align in sky frequency with the sig data container using dcshift and the two data containers are averaged - weighting each by the inverse of square of their system temperatures. The system temperature in the result is the weighted average of the two system temperatures.

If there are any blanked channels in either sig or ref then the corresponding channels in the other spectrum, after ref has been shifted to align in sky frequency with sig, are also blanked so that the average at those channels is blanked. This is done to avoid the appearance of a spike at a blanked channel where the contribution from the other spectrum, after the shift, is typically not blanked and not equal to the local average of surrounding, non-blanked, channels. This behavior can be turned off by the nomask keyword. Alternatively, all blanked channels in sig and ref can be replaced using a linear interpolation from adjacent non-blanked channels (a simple average in the case of single, isolated, blanked channels) using the blankinterp keyword.

Params:

sigin, optional, type=integer, default=0: The global buffer number to use as the signal part in the average. The result will contain a copy of this data container’s header information except for tsys as described above. The data at sig is overwritten by the result if sig is 0 (the default)
refin, optional, type=integer, default=1: The global buffer number to use as the reference part in the average. This data is shifted using dcshift to align with sig before averaging. The data in ref are never altered by this procedure.

Keywords:

ftolin, optional, type=double, default=0.005: The fractional channel shift tolerance. If the fractional part of the channel shift necessary to align the two parts is less than this value, no fractional shift as described in the documentation for dcshift will be done. It might be useful to turn off the fractional shift because it can cause aliases and ringing in the case of very strong lines or other sharp features. If ftol > 0.5 no fractional shifts will be done.
blankinterpin, optional, type=boolean: When set, blanks are replaced before shifting and averaging by a linear interpolation using the finite values found in the two spectra. The dcinterp procedure is used. For isolated blanked channels, the replacement value is the average of the two adjacent channel values.
nomaskin, optional, type=boolean: When set, turn off the masking of blank channels from each spectrum on to the other, after the shift. This may result in spikes at the location of blanked channels. This was the original behavior of this routine. This keyword has no effect if blankinterp is set.

Examples:

getfs, 64, /nofold
fold, ftol=1.0       ; no fractional shifting is done

Uses:

dcfold DATA_FREE set_data_container

function fshift(accumnum, buffer=buffer, frame=frame)#

Function to calculate the shift, in channels, necessary to align in frequency the primary data container with the data container template in an ongoing accumulation.

You can use an alternate data container by setting buffer. You can use an alternate global accumulation buffer by setting accumnum.

If the frame is not set, the one implied by the data header is used. Use xshift to align using the current settings of the plotter’s x-axis.

Params:

accumnumin, type=integer, default=0: accum buffer to use. Defaults to the primary buffer, 0. There are 4 buffers total so this value must be between 0 and 3, inclusive.

Keywords:

bufferin, optional, type=integer, default=0: The global buffer that will eventually be shifted. Defaults to the primary data container (buffer 0).
framein, optional, type=string: The reference frame to use. If not supplied, the value implied by the last 4 characters of the velocity_definition in the ongoing accumulation will be used. See frame_velocity for a full list of supported reference frames.

Returns:

shift, in channels, to be used as argument to shift. Returns 0.0 on failure.

Examples:

getps,30
accum             ; accum first spectrum, no alignment needed yet
getps,31
fs = fshift()     ; determine the shift to align scan 31 with scan 30
gshift,fs         ; apply the shift to scan 31
accum             ; and add the result to the accumulator
getps, 32
gshift, fshift()  ; all in one line, shift scan 32 to align with scan 30
accum
ave

Uses:

dcfshift

pro gauss(buffer=buffer, modelbuffer=modelbuffer, ok=ok, quiet=quiet, fit, fitrms)#

Fits Gaussians to the data in the primary data container (!g.s[0]) based on initial values that can be set by procedures gregion, ngauss, gmaxiter, and gparamvalues.

Other data containers can be fit using the buffer keyword.

Multiple gaussians in multiple regions can be fit at the same time.

The initial guesses and the most recent fit are available in the !g.gauss structure.

Params:

fitout, optional, type=array: results of fit. identical to !g.gauss.fit
fitrmsout, optional, type=array: errors of fit. identical to !g.gauss.fitrms

Keywords:

buffer in, optional, type=long, default=0: global buffer number whose data is to be fit. Defaults to the primary data container.
modelbufferin, optional, type=long, default=-1: buffer number to hold the resulting model. If not set (the default) then no global buffer is filled with the model.
okout, optional, type=long: result; 1 - good, 0 - bad
quietin, optional, type=boolean, default=F: When set, no report of the fits and initial guesses is printed.

Examples:

Typically, fitgauss will be used to set the initial guesses and do the fit, using gauss. Internally, fitgauss does these steps.

; using the user-identified points, set the region(s)
gregion,[4120,4400]   ; channels 4120 through 4400 inclusive
ngauss,2              ; fit 2 gaussians
; for each gaussian, do this
gparamvalues, 0, [2.4, 4359.0, 12.3]  ; [height, center, fwhm]
gparamvalues, 1, [0.5, 4370.0, 9.2] 
gauss
gshow

Continuum data containers can also be fit (must be in continuum mode).

cont                ; switch to cont mode
filein,'peaks.fits'
get,buffer=1        ; get some data
; setup the gauss fit
gregion,[60,80]
ngauss,1
gmaxiter,500
gparamvalues, 0, [400000.,70.,100.]
; find and show the fit
gauss
gshow

Uses:

gauss_fits report_gauss

pro gconvol(kernel, scale_factor, buffer=buffer, ok=ok, normalize=normalize, _extra=extra_keywords)#

A GUIDE front-end to the standard IDL CONVOL function.

This allows GUIDE users to convolve a data container with an arbitrary kernel using the IDL CONVOL function. All of the arguments except the dc keyword have the same meaning and use as in the CONVOL function. Users should consult the IDL documentation for CONVOL for a more detailed explanation than is given here. All of the CONVOL keywords are passed in through the _EXTRA keyword are so are not shown explicitly here. These keywords are /CENTER, /EDGE_WRAP, /EDGE_TRUNCATE, MISSING, /NAN, and /NORMALIZE

This procedure follows the GUIDE model and the result of the convolution replaces the original data values in the indicated data container.

NORMALIZE was added in IDL 6.2. It is essential when working with blanked data (NAN). It is implemented here so that it works for earlier version of IDL. For IDL 6.2 and later, /NORMALIZE is passed directly to CONVOL. For earlier versions of IDL, a second convolution is done using a vector of 1.0s having the same length as the data and blanked in the same locations as the data. The convolution of the data is then divided by this convolution and the result is put back into the data container. BIAS was also added in IDL 6.2 but that functionality isn’t necessary for the rest of GBTIDL and so it has not been implemented here apart from what CONVOL provides in IDL 6.2

Params:

kernelin, required, type=array: The kernel to use in the convolution. Must have fewer elements than the data container being convolved.
scale_factorin, optional, type=real, default=1: The scale factor.

Keywords:

bufferin, optional, type=integer, default=0: The data container buffer to use in the convolution.
okout, optional, type=boolean: Returns 1 if everything went ok, 0 if it did not (empty or invalid buffer, bad kernel).
normalizein, optional, type=boolean: Set this keyword to automatically compute a scale factor and bias and apply it to the result values. If this keyword is set, the scale_factor argument and the BIAS keyword are ignored. For all input types, the scale factor is defined as the sum of the absolute values of Kernel. If blanked (NAN) values are present, the scale factor and bias are calculated without using those values so that all result values are comparable in magnitude.
_extrain, optional, type=extra keywords: Keyword arguments to CONVOL. See the IDL documentation on CONVOL for more information.

Examples:

; hanning smoothing kernel
kernel = [0.25,0.5,0.25]
; convolve with the data in the primary data container
gconvol, kernel
; same kernel, using DC 1, ignore NAN (missing) values, 
; truncate the data at the edges, normalize the result.
; This is how the hanning procedure is implemented.
gconvol, kernel, buffer=1, /nan, /edge_truncate, /normalize

Uses:

getdata setdata

pro get(useflag=useflag, skipflag=skipflag, _EXTRA=ex)#

Get data from the input data file and put that into the primary data container (buffer 0).

The data to be retrieved are specified by giving a number of selection parameters. If more than one record satisfies the selection criteria given, only the first is returned. If you need to retrieve one of the other records you must first refine the selection criteria. A better approach might be to use select to get the list of records that satisfy that selection and then use getrec to get the individual records.

Note: All of the data satisfying the selection criteria (or lack of criteria if none are given) are extracted from the file before this routine copies the first one found and puts it into buffer 0. There is no protection against running out of memory by grabbing too much data.

Run the procedure listcols to see a complete list of selection parameters.

See the discussion on “Select” in the GBTIDL User’s Guide here for a summary of selection syntax.

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 any 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.

Keywords:

useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?
_EXTRAin, optional, type=extra keywords: These are selection parameters that determine which data to retrieve.

Examples:

filein,'my_raw_data.fits'
listcols                  ; show the parameters that can be used
get,index=0               ; retrieves the first record
copy, 0, 10
get, scan=6, plnum=0, ifnum=1, int=2
oshow, 10
get, scan=6, plnum=0, ifnum=1, int=2, /skipflag ; ignore all flags
; in this next example, only flags with idstring='wind' are ignored.
get, scan=6, plnum=0, ifnum=1, int=2, skipflag='wind'

Uses:

set_data_container

function get_scan_numbers(count, keep=keep, unique=unique, _EXTRA=ex)#

Function to return scan numbers for the input file.

This returns the different scan numbers in the order they appear in the input file. Use the keep flag to get the scan numbers from the output file. For example, if list shows these scan numbers: 99, 99, 99, 100, 99, 99, 100, 100, 101, 101, then get_scan_numbers will return this array [99, 100, 99, 100, 101]. If unique is set it will return this array [99, 100, 101].

The default behavior (without the unique flag set) is a useful check to see if a scan number repeats itself in a raw data file. That may cause processing problems since the standard calibration routines rely on scan numbers not appearing again later in the same data file. If you want to simply see which scan numbers appear in a data file where repeating scan numbers is expected or not otherwise a problem (e.g. an output file containing processed data), use the unique flag.

Selection fields can be used here in the same way that they can be used in other data selection procedures and functions. For a complete list of eligible parameters use the procedure listcols

See the discussion on “Select” in the GBTIDL manual for a summary of selection syntax.

The selection criteria are ultimately passed to the io class’s search_index via the _EXTRA parameter.

Params:

countout, optional, type=integer: The number of scan numbers returned. This is 0 when no scan numbers are in the file (the returned value from this function will also be -1 in that case).

Keywords:

keepin, optional, type=boolean: If set, the scan numbers come from the output file.
uniquein, optional, type=boolean: If set, the unique scan numbers are returned. This is a sorted list and it is impossible to tell if there are any duplicate scan numbers.
_EXTRAin, optional, type=extra keywords: These are the selection parameters.

Returns:

an array of scan numbers. Returns -1 (an illegal scan number) if the file is empty, or nothing matches the selection criteria.

Examples:

a = get_scan_numbers()
print,a
a = get_scan_numbers(source='3C*',/unique)
print,a

function getbasemodel(nfit=nfit, ok=ok)#

Function to return the polynomial using the most recently fitted baseline coefficients and !g.nfit or the nfit keyword using the data in the primary data container. This function is used in all of the GUIDE baseline related functions but may also be useful in other uses.

Note that getbasemodel does not do any fitting. Use baseline or bshape to generate a new fit.

Since orthogonal polynomials are used internally, using up to any nfit less than or equal to the value of nfit used when the polynomials were generated is itself the fit that would have resulted had that smaller nfit been used in the first place. In this way, getbasemodel can be used to generate the model fit for any value of nfit up to the nfit actually used to generate the most recently fit polynomial.

Keywords:

nfitin, optional, type=integer: Only use at most nfit parameters. If !g.nfit is less then nfit, then only !g.nfit parameters will be used and a warning will be issued.
okout, optional, type=boolean: 1 on success, 0 on failure.

Returns:

Array corresponding to the polynomial at !g,polyfit through nfit evaluated at all of the channels in the primary data container. Returns -1 on failure (ok will be 0).

Examples:

getrec, 20                            ; get some data
nregion,[100,500,700,1000,1600,2000]  ; set up regions to fit
nfit,7                                ; 7th order fit
bmodel                                ; do the fit
lastfit = getbasemodel()              ; get the fit
lastfit_n2 = getbasemodel(nfit=2)     ; only use up to 2nd order terms

Uses:

ortho_poly DATA_VALID

pro getbs(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, trackfdnum=trackfdnum, sampler=sampler, bswitch=bswitch, tau=tau, tsys=tsys, ap_eff=ap_eff, smthoff=smthoff, units=units, eqweight=eqweight, tcal=tcal, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

Procedure getbs retrieves and calibrates a beam switched Nod scan pair.

Beam switched modes are not recommended on the GBT. Total power Nod should be used instead. To process total power nod data use getnod instead of this routine. This procedure is provided only to accommodate old data.

The getbs routine produces a spectrum calibrated in Ta (K). Other recognized unit are Ta* and Jy.

Summary

Data are selected using scan, ifnum, intnum and plnum or, alternatively, sampler and intnum if you know the specific sampler name (e.g. “A10”). The other scan in the scan pair is found using scan (see comments below).
In beam switched data, there are two beams in each scan, some of that data comes from the signal phase, some of it from the reference phase and in each of those there is cal on and cal off data. So, there are 4 switching states in this data.
Individual integrations are processed separately with the same integration number in the two scans processed together. Both scans must have the same number of integrations. Each integration is processed using donod.
The integrations are calibrated in Ta (K). If units of Ta* or Jy are requested via the units keyword, then dcsetunits is used to convert to the desired units.
Within each integration, there are spectra identified as coming from beam 1 and other spectra identified as combing from beam 2. Some of those in each scan come from the signal switching phase and some come from the reference switching phase. The signal data from each integration is processed together using donod and the reference data from each integration is processed together also using donod. The reference data is multiplied by -1 before it is averaged with the signal data for that integration. The bswitch keyword can be used to limit which data is processed.
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.
The final average is left in the primary data container (buffer 0), and a summary line is printed. The printing of the summary line can be suppressed by setting the quiet keyword. The first Tys displayed is that of the result. The other 4 Tsys values displayed are weighted averages of the Tsys values from each of the 4 spectra that make up each integration (see donod for more details). In the case of bswitch=0, the signal and reference tsys values are averaged together. This can be useful in assessing the quality of the parts of the data that make up the final result.
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. In the case of bswitch=0, all 8 spectra comprising each integration are kept.

Parameters

The scan number is required. Either scan in the “Nod” scan pair can be given. Arguments to identify the IF number, polarization number, and feed number are optional. The default tracking feed number, trackfdnum, (0) is the lowest numbered FEED found in the data. This feed number is interpreted as the tracking (source) feed for the first scan in the signal phase. Specify trackfdnum=1 to identify the second FEED as the tracking feed. Tracking feed in this context means that the source signal was in that beam during the source phase of the first scan of the two “Nod” scans.

If ifnum, trackfdnum, 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, after using any user-supplied values. The value of ifnum is determined first, followed by trackfdnum and finally plnum. If a combination with data cannot be found then showiftab is used to show the user what the set of valid combinations are. The summary line includes the ifnum, trackfdnum, and plnum used.

Tsys and Available Units

The procedure calculates Tsys based on the Tcal values and the data in the non-source feeds (both scans). 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 spectra prior to calibration. 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.

The Special “bswitch” Keyword

A parameter called bswitch allows the user to select between using all of the data (the detault, bswitch=0) or using only data when the beam switch is in the “cross” (reference) or “thru” (signal) position. Data taken in beam switched mode should be examined carefully in both cross and thru positions.

Weighting of Integrations in Scan Average

By default, internal 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.

Summary Information

The scan number printed in the status line is that of the first scan in the “Nod” pair - no matter which scan number you actually provided as the scan parameter here. The values of ifnum, trackfdnum, and plnum are shown after the scan number. The first Tsys printed is the tsys value in the result. This is a weighted average of the Tsys values in the reference beams from both scans as described in donod The other 4 Tsys values printed on the status line are the 4 Tsys values calculated by donod and averaged (using the appropriate weighting scheme) over all integrations and beam switch positions.

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 any 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 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.

Once a unique match is found to the desired scan (using instance, file, or timestamp) then the scan paired with that scan necessary to finish this procedure is found. The match must be found within the same file as the desired scan. It must have the appropriate matching scan number (scan-1 if scan is the second scan in the procedure or scan+1 if scan is the first scan in the procedure). If those two rules are not sufficient to find a unique match, the matching scan with the closest timestamp in the appropriate direction (before or after depending on which procseqn is associate with scan) is used. Finally, the matched pair must have the appropriate procseqn given the procseqn that scan is.

Note: If you see the message “No data found, cannot continue” the most likely explanation is that the IF numbers are confused, probably due to a bad configuration (e.g. both feeds do not have data from the same IF and polarization). Consequently, this calibration routine can not reduce that data. It is likely that all of the IFNUM values for this data are -1.

Params:

scanin, required, type=integer: M&C scan number

Keywords:

ifnumin, optional, type=integer: IF number (starting with 0). Defaults to the lowest value associated with data taking into account any user-supplied values for trackfdnum, and plnum.
intnumin, optional, type=integer: Integration number, defaults to all integrations.
plnumin, optional, type=integer: Polarization number (starting with 0). Defaults to the lowest value with data after determining the values of ifnum and trackfdnum if not supplied by the user.
samplerin, optional, type=string: sampler name, this is an alternative way to specify ifnum and plnum. When sampler name is given, ifnum and plnum must not be given. Note that data from the associated switched sampler will also be used.
trackfdnumin, optional, type=integer: Tracking 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.
bswitchin, optional, type=integer: determines which beamswitch positions are used. 0=both, 1=ref, 2=sig (default 0)
tauin, optional, type=float: tau at zenith, if not supplied, it is estimated using :idl:pro: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. tsys {in}{optional}{type=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.
ap_effin, optional, type=float: Aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoffin, optional, type=integer: smooth factor for reference spectrum, defaults to 1 (no smoothing).
unitsin, optional, type=string: takes the value ‘Jy’, ‘Ta’, or ‘Ta*’, default ‘Ta’.
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0). Default is unset.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This will not have any effect on error messages. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurrence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is all files currently opened.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
statusout, optional, type=integer: An output parameter 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 possible saved to the output file if keepints was set) but there was a problem with the final average and buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when using getbs within another procedure or function.

Examples:

; average both polarizations from ifnum=1
sclear
getbs, 76, ifnum=1, plnum=0
accum
getbs, 76, ifnum=1, plnum=1
accum
ave

Uses:

accumave accumclear DATA_FREE dcaccum dcscale dcsetunits donod find_paired_info set_data_container showiftab

pro getcal(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, fdnum=fdnum, sampler=sampler, eqweight=eqweight, tcal=tcal, sig_state=sig_state, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

This procedure retrieves the “cal” signal from a cal-switched scan.

This code can be used as a template for the user who may wish to develop more tailored calibration schemes.

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 using docal. This differences the two switching phases (with cal and without cal) and calculates a mean system temperature.
Averaging of individual integrations is 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.
The final average is left in the primary data container (buffer 0), and a summary line is printed. The printing of the summary line can be suppressed by setting the quiet keyword.
This can be used on sig-switching data (frequency-switched data). Use the sig_state keyword to select the signal state (1) or the reference state (0). Otherwise all data are used.

Parameters

The scan number is required. Arguments to identify the IF number, polarization number and feed number are optional. The procedure calculates Tsys based on the Tcal values and the data. The Tcal value comes from the mean_tcal value in cal_off phase data container unless the user supplies a value using the tcal keyword. In that case, one tcal value is supplied and that value is used for all integrations processed here. The two switching phases are differenced and a system temperature (Tsys) is calculated in the docal procedure. See the documentation for that procedure for details of the Tsys calculation.

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.

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.

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 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.

Params:

scanin, required, type=integer: M&C scan number

Keywords:

ifnumin, optional, type=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.
intnumin, optional, type=integer: Integration number (starting with 0), defaults to all integrations.
plnumin, optional, type=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.
fdnumin, optional, type=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.
samplerin, optional, type=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.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0). Default is unset.
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
sig_statein, optional, type=integer: For use with sig-switched data. If sig_state is 1 then only the signal data are used, if sig_state is 0 then only the reference data are used.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This will not affect error messages. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This keyword is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string, default=unset: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurrence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is to search all files currently opened.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
statusout, optional, type=integer: An output parameter 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 buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when using gecal within another procedure or function.

Uses:

accumave accumclear DATA_FREE dcaccum dcscale docal set_data_container showiftab

function getchunk(count=count, keep=keep, useflag=useflag, skipflag=skipflag, indicies=indicies, _EXTRA=ex)#

A function to get several data containers from an input file in one call.

It is more efficient to retrieve multiple data containers in one call. Because the global data buffers all contain a single data container, this function does not interact directly with the global buffers, as other data retrieval procedures do. Instead, it returns an array of data containers that must then be handled appropriately by the user.

Note that it is the responsibility of the caller to explicitly free the pointers used in this array of data containers. Simply use data_free as shown in the examples below.

The usual data selection operations can be specified in this function.

There is no protection against running out of memory. If one does not carefully select the data to be fetched or even avoids specifying any arguments to getchunk, all of the data that matches that selection (which might be all of the data in the file) will be read from disk into memory. That might be more memory than you have and this procedure does not protect you against that. Use this function carefully.

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 any 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.

Keywords:

countout, optional, type=integer: An output value giving the number of data containers actually returned.
keepin, optional, type=boolean: When set, the data are fetched from the output file.
useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?
indiciesout, optional, type=long: Array of index numbers, one for each spectrum retrieved. Returns -1 when no spectra were returned.
_EXTRAin, optional, type=extra keywords: These are selection parameters to specify which data to retrieve. See listcols for a complete list of the columns available. Also see the discussion on “Select” in the GBTIDL manual for a summary of selection syntax.

Returns:

An array of data containers. If no data satisfy the selection criteria, count will be 0 and the returned value will be -1.

Examples:

In the first example, we copy the input file to the keep file (currently only possible in line mode), one scan at a time. This would be done in a procedure, not at the command line, because of the loop.

scans=get_scan_numbers(/unique)
for i=0,(n_elements(scan)-1) do begin
    a = getchunk(scan=scans[i])
    putchunk, a
    data_free, a
endfor

In the next example, we average all of the data for a given scan. This example also shows that we have choosen to ignore any flags with idstring=’wind’. This could be done at the command line because the loop is contained on a single line.

sclear
a = getchunk(scan=6000,count=count,skipflag='wind')
accum,dc=a[0]
for i=1,(count-1) do accum,dc=a[i]
ave
data_free,a

function getdata(buffer, elements, count=count)#

Extract some or all of the data array from one of the global buffers.

Use of getdata frees the user from having to deal with pointers by providing a copy of some or all of the data array in one of the global buffers (data containers).

Params:

bufferin, optional, type=integer, default=0: The data container buffer from which the data are retrieved (defaults to buffer 0).
elementsin, optional, type=integer, default=all: A subset of the full data array can be retrieved by specifying either a single data array index, or a two-element array to specify a range of data array indices. Defaults to all elements.

Keywords:

countout, optional, type=integer: The total number of elements returned. On error, this will be 0 and the returned value for this function will be -1.

Returns:

The extracted data.

Examples:

filein,'file.fits'
getrec,0
x = getdata()
help, x
X               FLOAT     = Array[1026]
y = getdata(0,0)
help, y
Y               FLOAT     = 34.5000
z = getdata(0,[0,2])
help, z
z               FLOAT     = Array[3]

Uses:

data_valid getdcdata

pro getfs(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, fdnum=fdnum, sampler=sampler, tsys=tsys, tau=tau, ap_eff=ap_eff, smthoff=smthoff, units=units, nofold=nofold, blankinterp=blankinterp, nomask=nomask, eqweight=eqweight, tcal=tcal, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

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 cannot 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 cannot 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.

Params:

scanin, required, type=integer: scan number

Keywords:

ifnumin, optional, type=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.
intnumin, optional, type=integer: integration number, default is all integrations.
plnumin, optional, type=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.
fdnumin, optional, type=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.
samplerin, optional, type=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.
tsysin, optional, type=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.
tauin, optional, type=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_effin, optional, type=float: aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoffin, optional, type=integer: smooth factor for reference spectrum
unitsin, optional, type=string: takes the value ‘Jy’, ‘Ta’, or ‘Ta*’, default is Ta.
nofoldin, optional, type=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).
blankinterpin, optional, type=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.
nomaskin, optional, type=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.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0). Default is unset.
tcalin, optional, type=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.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This keyword will not affect error messages. Default is unset.
keepintsin, optional, type=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 intnu keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is all files.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
statusout, optional, type=integer: 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.

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

pro getnod(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, trackfdnum=trackfdnum, sampler=sampler, tau=tau, tsys=tsys, ap_eff=ap_eff, smthoff=smthoff, units=units, eqweight=eqweight, tcal=tcal, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

Procedure getnod retrieves and calibrates a total power nod scan pair.

This procedure will only process scans taken with the observing procedure “Nod”. It can be used as a template for the user who may wish to develop more tailored calibration schemes. The spectrum is calibrated in Ta (K) by default. The user can calibrate to units of Ta* or Jy as well, via the units parameter.

Summary

Data are selected using the parameters scan, ifnum, intnum and plnum or, alternatively, sampler and intnum if you know the specific sampler name (e.g. “A10”). The second scan in the Nod procedure is identified automatically by this procedure.
Individual integrations are processed separately with the same integration number in the two scans processed together. Both scans must have the same number of integrations. Each integration is processed using donod
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.
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.
The final average is left in the primary data containe (buffer 0), and a summary line is printed. The printing of the summary line can be suppressed by setting the quiet keyword. The first Tsys displayed is that of the averaged spectrum. The other 4 Tsys values displayed are weighted averages of the Tsys values from each of the 4 beam/scan combinations that make up each integration (see donod for more details). These values can be useful in assessing the quality of the parts of the data that make up the final result.
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.
VEGAS will sometimes record scans of different numbers of integrations even though the setups are the same. If this occurs in an On/Off scan pair then this routine procedes by ignoring the final integration in the longer scan (after first checking that the difference in the number of integrations is one, otherwise an error is reported). This is safe to do, with no loss of data, in all known cases because the extra integration in the longer scan will be a partial integration (missing data from one of the switching states, likely also much shorter than the other integrations). So, that extra integration is unusable.

Parameters

The scan number is required. Either of the scans in the “Nod” pair can be given. Arguments to identify the IF number, polarization number, and feed number are optional. The default tracking feed number, trackfdnum, is the lowest numbered FEED found in the data. This feed number is interpreted as the tracking (source) feed for the first scan. The only other possible choice of trackfdnum here is 1 and the only reason to use that is if the lowest numbered FEED was not the tracking feed (that is not the usual configuration for “Nod” scans). Tracking feed in this context means that the source signal was in that beam during the first of the two “Nod” scans.

If ifnum, trackfdnum, 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, after using any user-supplied values. The value of ifnum is determined first, followed by trackfdnum and finally plnum. If a combination with data cannot be found then showiftab is used to show the user what the set of valid combinations are. The summary line includes the ifnum, trackfdnum, and plnum used.

Tsys and Available Units

The procedure calculates Tsys based on the Tcal values and the data in the non-source feeds (both scans). 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, then 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 override the default Tcal by supplying a mean Tcal using the tcal keyword.

Smoothing the Reference Spectra

A parameter called smthoff can be used to smooth the reference spectrum prior to calibration. In certain conditions this technique 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, internal 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.

Summary Information

The getnod procedure provides some information in the terminal as it processes data. The scan number of the first scan in the “Nod” pair along with the ifnum, trackfdnum, and plnum are shown, followed by several Tsys values. The first Tsys printed is the effective Tsys of the resulting spectrum, a weighted average of the Tsys values in the reference beams from both scans as described in donod The other 4 Tsys values are the individual Tsys values from the components of the calibration, in order: scan 1 beam 1, scan 1 beam 2, scan 2 beam 1, scan 2 beam 2.

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. These keywords can be used either as 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. If /skipflag is set, then all flags are ignored (the spectrum may still contain blanked values if the 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 Duplicate Scan Numbers

Sometimes a data set may have multiple spectra with the same scan number. There are 3 ways to attempt to resolve such ambiguities. The instance keyword is one way. For example, if scan 23 appears 3 times then instance=1 refers to the second instance of scan 23 in the data set. 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 timestamp is given, scan and instance are ignored. If more than one timestamp match is found, an error is printed and this procedure will not continue.

Once a unique match is found to the desired scan (using instance, file, or timestamp) then the paired scan is identified. The match must be found within the same file and it must have the appropriate matching scan number (scan-1 if scan is the second scan in the procedure or scan+1 if scan is the first scan in the procedure). If those two rules are not sufficient to find a unique match, the matching scan with the closest timestamp in the appropriate direction (before or after depending on which procseqn is associate with scan) is used. Finally, the matched pair must have the appropriate procseqn.

Note: If you see the message “No data found, cannot continue” the most likely explanation is that the IF numbers are confused, probably due to a bad configuration (e.g. both feeds do not have data from the same IF and polarization). Consequently, this calibration routine can not calibrate that data. It is likely that all of the IFNUM values for this data are -1.

Params:

scan ：in, required, type=integer: M&C scan number

Keywords:

ifnumin, optional, type=integer: IF number (starting with 0). Defaults to the lowest value associated with data taking into account any user-supplied values for trackfdnum, and plnum.
intnumin, optional, type=integer: Integration number, defaults to all integrations.
plnumin, optional, type=integer: Polarization number (starting with 0). Defaults to the lowest value with data after determining the values of ifnum and trackfdnum if not supplied by the user.
samplerin, optional, type=string: sampler name, this is an alternative way to specify ifnum and plnum. When sampler name is given, ifnum and plnum must not be given. Note that data from the associated switched sampler will also be used.
trackfdnumin, optional, type=integer: Tracking 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.
tauin, optional, type=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.
tsysin, optional, type=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.
ap_effin, optional, type=float: Aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoffin, optional, type=integer: Smooth factor for reference spectrum, defaults to 1 (no smoothing).
unitsin, optional, type=string: takes the value ‘Jy’, ‘Ta’, or ‘Ta*’, defaults to ‘Ta’
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0). Default is unset.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. Error messages are not affected. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This keyword is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is all files currently opened.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.

Returns:

statusout, optional, type=integer: This keyword indicates 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 buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when using getnod with another procedure or function.

Examples:

; average both polarizations from ifnum=1
sclear
getnod, 76, ifnum=1, plnum=0
accum
getnod, 76, ifnum=1, plnum=1
accum
ave

Uses:

accumave accumclear DATA_FREE dcaccum dcscale dcsetunits donod find_paired_info set_data_container showiftab

@version $Id;-

pro getps(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, fdnum=fdnum, sampler=sampler, tau=tau, tsys=tsys, ap_eff=ap_eff, smthoff=smthoff, units=units, eqweight=eqweight, tcal=tcal, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

Procedure getps retrieves and calibrates a total power, position switched scan pair.

Position switched data are usually taken with the observing procedures OnOff() or OffOn. This routine can be used as a template for the user who may wish to develop more tailored 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”). The other scan in the scan pair is found using scan (see comments below). The same sampler name is used for both scans.
Individual integrations are processed separately. The same integration number in both the “On” and “Off” scans are processed together. Each integration is processed using dofullsigref.
The integrations are calibrated in Ta (K). If units of Ta* or Jy are requested via the units keyword, then dcsetunits is used to convert to the desired units.
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.
The final average is left in the primary data container (buffer 0), and a summary line is printed. The printing of the summary line can be suppressed by setting the quiet keyword. The first Tsys displayed is that of the result. This all comes from the “Off” scan integrations. The second Tsys is the weighted average of the Tsys values from the “On” scan integrations.
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.
VEGAS will sometimes record scans of different numbers of integrations even though the setups are the same. If this occurs in an On/Off scan pair then this routine procedes by ignoring the final integration in the longer scan (after first checking that the difference in the number of integrations is one, otherwise an error is reported). This is safe to do, with no loss of data, in all known cases because the extra integration in the longer scan will be a partial integration (missing data from one of the switching states, likely also much shorter than the other integrations). So, that extra integration is unusable.

Parameters

The scan number is a required parameter. Either scan in the sequence of two total power scans can be given, and the paired scan is determined from the header. 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 cannot 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 in the “Off” scan. 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 prior to calibration. 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.

Summary Information

The scan number printed in the status line is that of the “On” scan followed by the ifnum, fdnum, and plnum used. The first Tsys printed is the tsys of the result (and they come only from the “Off” scan). The second Tsys printed is a weighted average of the Tsys values associated with the “On” scan.

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 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.

Once a unique match is found to the desired scan (using instance, file, or timestamp) then the scan paired with that scan necessary to finish this procedure is found. The match must be found within the same file as the desired scan. It must have the appropriate matching scan number (scan-1 if scan is the second scan in the procedure or scan+1 if scan is the first scan in the procedure). If those two rules are not sufficient to find a unique match, the matching scan with the closest timestamp in the appropriate direction (before or after depending on which procseqn is associate with scan) is used. Finally, the matched pair must have the appropriate procseqn given the procseqn that scan is.

Params:

scan {in}{required}{type=integer} M&C scan number

Keywords:

ifnumin, optional, type=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.
intnumin, optional, type=integer: Integration number, defaults to all integrations.
plnumin, optional, type=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.
fdnumin, optional, type=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.
samplerin, optional, type=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.
tauin, optional, type=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.
tsysin, optional, type=float: tsys at zenith, this is converted to a tsys at the observed elevation. If not supplied, the tsys for each integration is calculated as described elsewhere.
ap_effin, optional, type=float: aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoffin, optional, type=integer: smooth factor for reference spectrum, defaults to 1 (no smoothing).
unitsin, optional, type=string: takes the value ‘Jy’, ‘Ta’, or ‘Ta*’, default is Ta.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0), default is unset.
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This will not have any effect on error messages. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This option is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurrence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is all files.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
statusout, optional, type=integer: An output parameter 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 buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when getps is called within another procedure or function.

Examples:

; average both polarizations from ifnum=1
sclear
getps, 76, ifnum=1, plnum=0
accum
getps, 76, ifnum=1, plnum=1
accum
ave

Uses:

accumave accumclear DATA_FREE dcaccum dcscale dcsetunits dofullsigref find_paired_info set_data_container showiftab

pro getrec(index, useflag=useflag, skipflag=skipflag)#

Gets the data associated with a given index number in the input data set.

This is shorthand for get,index=index with optional use of useflag or skipflag. See the documentation for get for more information.

Params:

indexin, required, type=integer: The index number of the record to be retrieved
useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?

Examples:

getrec,1
show
getrec,1,/skipflag  ; ignore all flags
show

pro getscan(scan, useflag=useflag, skipflag=skipflag)#

Gets the data associated with a given scan number. In general this procedure is used on data that have already been calibrated and written o a new data file.

To retrieve scans from a raw data file, as produced by the ‘sdfits’ program on the GBT, use getfs, gettp, getnod, or one of the other procedures that does both retrieval and calibration.

This is shorthand for get,scan=scan with optional use of useflag or skipflag. See the documentation for get for more information. If there is more than one record that has the requested scan number, only the first is saved to the primary data container. This is discussed in more detail in the documentation for get.

Params:

scanin, required, type=integer: The scan number of the record to be retrieved

Keywords:

useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?;

Examples:

filein,'my_processed_data.fits'
getscan,101
copy, 0, 10
getscan,102
oshow, 10
getscan,103,/skipflag ; ignore all flags

pro getsigref(sigscan, refscan, ifnum=ifnum, intnum=intnum, plnum=plnum, fdnum=fdnum, sampler=sampler, tau=tau, tsys=tsys, ap_eff=ap_eff, smthoff=smthoff, units=units, eqweight=eqweight, tcal=tcal, quiet=quiet, avgref=avgref, keepints=keepints, useflag=useflag, skipflag=skipflag, siginstance=siginstance, sigfile=sigfile, sigtimestamp=sigtimestamp, refinstance=refinstance, reffile=reffile, reftimestamp=reftimestamp, status=status)#

This procedure retrieves a pair of total power scans and calibrates the spectrum.

The signal and reference scans are identified separately and do not need to be associated in a single observing procedure. This procedure can be used as a template for the user who may wish to develop more tailored calibration schemes. The spectrum is calibrated in Ta (K) by default. Other recognized units are Ta* and Jy.

Summary

Data are selected for the two scans using sigscan, refscan, ifnum, intnum, plnum and fdnum or, alternatively, sampler and intnum if you know the specific sampler name (e.g. “A10”). The same sampler name is used for both sigscan and refscan.
If the avgref option is not set (the default) and both scans have the same number of integrations, then individual integrations are processed separately. The same integration number in sigscan and refscan are processed together. If the avgref option is set or both scans do not have the same number of integrations then the total power value from each integration in refscan is found using dototalpower and the individual integrations are averaged together to produce one reference spectrum that is used for each integration of sigscan. Each integration is processed using dofullsigref If there is no cal switching (TPnoCal) then there is no attempt to determine TCal and the sig and ref values are used as is.
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.
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.
The final average is left in the primary data container (buffer 0), and a summary line is printed. 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.

Parameters

Arguments for sig and ref scan numbers are required. Arguments to identify the IF number, polarization number, and feed number are optional. The default feed number (0) is the lowest numbered FEED found in the data.

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 cannot 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 in the reference scan. 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 of the reference scan. If the data are calibrated to Ta* or Jy, additional parameters are used. A zenith tau value 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 prior to calibration of each integration. 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. This same weighting is used when averaging the reference scans if the avgref option is on or there are different numbers of integrations in each scan.

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 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. These are specified independently for each of the two scans (sigscan and refscan).

Params:

sigscanin, required, type=integer: M&C scan number for the signal scan
refscanin, required, type=integer: M&C scan number for the reference scan

Keywords:

ifnumin, optional, type=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.
intnumin, optional, type=integer: Integration number, defaults to all integrations.
plnumin, optional, type=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.
fdnumin, optional, type=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.
samplerin, optional, type=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.
tauin, optional, type=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.
tsysin, optional, type=float: tsys at zenith, this is converted to a tsys at the observed elevation. If not supplied, the tsys for each integration is calculated as described elsewhere.
ap_effin, optional, type=float: aperture efficiency, if not suppled, it is estimated using get_ap_eff ap_eff is only used when the requested units are Jy.
smthoffin, optional, type=integer: smooth factor for reference spectrum, defaults to 1 (no smoothing).
unitsin, optional, type=string: takes the value ‘Jy’, ‘Ta’, or ‘Ta*’, default is Ta.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0), default is unset.
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
avgrefin, optional, type=boolean, default=unset: When set, the total power values for the individual integrations in refscan are averaged together using the current weighting option (using Tsys or equal weighting) to produce a single reference spectrum that is then used to calibrate each integration of sigscan. This option will automatically be selected whenever the number of integrations in refscan is not the same as in sigscan.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This will not affect error messages. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This option is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules? Default is unset.
siginstancein, optional, type=integer: Which occurrence of sigscan should be used, default is 0.
sigfilein, optional, type=string: When specified, limit the search for sigscan (and instance) to this specific file, default is all files.
sigtimestampin, optional, type=string: The M&C timestamp associated with the desired signal scan. When supplied, sigscan and siginstance are ignored.
refinstancein, optional, type=integer: Which occurrence of refscan should be used, default is 0.
reffilein, optional, type=string: When specified, limit the search for refscan (and instance) to this specific file, default is all files.
reftimestampin, optional, type=string: The M&C timestamp associated with the desired reference scan. When supplied, refscan and refinstance are ignored.
statusout, optional, type=integer: An output parameter 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 buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when using getsigref within another procedure or function.

Examples:

Suppose scans 13 and 14 are a position switched pair and scans 21 and 22 are also a position switched pair. There was a problem with the off or reference scan in 13 and 14 (scan 13 in this example) so you want to use the other reference scan (scan 21) in it’s place. Note that as this is currently written, for this to work scan 21 must have the same number of integrations and switching phases as scan 13. If that isn’t the case, you may want to look at using the underlying dosigref procedure to work with each integration or an average of all integrations in each scan directly.

getsigref, 14, 21
;
; you could do this, uses dosigref directly
;
gettp, 14        ; averages total power of all ints in scan 14
copy, 0, 10      ; remember for later use
gettp, 21        ; total power avg in scan 21
copy, 0, 11
dosigref, result, !g.s[10], !g.s[11]
set_data_container, result ; put result into buffer 0
data_free, result ; delete the pointer in result

Uses:

accumave accumclear DATA_FREE dcaccum dcscale dcsetunits dofullsigref set_data_container showiftab

pro gettp(scan, ifnum=ifnum, intnum=intnum, plnum=plnum, fdnum=fdnum, sampler=sampler, eqweight=eqweight, tcal=tcal, sig_state=sig_state, cal_state=cal_state, wcalpos=wcalpos, subref=subref, quiet=quiet, keepints=keepints, useflag=useflag, skipflag=skipflag, instance=instance, file=file, timestamp=timestamp, status=status)#

This procedure retrieves and calibrates a total power scan.

This code can be used as a template for the user who may wish to develop more tailored calibration schemes.

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 using dototalpower. This averages the two switching phases (with cal and without cal) and calculates a mean system temperature. For scans without any CAL switching data (TPnoCal) then nothing is done at this step. Note: this step is done even when the data from only one state is requested using the cal_state or sig_state keywords. If the data from one of the two states is blanked for a given integration then the resulting Tsys will be set to Not A Number. If the default weighting is used then none of the data from any integration with a non-finite Tsys will be used in the final average. The eqweight keyword can be used to turn off the default weighting.
Averaging of individual integrations is 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.
The final average is left in the primary data container (buffer 0), and a summary line is printed. The printing of the summary line can be suppressed by setting the quiet keyword.
This can be used on sig-switching data (frequency-switched data). Use the sig_state keyword to select the signal state (1) or the reference state (0). Otherwise all data are used. In the case of all data being used, each individual switching state is first processed (Tsys is determined and the two cal states are averaged) and then the results are all averaged using Tsys weighting unless eqweight is set.
If cal_state is used then only that cal_state is used in the average (or individual integrations). Both cal states are still used to determine tsys. Options are: 0 or 1. If 1 then the cal is on, if 0 it is off.

Parameters

The scan number is a required parameter. Arguments to identify the IF number, polarization number and feed number are optional. The procedure calculates Tsys based on the Tcal values and the data. The Tcal value comes from the mean_tcal value in cal_off phase data container unless the user supplies a value using the tcal keyword. In that case, one tcal value is supplied and that value is used for all integrations processed here. The two switching phases are averaged and a system temperature (Tsys) is calculated in the dototalpower procedure. See the documentation for that procedure for details of the Tsys calculation.

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.

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.

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 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.

Params:

scanin, required, type=integer: M&C scan number

Keywords:

ifnumin, optional, type=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.
intnumin, optional, type=integer: Integration number (starting with 0), defaults to all integrations.
plnumin, optional, type=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.
fdnumin, optional, type=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.
samplerin, optional, type=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.
eqweightin, optional, type=boolean: When set, all integrations are averaged with equal weight (1.0). Default is unset.
tcalin, optional, type=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 will have it’s mean_tcal header value set to this keyword when it is set by the user.
sig_statein, optional, type=integer: For use with sig-switched data. If sig_state is 1 then only the signal data are used, if sig_state is 0 then only the reference data are used.
cal_statein, optional, type=integer: If cal_state is 1 then only the cal-on data is used to calculate the average or integration values. If cal_state is 0 then only the cal-off data are used. If unset then all cal switching states are used. Both states are always used to determine Tsys.
wcalposin, optional, type=string: Only select data matching this wcalpos value (the WBand calposition label). If not supplied (the default) no selection on wcalpos will be done.
subrefin, optional, type=integer: Only select data matching this subref value (the subref_state value used when subreflector nodding to indicate the position of the subreflector: 1 and -1 are the two positions and 0 indicates motion during that integration). If not supplied (the default) no selection on subref will be done.
quietin, optional, type=boolean: When set, the normal status message on successful completion is not printed. This will not affect error messages. Default is unset.
keepintsin, optional, type=boolean: When set, the individual integrations are saved to the current output file (fileout). This keyword is ignored if a specific integration is requested using the intnum keyword. Default is unset.
useflagin, optional, type=boolean or string: Apply all or just some of the flag rules? Default is set.
skipflagin, optional, type=boolean or string, default=unset: Do not apply any or do not apply a few of the flag rules? Default is unset.
instancein, optional, type=integer: Which occurrence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is to search all files currently opened.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
statusout, optional, type=integer: An output parameter 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 buffer 0 likely contains just the result from the last integration processed. This keyword is primarily of use when using gettp within another procedure or function.

Examples:

A simple version of (on-off)/off using two total power scan.

gettp, 24   ; this is the "on" data
copy,0,10
gettp, 31   ; this is the "off" data
copy,0,11
subtract, 10, 11  ; result in 0
divide, 0, 11     ; overwrites result in 0; </pre>

Uses:

accumave accumclear DATA_FREE dcaccum dcscale dcsetunits dototalpower set_data_container showiftab

pro gfft(real_buffer, imag_buffer, inverse=inverse, bdrop=bdrop, edrop=edrop)#

Do an FFT or an inverse FFT on the data container(s) indicated by the arguments. This always overwrites the data array in those data containers with the result.

In the case of the forward FFT (the default), if a buffer number for the imaginary part is omitted, it is assumed that the input array is a pure real array (the imaginary part is all 0 and any data at the imag_buffer location is ignored on input (and overwritten on output).

The units of the x-axis and the data are not changed here. The user needs to keep track of the state of their data containers. If a non-zero bdrop or edrop are used, the resulting data containers will be shortened by that many elements using dcextract. Consequently, it may not be appropriate to use the same bdrop and edrop on an inverse FFT as it was when the FFT was first done.

See the discussion in idl:pro:`dcfft on how inverse is used for spectral-line data vs continuum data. For spectral-line data, an FFT is a transformation from frequency to time and an inverse FFT is a transformation in the other direction. For continuum data, an FFT is a transformation from time to frequency and an inverse FFT is a transformation in the other direction.

Params:

real_bufferin, out, optional, type=integer, default=0: The global buffer number from which the real values going in to the FFT are obtained. The real values from the result are overwritten to this location. Defaults to buffer 0.
imag_bufferin, out, optional, type=integer, default=1: The global buffer number from which the imaginary values going in to the FFT are obtained. The imaginary values from the result are overwritten to this location. If this parameter is omitted on the forward transformation (inverse is not set) then the input values are assumed to be all real (the imaginary part is all 0) and any data at this location is ignored and overwritten on output. Defaults to buffer 1.
inversein, optional, type=boolean: When set, the inverse FFT is performed as described above.
bdropin, optional, type=integer, default=0: The number of channels to exclude from the FFT at the beginning.
edropin, optional, type=integer, default=0: The number of channels to exclude from the FFT at the end.

Examples:

getps, 34    ; get some data
gfft         ; uses buffer 0, result in 0 (real) and 1 (imag)
oshow, 1
gfft, 0, 1, /inverse  ; the other direction

Uses:

dcfft dcextract

pro ginterp(buffer, bchan=bchan, echan=echan, linear=linear, quadratic=quadratic, lsquadratic=lsquadratic, spline=spline)#

Interpolate across blanked channels in the primary data container (buffer 0) or one of the other buffers.

This uses the IDL INTERPOL function to replace blanked values in the buffer with unblanked values according to the interpolation method selected.

You can limit the range of channels to consider using bchan and echan. When not supplied, all of the channels are used.

The default interpolation method is linear. The other interpolations may not be particularly useful across large gaps.

If all of the data in the requested range is good (unblanked) then no interpolation is done and this routine silently returns without changing anything in dc.

It is an error to request more than one interpolation method.

Params:

bufferin, optional, type=integer, default=0: The data container to smooth to the new resolution. This defaults to the primary data container (buffer 0).

Keywords:

bchanin, optional, type=integer: The starting channel number. If not specified, bchan=0.
echanin, optional, type=integer: The last channel number. If not specified use all channels from bchan to the end.
linearin, optional, type=boolean: When set, use the linear interpolation provided by INTERPOL. This is the default interpolation when no other method is specified.
quadraticin, optional, type=boolean: When set, use the quadratic interpolation provided by INTERPOL.
lsquadraticin, optional, type=boolean: When set, use the lsquadratic (lest squares quadratic) interpolation provided by INTERPOL.
splinein, optional, type=boolean: When set, use the spline interpolation provided by INTERPOL.

Examples:

clip, -100.0, 100.0, /blank    ; blank bad data
ginterp      ; linear interpolation across the blanked regions

Uses:: dcinterp show

pro gmaxiter(maxiter)#

Sets the maximum iterations for fitting guassians: !g.gauss.maxiter

Params:

maxiterin, required, type=long: maximum iterations for fitting gaussians

Examples:

; get some continuum data
cont
filein,'peaks.fits'
get,index=1
; setup the gauss fit
gregion,[60,80]
ngauss,[1]
gmaxiter,500
gparamvalues, 0, 0, [400000.,70.,100.]
; find and show the fit
gauss
gshow

pro gmeasure(mode, fract, brange=brange, erange=erange, rms=rms, chan=chan, lefthorn=lefthorn, righthorn=righthorn, quiet=quiet, ret=ret)#

Procedure to measure the area, width, and velocity of a galaxy profile.

The derived area, width and velocity are displayed unless the /quiet keyword is used. These values can also be returned using the ret keyword. The value of ret is a 6-element array containing the area, width, and velocity in that order estimates of the error on those quantities in the same order. The width and velocity are always given (shown and returned) in km/s and the area is given in data units * km/s. The error on the area is only set when fract equals 0.2 or 0.5. The errors on the width and velocity are only set for mode 4. Mode 4 always sets the width error to be twice the velocity error.

This is a front-end to awv. The source code there originated at Arecibo. See the comments there for a description of the 4 possible values for mode and how fract and rms are used for each mode.

The data that is currently displayed in the plotter is used in this procedure. The displayed x-axis can be any type. The x-axis values are be converted to velocity taking into account any previously set velocity offset (even if the displayed axis is not the velocity axis). If there is no data displayed in the plotter, the contents of the primary data container (buffer 0) are used.

If the region of interest is not specified, the user is asked to mark it interactively.

A baseline should have been removed prior to using this function.

brange, erange, lefthorn, and righthorn are given in the currently display x-axis units unless the chan keyword is set.

Originally Contributed By: Karen O’Neil, NRAO-GB and Bob Garwood, NRAO-CV

Params:

modein, required, type=integer: Must be one of 1,2,3, or 4. See the comments in awv for more details.
fractin, required, type=float: Fraction of peak or mean used in locating the edges of the galaxy profile. See the comments in awv for more details. Note: In modes 3 and 4 the user is asked to mark the two horns of the galaxy profile with the cursor unless the optional lefthorn and righthorn keywords are used.

Keywords:

brangein, optional, type=integer: Starting value of the region of interest in x-axis units unless chan is set.
erangein, optional, type=integer: Ending value of the region of interest in x-axis units unless chan is set.
rmsin, optional, type=float: Used in modes 2, 3 and 4 as described in awv. If this is not supplied, it defaults to the stddev of the data within the region of interest given by brange and erange.
chanin, optional, type=boolean: Interpret the user supplied range and optional horn positions in channels instead of the current x-axis units.
lefthornin, optional, type=float: Location of the left peak in x-axis units unless chan was specified.
righthornin, optional, type=float: Location of the right peak in x-axis units unless chan was specified.
quietin, optional, type=boolean: When set, the results are not printed to the terminal (the ret keyword should be used to get the results).
retout, optional, type=floating point: Six-element array giving [area,width,velocity,areaerr,widtherr,velocityerr]. All six elements will be 0.0 if there was a problem. The areaerr is only set when fract is 0.2 or 0.5. The widtherr and velocityerr are only set by mode 4. Unset error values are 0.0.

Examples:

gmeasure, 1, 0.5, ret=ret50
gmeasure, 1, 0.8, ret=ret80

Uses:

awv

pro gmoment(bmoment, emoment, chan=chan, full=full, quiet=quiet, ret=ret)#

Find the first 3 moments of a region of the data in buffer 0.

The three moments are:

m[0] = sum(data(i) * delta_x(i))
m[1] = sum(data(i)*x(i))/m[0]
m[2] = sqrt(sum(data(i)*(x(i)-m[1])^2)/m[0])

where the sums are over the region of interest, the x and delta_x values are the channel centers and spacings in the currently displayed x-axis units. delta_x is calculated independently for each channel and centered at that channel. The results are printed out and returned through the ret keyword. The display of the results can be turned off through the use of the /quiet flag.

The region is given in the currently displayed x-axis units and the sum starts from the channel number nearest bmoment and ends at the channel number nearest emoment. If the /chan keyword is used, then bmoment and emoment are given in channels. If a region is not specified the user is prompted to use the cursor on the plotter to mark the region. /full can be used to force gmoment to use all channels.

Blanked values are ignored.

The structure returned through the re keyword has these fields.

bchan The first channel used.
echan The last channel used.
nchan The total number of channels used.
xmin The minimum x-axis value (bchan or echan)
xmax The maximum x-axis value (bchan or echan)
moments A 3-element array giving the moments, in the order described above.
moment_unts A 3-element string array giving the units for each moment.

gmoment was chosen because IDL already has a moment function.

Params:

bmomentin, optional, type=float: Start of region in x-axis units.
emomentin, optional, type=float: End of region in x-axis units.

Keywords:

chanin, optional, type=boolean: Range specified in channels?
fullin, optional, type=boolean: Compute moments for full spectrum?
quietin, optional, type=boolean: Suppress the printing of the moments.
retout, optional, type=structure: Structure containing the results.

Examples:

gmoment, 1000, 1520, ret=ret

pro gparamvalues(gauss_index, values)#

Procedure to put values into the !g.gauss.params container.

Params:

gauss_indexin, required, type=long: Which gaussian (0 to ngauss-1) to set the parameters of.
valuesin, required, type=double array: Array of values to assign to the indicated gaussian (must have 3 elements). Order is height, center, and full width at half maximum. The units are always channels.

Examples:

ngauss, 2    ; set up for 2 gaussians
gparamvalues, 0, [1020.0, 1.24, 12.4]

pro gregion(regions)#

Set some regions for use by GUIDE gaussian procedures and functions.

This sets the !g.gauss.regions structure with the regions described by the regions argument. Overlaps in regions are eliminated and the resulting content of !g.gauss.regions is a set of unique, non-overlapping regions. Regions are expressed as channel numbers. This procedure always clears the contents of !g.gauss.regions before starting.

Note

There is a limit of 100 regions. If you need to use more regions you will need to either use the fitting functions directly or make a local copy of the guide_struct file which defines the !g structure and edit the sizes in there.

Params:

regionsin, required, type=integer array: The regions to set. If this is a 1D array, then it is interpreted as a sequence of beginning and ending channels which define n_elements/2 regions, inclusive. A warning is issued in that case if n_elements is not a multiple of 2. The trailing, unmatched value will be ignored. Values after the first negative value encountered are also ignored. If this is a 2D array, then the first dimension must be 2 and the second dimension is the number of regions. A warning is issued if this argument gives more than 100 regions. Only the first 100 regions are used in that case. Overlapping regions are eliminated.

Examples:

All of these produce identical results

; as 1-D array
gregion, [125,180,215,300,320,475]
; as 2-D array
gregion, [[125,180],[215,300],[320,475]]
; same regions, beginning and end channels swapped
gregion, [180,125,300,215,320,475]
; overlapping regions
gregion, [125,160,150,180,215,300,320,420,400,475]

pro gshift(offset, buffer=buffer, wrap=wrap, ftol=ftol, linear=linear, quadratic=quadratic, lsquadratic=lsquadratic, spline=spline, cubic=cubic, nowelsh=nowelsh, nopad=nopad, ok=ok)#

Procedure to shift data in a GUIDE data buffer by a given number of channels.

This uses dcshift. Please read the documentation for that toolbox function for all the details about how shifting of data containers is implemented. This documentation is very thin and is primarily useful as a syntax reminder for the usage procedure.

See fshift or vshift for examples showing how this is used to align spectra prior to averaging.

Params:

offsetin, required, type=floating point: The number of channels to shift the data (positive shifts things towards higher channels, negative shifts things towards lower channels).

Keywords:

bufferin, optional, type=integer: The GUIDE data buffer to shift. All shifting is done in place and so the data in this buffer is modified by this procedure.
wrapin, optional, type=boolean: Data shifted off one end of the array appears on the other end of the array (it wraps around as a result of the shift) when this is set. Otherwise, as data is shifted it is blanked (replaced by NaNs) and data shifted off the end is lost.
ftolin, optional, type=floating point, default=0.01: Fractional shifts (the non-integer portion of offset) are only done when they are larger than ftol. Set this value to >= 1.0 to turn off all fractional shifts.
linearin, optional, type=boolean: When set, use the linear interpolation provided by INTERPOL for any fractional shift larger than ftol.
quadraticin, optional, type=boolean: When set, use the quadratic interpolation provided by INTERPOL for any fractional shift larger than ftol.
lsquadraticin, optional, type=boolean: When set, use the lsquadratic (lest squares quadratic) interpolation provided by INTERPOL for any fractional shift larger than ftol.
splinein, optional, type=boolean: When set, use the spline interpolation provided by INTERPOL for any fractional shift larger than ftol.
cubicin, optional, type=boolean: When set, use the cubic interpolation provided by INTERPOLATE for any fractional shift larger than ftol. The value of the CUBIC keyword in the INTERPOLATE call is set to -0.5.
nowelshin, optional, type=boolean: When set, the shifted data is NOT windowed using the Welsh function. This is ignored when a non-FFT-based fraction shift is done
nopadin, optional, type=boolean: When set, the data is NOT padded with 0s to the next higher power of 2 prior to the FFT and shift. The data are never padded for the non-FFT-based fractional shifts.
okout, optional, type=boolean: This is set to 1 on success or 0 on failure (e.g. bad arguments).

Examples:

getps, 30
accum           ; first in, no alignment needed yet
getps, 31
fs = fshift()   ; shift to align in frequency
gshift, fs      ; actually do the shift
accum           ; now it can be added to the accumulation
ave

Uses:

dcshift DATA_COPY set_data_container DATA_FREE

pro gshow(modelbuffer=modelbuffer, parts=parts, color=color)#

Show the most recently fit gaussians and annotate the plot with their peak, center, width values.

The gaussians are plotted on top of the whatever is already plotted.

Keywords:

modelbufferin, optional, type=integer: The data container buffer containing the model of the most recent gaussian fit. If this is omitted, a value of -1 is assumed. If this is -1 then a model is constructed from the fit parameters in !g.gauss. This is ignored if parts is set.
partsin, optional, type=boolean: When set, show the individual gaussians as separate plots. This always constructs the gaussians from the parameters in !g.gauss. modelbuffer is ignored when this keyword is set.
colorin, optional, type=integer, default=``!g.gshowcolor``: A color to use for the plots.

Examples:

; assumes initial guesses already set
gauss
gshow,/parts

pro gsmooth(newres, buffer=buffer, decimate=decimate)#

Smooth the data with a GAUSSIAN such that the spectrum in the given buffer with an original resolution of frequency_resolution now has a resolution of NEWRES, where NEWRES is expressed in channels.

Optionally also decimate the spectrum by keeping only every NEWRES channels.

The frequency_resolution field is set to $newres * \abs(frequency_interval)$ after this procedure is used.

The width of the smoothing Gaussian is $\sqrt{newres^2 - oldres^2}$.

Params:

newresin, required, type=real: The desired new resolution in units of channels. This must be >= the frequency_resolution also expressed in channels. If it is equal to the frequency_resolution then this procedure does not change the data.

Keywords:

bufferin, optional, type=integer, default=0: The data container to smooth to the new resolution. This defaults to the primary data container (0).
decimatein, optional, type=boolean: When set, only every NEWRES channels are kept, starting from the original 0 channel. If NEWRES is not an integer, this may not be a wise thing to do (the decimation rounds to the nearest integer).

Examples:

; smooth to 2 channels wide
gsmooth, 2
; copy that to buffer 1 and smooth it to 4 channels wide
copy,0,1
gsmooth, 4, buffer=1
show, 1
; same operation on buffer 0, but decimate
gsmooth, 4, /decimate

Uses:

dcsmooth

pro gstatus(full=full)#

Summarize the status of GBTIDL as found in the global structure used by GBTIDL (!g).

This summarizes the parts of the !g structure that the user is most likely to care about. help,!g,/struct is useful, but only if you know exactly what you are looking for. Many fields in !g are not intended to be manipulated directly by the user and even those that are are sometimes difficult to interpret.

Using /full adds plotter color settings to the output.

See also the description of the contents of the !g structure here.

Keyword:

fullin, optional, type=boolean: If set, color settings are also summarized. The default is to omit that information.

Examples:

gstatus

pro hanning(buffer=buffer, decimate=decimate, ok=ok)#

This procedure smooths a spectrum with a hanning filter.

Replaces the contents of the data being smoothed with the smoothed data. Blanked data values are ignored.

For spectrum data containers, the frequency_resolution is set using esthanres.

Keywords:

bufferin, optional, type=integer, default=0: global buffer number to use (0-15).
decimatein, optional, type=boolean: If set, decimates by 2.
okout, optional, type=boolean: Returns 1 if everything went ok, 0 if it did not (invalid or empty buffer)

Examples:

getrec,1
show
hanning
show

Uses:

gconvol decimate

pro header(dc)#

Show header information for the primary data container or any other data container.

Params:

dcin, type=data container, optional: The data container to use. Defaults to the primary data container.

Examples:

header
; or, this is the same thing
header, !g.s[0]

Uses:

scalevals eqtogal getradec getgal ra2ha adstring

pro invert(buffer=buffer)#

Flip the data end-to-end in the indicated buffer in the global data containers.

For line data the value of frequency_increment and reference_channel are also changed appropriately so that, as displayed, there will be no change in appearance. This is useful if you need to combine (e.g. average) two data containers where the frequency increments have opposite signs.

For continuum data (where the need to invert is less obvious), all of the time-dependent arrays are also flipped (utc, mjd, etc).

The invert is done in place. Use dcinvert to flip a data container that is not one of the global data containers.

Note that when displayed, this will only be noticable when the x-axis is channels. The velocity and frequency axes always increases from left to right, independent of the actual channel increment from low channel number to high channel number.

Keywords:

bufferin, optional, type=integer, default=0: guide data container to use. Defaults to buffer 0.

Examples:

invert             ; invert buffer 0
invert, buffer=10  ; invert buffer 10

Uses:

dcinvert

pro keep(dc)#

Save a spectrum to the output file.

The data in the primary data container (buffer 0) is saved to the currently opened output file. The user can optionally save another buffer (0 to 15) or a specific data container by supplying a value for the dc parameter. Use fileout to open an output file. Use kget to retrieve data from the output file (nget can also be used, the file can also be opened using filein but only if some other file is already opened as the output file (the same file can not be opened by filein and fileout at the same time).

Only spectral line data can be saved to disk at this time.

Params:

dcin, optional, type=data container or integer, default=0: a data container, or an integer global buffer number. Defaults to the primary data container (buffer 0).

Examples:

getnod,30
fileout,'mysave.fits'
keep
getnod,32
keep
getfs,48,/nofold
keep                    ; saves buffer 0 by default
keep,1                  ; saves buffer 1

pro kget(useflag=useflag, skipflag=skipflag, _EXTRA=ex)#

Retrieves data from the output data file and places it in the primary data container (buffer 0).

Use the selection parameters to specify which data to retrieve. If the selection returns more than one data container, only the first data container is used. If you need to retrieve one of the other records you must first refine the selection criteria. A better approach might be to use select to get the list of records that satisfy that selection and then use kgetrec to get the individual records.

Only spectral line data can currently be fetched from a keep file.

Note: all of the data satisfying the selection criteria (or lack of criteria if none is given) are extracted from the file before this routine copies the first one found and puts it into buffer 0. There is no protection against running out of memory by grabbing too much data.

See the output of listcols for a complete list of columns that can be selected.

See the discussion on “Select” in the GBTIDL User’s Guide here for a summary of selection syntax.

The selection criteria are passed directly to the io class’s get_spectra or get_continua function via the _EXTRA parameter.

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.

Keywords:

useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?
_EXTRAin, optional, type=extra keywords: These are selection parameters passed to the data source to limit the amount of data returned.

Examples:

getnod,30
fileout,'mysave.fits'
keep
getnod, 32
keep
kget,index=0   ; retrieves the first record in the keep file
kget,index=0,/skipflag ; same record, ignore all flags
kget.index=0,useflag='wind' ; same record, apply just the 'wind' flag.

Uses:

set_data_container

pro kgetrec(index, useflag=useflag, skipflag=skipflag)#

Gets the data associated with a given index number in the input data set from the output (keep) file.

This is shorthand for kget,index=index with optional use of useflag or skipflag. See the documentation for kget for more information.

Params:

indexin, required, type=integer: The index number of the record to be retrieved.

Keywords:

useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?

Examples:

kgetrec,1
show
kgetrec,1,/skipflag ; ignore all flags
show

pro kgetscan(scan, useflag=useflag, skipflag=skipflag)#

Gets the data associated with a given scan number in the input data set from the output (keep) file.

This is shorthand for kget,scan=scan with optional use of useflag or skipflag. See the documentation for kget for more information. If there is more than one record that has the requested scan number, only the first is saved to the primary data container. This is discussed in more detail in the documentation for kget.

Params:

scanin, required, type=integer: The scan number of the record to be retrieved.

Keywords:

useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?;

Examples:

kgetscan,1
show
kgetscan,1,/skipflag ; ignore all flags
show

function lastrec(keep=keep)#

Returns the record number (index) of the most recently retrieved data container.

In line mode, this is the most recently retrieved record number from the input line file. In continuum mode, this is the most recently retrieved record number from the input continuum file. If the /keep keyword is used, this is the most recently retrieved record number from the output line file (the keep file).

This is -1 if nothing has been retrieved from that data source or if the data source is empty.

If multiple data containers were retrieved in a single call (e.g. using one of the calibration routines such as getfs) then this will be the largest record number in the set of records that were retrieved.

Keywords:

keepin, optional, type=boolean: If set, returns the record number (index) of the data container most recently retrieved from the output line file (the keep file).

Returns:

An integer giving the record number (index) of the last record fetched from the data source. Returns -1 if nothing has been fetched so far from that data source.

Examples:

getps, 6000
a = lastrec()

function lastscan(keep=keep)#

Returns the scan number of the most recently retrieved data container.

In line mode, this is the most recently retrieved scan number from the input line file. In continuum mode, this is the most recently retrieved scan number from the input continuum file. If the /keep keyword is used, this is the most recently retrieved scan number from the output line file (the keep file).

This is -1 if nothing has been retrieved from that data source or if the data source is empty.

If multiple data containers were retrieved in a single call (e.g. using one of the calibration routines such as getfs) then this will be the scan number of the last record actually retrieved from the data source.

Keyword:

keepin, optional, type=boolean: If set, returns the scan number of the data container most recently retrieved from the output line file (the keep file).

Returns:

An integer giving the scan number of the last record fetched from the data source. Returns -1 if nothing has been fetched so far from that data source.

Examples:

; This could be used to get the next scan, assuming they were sequential
getfs, lastscan()+1

pro list(start, finish, keep=keep, columns=columns, user=user, file=file, _EXTRA=ex)#

Lists columns from the index of the input file (or optionally the keep file) for the indicated range of rows. Selection can also be done in the same call so that only those rows that match the selection criteria will be listed.

The default columns that are listed are: INDEX, SOURCE, SCAN, PROCEDURE, POLARIZATION, IFNUM, FDNUM, INT, SIG, and CAL. Users can list other columns by specifying the columns argument. Users can alternatively set the list of columns to be show in !g.user_list_cols and then use the /user flag here.

Columns can be specified as either an array of strings or as a comma separated list. The value of !g.user_list_cols is always a comma separated list.

For a complete list of available column names, use listcols.

Additional selection on the index can be done to limit the index rows that are listed. The syntax is the same as in select. The “Select” section in the GBTIDL manual gives examples of the types of selections possible with list.

The rows are usually listed in order of increasing index number (even if index is not listed). This can be overridden by specifying another column name to sort on through the sortcol keyword (passed in through the _EXTRA keyword).

Use the FILE keyword to send the listing to a file instead of to the current screen.

Params:

startin, optional, type=long, default=0: If set, the beginning of range to list
finishin, optional, type=long, default=last index: If set, the end of range to list

Keywords:

keepin, optional, type=boolean: If set, the list comes from the keep file and !g.line is irrelevant.
columnsin, optional, type=string: If present, only list the values from these columns instead of the default columns. Can be either a comma-separated list in a single string or an array of strings. Columns trumps the user flag, if set.
userin, optional, type=boolean: If set and columns is not used, then the columns to list come from the !g.user_list_cols value. If that value is empty then this the default list is used. !g.user_list_cols is a comma-separated list of column names.
filein, optional, type=string, default=/dev/tty: The file to write to. Defaults to the current screen, using “more” to page the output.
_EXTRAin, optional, type=keywords: In addition to the selection keywords the <b>sortcol</b> keyword is also available here. Set that equal to a column name and the list order will be sorted in increasing values of that column.

Examples:

; list first 11 records in the input file
list,0,10

; list source and polarization for first 11 entries
list,0,10,columns=['source','polarization']

; Set the user preferences to index, source, longitude, latitude
!g.user_list_cols = "source,longitude,latitude"
; and list using the user preferences
list,0,10,/user

; this illustrates additional selection
; list index, source and tsys for all data in ifnum=1
list,ifnum=1,columns='index,source,polarization'

; list, sorting by increasing integration number
list,sortcol='int'

; Send the previous list to a file named mylisting
list,sortcol='int',file='mylisting'

pro listfind(param)#

List a specified selection parameter or all selection parameter values used by find.

This allows you to quickly tell the value of one or all of the selection parameters used by FIND. The set of parameters is the column names as reported by listcols.

Note: Only those parameters that have actually been set are listed unless a listing for specific parameters has been requested.

Use setfind to set selection parameters.

Use clearfind to clear selection parameters.

Params:

paramin, optional, type=string: The selection parameter(s) to list. Minimum-matching is used to find the selection parameter matching this value. If param is not supplied or is an empty string, all parameters are listed. Only parameters appropriate for the current mode (line or continuum) are shown unless a specific parameter is requested.

Examples:

listfind  ; show all set find parameters
listfind,'scan'  ; show the value of the SCAN selection parameter
listfind,['scan','int','plnum'] ; show the values of 3 selection params

pro listflags(idstring, summary=summary, keep=keep)#

List flags associated with the current input spectral line data file or with the keep (output) data file. Use the idstring parameter to limit the listing to a specific idstring.

Continuum flagging is not supported.

Params:

idstringin, optional, type=string, default=all: The string to match. All flags that match this string will be listed.

Keywords:

summaryin, optional, type=boolean: Produces a somewhat more readable output at the cost of possibly not showing all of the information. Truncated information is indicated with “.” in the truncated field. The default is to show all of the information - which may have long lines and which will not necessarily be nicely aligned by column.
keepin, optional, type=boolean: List the flags in the keep (output) file?

Examples:

..code-block:

; list all flags, formatted nicely, possibly truncated
listflags, /summary
; only list "RFI" tagged flags
listflags, "RFI"

pro listids(keep=keep)#

List all of the idstring values in the flag file of the current spectral line data source or the keep (output) data source.

Continuum flagging is not supported.

Keywords:

keepin, optional, type=boolean: List the idstring values in the keep (output) file?

pro liststack(start, finish, _EXTRA=ex)#

List the index information using the first !g.acount values of !g.astack as index numbers.

All of the keywords available in list are available here, with the same meanings. These keywords are passed to list through the _EXTRA keyword. See the documentation for list for examples.

Params:

startin, optional, type=long, default=0: If set, the first element of !g.astack to list.
finishin, optional, type=long, default=!g.acount-1: If set, the last element of !g.astack to list.

Keywords:

_EXTRAin, optional, type=extra keywords: Passed to list.

pro ls(pattern, options=options)#

List files (defaults to .fits in the current directory). This invokes the unix “ls” command using the pattern and optional arguments. If pattern is not provide, it defaults to “.fits”.

Params:

patternin, optional, type=string, default=’*.fits’: The pattern to list.

Keywords:

optionsin, optional, type=string, default=’’: Any arguments to the unix “ls” command.

Examples:

; show all the fits files in the current directory
ls
; show all the files in the current directory
ls,''
; show all the fits files in a directory relative to this one
ls,'../mydata'
; do a long listing
ls,options='-l'

pro mediansub(width, buffer=buffer)#

Subtract the median filtered values of the given width, in channels, from the data. The result replaces the original data values.

Uses the IDL MEDIAN function to get the median filtered array.

Params:

widthin, required, type=integer: The desired number of channels to use in performing the median filter.

Keywords:

bufferin, optional, type=integer, default=0: The data container to use. This defaults to the primary data container (0).

Examples:

; subtract a median filter of width 200 channels
mediansub,200

Uses:

dcmediansub

pro molecule(formula=formula, name=name, doprint=doprint, elimit=elimit, indices=indices, novsource=novsource)#

Plot the molecular line frequencies for previously detected molecular lines stored in !g.molecules on the currently displayed plot at the appropriate location given the current x-axis.

Note: The display is changed to show frequency as the x-axis if it is not already doing so.

Note: It is assumed that you want them shown at their rest frequency in the frequency reference frame current in use on the plotter adjusted for any source velocity. If the source velocity has already been used to adjust the x-axis display then this routine will plot the molecule lines at their rest frequencies without any offset. Use the /novsource keyword to turn off any consideration of the source velocity - lines are simply plotted at their rest frequencies no matter what the source velocity is or what the displayed x-axis is.

The set of lines to be search can be narrowed by supplying a formula or name. Wildcards are allowed and arrays of formula and names can be supplied.

Only lines with an upper state energy less than or equal to the elimit value (in K) are shown. The default value for this keyword is 50 K.

To show fewer lines use a lower elimit value or select specific lines using the formula or name keywords.

The indices keyword can be used to return the set of indices in the !g.molecules array of molecule_struct structures. This can be used to get access to full information if desired. See moleculeread for a description of the contents of the molecule_struct structure.

The line information was extracted from the Database for Astronomical Spectroscopy - Splatalogue specifically tailored for the available spectral line coverage of the GBT. Splatalogue is a fully rationalized and extended compilation of existing spectroscopic resources for use by the astronomical community including, but not limited too, the JPL, CDMS, Lovas/NIST, Frank Lovas’ own Spectral Line Atlas of Interstellar Molecules (SLAIM) catalogs.

Splatalogue is maintained at the North American ALMA Science Center with cooperation from the East Asian and European ALMA Regional Centers. The Splatalogue Subsystem Scientist is Anthony Remijan.

For questions, comments, suggestions or concerns about Splatalogue please submit a Helpdesk ticket through the ALMA Science Portal.

The text file containing the line information is found at $GBT_IDL_DIR/pro/guide/GBTIDL_RFF.csv

Keywords:

formulain, optional, type=string(s), default=’’: optionally filter the list of molecules to those whose formula matches this string. Wildcards are allowed following the rules of the IDL STRMATCH function. If formula is array of strings, each element is used separately and the final list is the set of all lines with a formula matching any of the strings on that list. If not supplied, the entire list is used. The filter is case insensitive.
namein, optional, type=string(s), default=’’: optionally filter the list of molecules to those whose name matches this string. Wildcards are allowed following the rules of the IDL STRMATCH function. If name is array of strings, each element is used separately and the final list is the set of all lines with a name matching any of the strings on that list. If not supplied, the entire list is used. The filter is case-insensitive.
doprintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.
elimitin, optional, type=double, default=50.0: Only lines with an upper state energy less than or equal to this limit will be plotted. The units are Kelvin. Lowering this limit reduces the number of lines plotted.
indicesout, optional, type=integer: The list of indices in !g.molecules of the lines that were plotted. This can be used to get the original information (e.g. rest frequency) of the lines marked on the plot. This has a value of -1 when no lines were plotted.
novsourcein, optional, type=boolean: Optionally set this to turn off any consideration of the source velocity when marking the locations of any molecule lines.

Examples:

molecule,formula='NH3*'                 ; All instances of ammonia
molecule,formula=['NH3*','HCCCHO*']     ; Two formulas to match
molecule,name=['ammonia','2-propynal']  ; Alternative
molecule,elimit=20                      ; lower the upper state energy cutoff to 20 K
molecule,indices=indices                ; get the indices of the species plotted
print,!g.molecules[indices].name        ; print out their names

Uses:

moleculeread freq veltovel shiftvel shiftfreq decode_veldef show vline getxrange getyrange getxvoffset getxunits getxoffset getplotterdc textoidl

pro move(in, out)#

Move the data from the in location to the out location. Anything in out is lost. This uses the value of !g.line. If it is set (1) then the array of line data (!g.s) is used, otherwise the array of continuum data (!g.c) is used. The contents of in are emptied and lost.

Params:

inin, required, type=integer: The buffer to move values from.
outin, required, type=integer: The buffer to move the values to.

Examples:

Move the contents of location 0 to location 10. Then move the contents of 9 to location 0.

copy, 0, 10
copy, 9, 0

Uses:: copy

pro multiply(in1, in2, out)#

This procedure multiplies the data from two data containers stored in the global buffers 0-15.

If no parameters are passed, then the data from buffers 0 and 1 are multiplied and the result is stored in buffer 0. If two parameters are supplied, the data from the first buffer number is multiplied by the data from the second buffer number and the result of the is stored in buffer 0. If three parameters are supplied, the result is stored in the third (output) buffer number.

out = in1 * in2

Params:

in1in, optional, type=integer: First input data buffer number
in2in, optional, type=integer: Second input data buffer number #2
outin, optional, type=integer: Output data buffer number.

Examples:

getrec,1
copy,0,1
getrec,2
multiply

getrec,1
copy,0,10
getrec,2
copy,0,11
multiply,10,11,12   ; The data from buffers 10 and 11 are multiplied
                    ; and the result is stored in buffer 12

Uses:

dcadd dcpaircheck

pro nfit(order)#

Set the order of the polynomial to be fit as a baseline.

Params:

orderin, required, type=integer: The order of polynomial to fit.

Examples:

Get some data, set some regions, fit a 2nd order polynomial

getrec,20
nregion,[100,500,700,1000,1600,2000]
nfit,2
baseline

pro ngauss(ng)#

Sets the value of !g.gauss.ngauss. Must set this before fitting gaussians. The fitgauss procedure will set this for you as you mark off individual gaussians to be fit.

Params:

ngin, required, type=integer: The total number of gauss to fit.

Examples:

; fit three gaussians
ngauss, 3

pro nget(nsave, buffer=buffer, infile=infile, useflag=useflag, skipflag=skipflag, ok=ok)#

Get a previously saved data container with the matching nsave number, and put it in the indicated global buffer number.

Only spectral line data can currently be fetched using an nsave number.

nget fetches data from the output file (keep file) unless infile is set.

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.

Params:

nsavein, required, type=long: nsave number to be retrieved

Keywords:

bufferin, optional, type=long: global buffer number where the retrieved spectrum is stored (defaults to 0).
infilein, optional, type=boolean: if set, use line input file instead of the output file.
useflagin, optional, type=boolean or string, default=true: Apply all or just some of the flag rules?
skipflagin, optional, type=boolean or string: Do not apply any or do not apply a few of the flag rules?

Returns:

okout, optional, type=boolean: status output

Examples:

; get some data getps,10 ; do stuff to it and save result in nsave=50 nsave,50 ; do more stuff to that data, but oops, thats no good ; back to previous state nget,50

Uses:

set_data_container

function nrecords(keep=keep)#

Retrieve the number of records associated with an i/o object.

If the keyword keep is set, the data comes from !g.lineoutio.

If the value of !g.line is true, then the data comes from !g.lineio otherwise the data comes from !g.contio.

Keywords:

keepin, optional, type=bool: the data comes from !g.lineoutio

Returns:

The number of records.

pro nregion(regions)#

Set some regions for use by other GUIDE procedures and functions.

This sets the !g.regions structure with the regions described by the regions argument. Overlaps in regions are eliminated and the resulting contents of !g.regions is a set of unique, non-overlapping regions. Regions are expressed as channel numbers. This procedure always clears the contents of !g.regions before starting.

Note: there is a limit of 100 regions. If you need to use more regions you will need to either use the fitting functions directly or make a local copy of the guide_struct file which defines the !gstructure and edit the sizes in there.

Params:

regionsin, required, type=integer array: The regions to set. If this is a 1D array, then it is interpreted as a sequence of beginning and ending channels which define n_elements/2 regions, inclusive. A warning is issued in that case if n_elements is not a multiple of 2. The trailing, unmatched value will be ignored. Values after the first negative value encountered are also ignored. If this is a 2D array, then the first dimension must be 2 and the second dimension is the number of regions. A warning is issued if this argument gives more than 100 regions. Only the first 100 regions are used in that case. Overlaping regions are eliminated.

Examples:

All of these produce identical results

; as 1-D array
nregion, [125,180,215,300,320,475]
; as 2-D array
nregion, [[125,180],[215,300],[320,475]]
; same regions, beginning and end channels swapped
nregion, [180,125,300,215,320,475]
; overlapping regions
nregion, [125,160,150,180,215,300,320,420,400,475]

pro nsave(nsave, buffer=buffer, dc=dc, ok=ok)#

Save a data container to the current fileout with the indicate NSAVE value. If the !g.sprotect flag is true and nsave already exists, then the output file will not be changed and a message to that effect will be printed out. Otherwise, if nsave exists it will be overwritten with the data being saved so that there will only be at most one instance of each nsave value in any file. The data can be recovered by specifying the nsave search parameter. See the examples.

Params:

nsavein, required, type=integer: The output nsave to use when saving this data.

Keywords:

bufferin, optional, type=integer, default=0: The global buffer number to use when saving to disk.
dcin, optional, type=data container: A specific data container to save. If dc is set, buffer is ignored.
okout, optional, type=integer: Optionally return the exit status of this procedure. This is 1 on success and 0 on failure. This is chiefly useful when used inside another procedure or function.

Examples:

getps,10  ; get some data
; do stuff to it
nsave,50  ; its now in nsave=50
; do more stuff to that data, oops, thats no good
; back to previous state
kget,nsave=50

pro offline(project, acs=acs, sp=sp, vegas=vegas)#

This is a convenient way to find the previously auto-filled data for the indicated project and backend in the standard online data location when used in Green Bank.

Provide a project name and optionally the backend type (acs, vegas, or sp) to connect to file or directory in the online data directory (/home/sdfits) for that project and backend. Note that this file will not be treated as online, and will not be updated, just as filein does not do automatic updates. Continuum is not supported. In addition to being less typing, using offline ensures that should the location of the automatically generated sdfits files move at any point, you don’t have to know where they were moved to - the Green Bank installation of GBTIDL will always know where to find them.

Params:

projectin, required, type=string: The project name to use in constructing the filename’.
acsin, optional, type=boolean: the most recent spectrometer sdfits file will be connected. This is the default.

Keywords:

spin, optional, type=boolean: the most recent spectral processor sdfits file will be connected to.
vegasin, optional, type=boolean: the most recent vegas sdfits directory will be connected.

Examples:

offline,'AGBT02A_028_05'  ; opens ACS data for this project

pro online(acs=acs, sp=sp, vegas=vegas)#

Set the line io object to look at the online file.

The online file is determined by finding the most recently updated spectral line file (ACS, VEGAS, or SP) in the online directory (/home/sdfits). Once a file is connected to, this command must be used again to connect to a more recent spectral line sdfits file (from switching projects or switching backends). The default is to use the most recent file for either spectral line backend. Use one of the two keywords to attach to the most recent file for a specific backend. If both keywords are true, a message will be printed and this procedure will return without changing the attached file.

Note that any file previously attached using filein or offline will be closed as a result of using this procedure. There can be only one input spectral line data file at a time.

The online file may be a directory of FITS files if the vegas backend is the most recently updated file or is chosen as an option here.

Keywords:

acsin, optional, type=boolean: the most recent spectrometer sdfits file will be connected to.
sp: in, optional, type=boolean: the most recent spectral processor sdfits file will be connected to.
vegas: in, optional, type=boolean: the most recent vegas sdfits directory will be connected to.

pro powspec(buffer)#

Compute the power spectrum for the indicated data container, which is overwritten with the result. Uses dcfft to do the fft. This is simply the sum of squares of the real and imaginary parts of the fft on the data.

Use dcpowspec to get the power spectrum for a non-global data container.

Params:

bufferin, out, optional, type=integer, default=0: The global buffer number to use for both input and output.

Uses:

dcfft

pro putchunk(chunk)#

This saves several data containers into the output file (keep file). These must be spectrum data containers. This is most often used in conjuction with getchunk.

Params:

chunkin, required, type=spectrum data container arry: The array of spectrum data containers to save.

Examples:

Copy the input file to the keep file (this is currently only possible in line mode), one scan at a time (in a procedure or function).

scans=get_scan_numbers(/unique)
for i=0,(n_elements(scan)-1) do begin
    a = getchunk(scan=scans[i])
    putchunk, a
    data_free, a
endfor

pro qdflag(scans, thresh=thresh, idstring=idstring, flag_qd_bad=flag_qd_bad, keep=keep)#

Generate flag table entries using QuadrantDetector columns in the associated SDFITS file (QD_XEL, QD_EL, and QD_BAD).

A flag table entry is made for an integration within a scan as follows: * If QD_BAD is 0, flag the data based on the threshold value * If QD_BAD is 1 or -1 (all possible values other than 0), flag

the data if the flag_qd_bad keyword is set otherwise (the default) do not flag the data.

Data which pass the QD_BAD test should be flagged for that integration if

(ABS(QD_XEL) / HPBW) > thresh
HPBW = 740 / (observed_frequency in GHz)

Where the units of QD_XEL and HPBW in the above are arcseconds and thresh defaults to 0.2 if not specified.

The idstring value is used to tag all flag table entries written by this routine. If not supplied it defaults to QD_BADDATA.

This procedure will not reflag any scan where any flag entries already exist with the same idstring. If you want to regenerate the flag table (e.g. using a different threshold or flag_qd_bad value) choose a different idstring or remove all existing flags with that idstring using the unflag procedure.

This uses the main data file unless the keep keyword is set, in which case it uses the keep file.

This only works on spectral line data.

On completion, a table is printed giving the following statistics for each unique source name encountered: the total time observed for that source (this is the duration, not the exposure), the total time flagged, the percent flagged, and the percent of data that had a non-zero QD_BAD value.

For older SDFITS files that lack the QD columns, this routine prints a warning message without flagging any data.

Params:

scansin, required, type=integer: The scan number(s) to flag. If not supplied, use all scans. This can be vector of scan numbers

Keywords:

threshin, optional, type=float, default=0.2: The threshold to use when flagging using good QD_XEL values. Defaults to 0.2.
idstringin, optional, type=string, default=”QD_BADDATA”: The tag to give each flag entry written by this routine. Defaults to “QD_BADDATA”.
flag_qd_badin, optional, type=boolean: If set, flag all data having non-zero values of QD_BAD, otherwise data with QD_BAD is not flagged.
keepin, optional, type=boolean: If set, flag using the keep file, otherwise use the default data file.

pro recomball(doPrint=doPrint)#

Plot the Hydrogen, $\alpha$, $\beta$, $\gamma$, helium $\alpha$, $beta$ and carbon $\alpha$ recombination lines.

Originally by Glen Langston, glangsto@nrao.edu

Keywords:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recomball,/doprint

Uses:

recombh recombhe recombc

pro recombc(dn, doPrint=doPrint)#

Plot the Carbon recombination lines for quantum jump of dN. Defaults to plotting the alpha lines (dN=1).

Originally by Glen Langston, glangsto@nrao.edu

Molecular Formula from Tools of RadioAstronomy, Rolfs and Wilson, 2000, pg 334

\[v_{ki} = Z^2 R_M \left(\frac{1}{i^2} - \frac{1}{k^2}\right),\]

where $R_M = R_\infty/(1 + m/M)$

\[v_{ki} = R_A \left(\frac{1}{i^2} - \frac{1}{k^2}\right) (k > i)\]

where for carbon values (MHz), $R_a = 3.28969163 \times 10^9$

Params:

dnin, optional, type=integer, default=1: The quantum jump to calculate (1 is alpha, 2 is beta, etc).

Keywords:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recombc,2,/doprint

Uses:

veltovel shiftvel shiftfreq show vline getxrange getyrange getplotterdc

pro recombh(dn, doPrint=doPrint)#

Plot the Hydrogen recombination lines for quantum jump of dN. Defaults to plotting the alpha lines (dN=1).

Originally by Glen Langston, glangsto@nrao.edu

Molecular Formula from Tools of RadioAstronomy, Rolfs and Wilson, 2000, pg 334

\[v_{ki} = Z^2 R_M \left(\frac{1}{i^2} - \frac{1}{k^2}\right),\]

where $R_M = R_\infty/(1 + m/M)$

\[v_{ki} = R_A \left(\frac{1}{i^2} - \frac{1}{k^2}\right) (k > i)\]

where for hydrogen values (MHz), $R_a = 3.28805129\times 10^9$

Params:

dnin, optional, type=integer, default=1: The quantum jump to calculate (1 is alpha, 2 is beta, etc).

Keywords:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recombh,2,/doprint

Uses:

veltovel shiftvel shiftfreq show vline getxrange getyrange getplotterdc

pro recombhe(dn, doPrint=doPrint)#

Plot the Helium recombination lines for quantum jump of dN. Defaults to plotting the alpha lines (dN=1).

Originally by Glen Langston, glangsto@nrao.edu

Molecular Formula from Tools of Radio Astronomy, Rolfs and Wilson, 2000, pg 334

\[v_{ki} = Z^2 R_M \left(\frac{1}{i^2} - \frac{1}{k^2}\right),\]

where $R_M = R_\infty/(1 + m/M)$

\[v_{ki} = R_A \left(\frac{1}{i^2} - \frac{1}{k^2}\right) (k > i)\]

where for helium values (MHz), $R_a=3.28939118\times 10^9$

Params:

dnin, optional, type=integer, default=1: The quantum jump to calculate (1 is alpha, 2 is beta, etc).

Keyword:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recombh,2,/doprint

Uses:

veltovel shiftvel shiftfreq show vline getxrange getyrange getplotterdc

pro recombn(dn, doPrint=doPrint)#

Plot the Nitrogen recombination lines for quantum jump of dN. Defaults to plotting the alpha lines (dN=1).

Originally by Glen Langston, glangsto@nrao.edu

Molecular Formula from Tools of RadioAstronomy, Rolfs and Wilson, 2000, pg 334

\[v_{ki} = Z^2 R_M \left(\frac{1}{i^2} - \frac{1}{k^2}\right),\]

where $R_M = R_\infty/(1 + m/M)$

\[v_{ki} = R_A \left(\frac{1}{i^2} - \frac{1}{k^2}\right) (k > i)\]

where for nitrogen values (MHz), $R_a = 3.28971314\times 10^9$

Params:

dnin, optional, type=integer, default=1: The quantum jump to calculate (1 is alpha, 2 is beta, etc).

Keywords:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recombn,2,/doprint

Uses:

veltovel shiftvel shiftfreq show vline getxrange getyrange getplotterdc

pro recombo(dn, doPrint=doPrint)#

Plot the Oxygen recombination lines for quantum jump of dN. Defaults to plotting the alpha lines (dN=1).

Originally by Glen Langston, glangsto@nrao.edu

Molecular Formula from Tools of RadioAstronomy, Rolfs and Wilson, 2000, pg 334

\[v_{ki} = Z^2 R_M \left(\frac{1}{i^2} - \frac{1}{k^2}\right),\]

where $R_M = R_\infty/(1 + m/M)$

\[v_{ki} = R_A \left(\frac{1}{i^2} - \frac{1}{k^2}\right) (k > i)\]

where for oxygen values (MHz), $R_a = 3.28972919\times 10^9$

Params:

dnin, optional, type=integer, default=1: The quantum jump to calculate (1 is alpha, 2 is beta, etc).

Keywords:

doPrintin, optional, type=boolean, default=0: optionally print the line frequencies. The printed frequencies are the line frequencies in the frame being displayed on the plotter.

Examples:

recombo,2,/doprint

Uses:

veltovel shiftvel shiftfreq show vline getxrange getyrange getplotterdc

pro replace(bchan, echan, zero=zero, blank=blank)#

Replace spectral channels by interpolation, or with zero values or blanks. If neither zero or blank are set, the data between bchan and echan are replaced with a straight line connecting the two end points. If neither bchan or echan are given the user is prompted select the region to be replaced on the plotter.

Params:

bchanin, optional, type=float: Starting channel. If this is a floating point value it is first rounded (using the IDL round function) before being used.
echanin, optional, type=float: Ending channel. If this is a floating point value it is first rounded (using the IDL round function) before being used.

Keywords:

zeroin, optional, type=boolean: If this keyword is set, the data are replaced with zero values. Otherwise, the replacement data values are interpolated from the endpoints.
blankin, optional, type=boolean: If this keyword is set, the data are replaced by IEEE NaN (not a number). Such values are treated as missing data (not used in operations, not shown on the plotter, etc). If both blank and zero are set, zero takes precedence and the data will not be blanked.

Examples:

getrec,1
chan               ; set the X-axis to channels
replace,1023,1025  ; replace the channel range 1023-1025
freq               ; set the X-axis to GHz
replace            ; prompt user for ranges and replace the values
replace,15,/zero   ; set the data value at channel 15 to 0.0
replace,2014,/blank; set the data value at channel 2014 to NaN

pro report_gauss(fits=fits, params=params)#

Procedure for printing what the current regions and gaussians are in the guide structure, and the most recently reported fits for these gaussians.

If /fits is the only keyword set, then only the fitted parameters will be reported. If /params is the only keyword set, then only the intiial guesses will be reported. If both are set or neither are set (the default) then both initial guesses and fits are reported for each Gaussian.

Keywords:

fitsin, optional, type=boolean: displays the fits for all gaussians
paramsin, optional, type=boolean: displays the initial parameters for all gaussians

pro resample(newinterval, keychan, buffer=buffer, nearest=nearest, linear=linear, lsquadratic=lsquadratic, quadratic=quadratic, spline=spline)#

Resample a spectrum data container onto a new frequency axis using one of four possible interpolation methods.

Takes the data values in the data container indicated by the parameter buffer and interpolates them onto a new frequency axis derived from the newinterval and keychan arguments. The reference_frequency is unchanged by this operation. The new frequency_interval is given by the newinterval argument. The new frequency axis is determined by choosing one channel in the original frequency axis and requiring that the frequency at that channel be centered on one of the channels in the interpolated data (the keychan argument). This sets the new reference frequency. When not supplied, keychan defaults to the channel nearest to the original reference channel.

The data container indicated by the buffer parameter is altered by this procedure. The data values will contain the interpolated values and the header will describe the new frequency axis. The number of channels in the resulting interpolated data is just enough to use as much of the original data as possible without trying to interpolate beyond the ends of that data.

Interpolation is accomplished by using the IDL INTERPOL procedure except when ‘nearest’ is set, in which case it is done by this procedure. Blanked values (NaN) are ignored. See the documentation for INTERPOL for details about the various interpolation methods.

This procedure only works in line mode.

Params:

newintervalin, required, type=real: The new frequency_interval to use in the interpolation. This value must be nonzero. If it has opposite sign from the input frequency interval, invert will be used to first reverse the sense of the frequency axis.
keychanin, optional, type=integer: The new frequency axis will have one channel where the frequency value equals the original frequency value at the keychan channel. When keychan is not supplied, it defaults to the channel nearest to the reference_channel.

Keywords:

bufferin, optional, type=integer, default=0: The data container buffer to use. Defaults to 0, the primary data container.
nearestin, optional, type=boolean: When set do nearest-neighbor interpolation.
linearin, optional, type=boolean: When set (the default), do a linear interpolation.
lsquadraticin, optional, type=boolean: When set do a least squares quadratic fit interpolation.
quadraticin, optional, type=boolean: When set do a quadratic fit interpolation.
splinein, optional, type=boolean: When set do spline interpolation.

Examples:

; data container 0 has a spectrum in it
; copy it elsewhere
copy,0,10
; do a linear interpolation to 1.5 x the channel spacing
resample,!g.s[0].frequency_interval*1.5
; the next line is exactly equivalent to "dcinvert"
resample,-!g.s[0].frequency_interval
; Use buffer 10, use channel 0 as the keychan and
; do a spline interpolation, make sure things are ok
resample,!g.s[10].frequency_interval*1.5,0,buffer=10,/spline

Uses:

dcresample show

function samplerinfo(scan, sampler, instance=instance, file=file, timestamp=timestamp, quiet=quiet, recs=recs)#

Find the if, feed, and polarization numbers which corresponds to the given sampler name in the scan.

A three-element array is returned having the value (ifnum, plnum, fdnum) corresponding to the IF, feed, and polarization numbers associated with the given sampler name and scan.

If the same scan appears more than once in the data file then the value corresponding to instance will be returned. If instance is omitted, the first instance (instance=0) will be returned. The instance and file keywords can be used to ensure that a single scan is used. Alternatively, the timestamp keyword can be used to ensure that a single scan is used (scan and instance are ignored in that case).

If the requested sampler is not found in the scan, the all values of the returned array will be -1.

There is no check to make sure that there is just one (ifnum, plnum, fdnum) associated with the given sampler. The values for the first matching sampler are returned.

Params:

scanin, required, type=integer: scan number
samplerin, required, type=string: sampler name

Keywords:

instancein, optional, type=integer: Which occurence of this scan should be used. Default is 0.
filein, optional, type=string: When specified, limit the search for this scan (and instance) to this specific file. Default is all files.
timestampin, optional, type=string: The M&C timestamp associated with the desired scan. When supplied, scan and instance are ignored.
quietin, optional, type=boolean: When set, suppress most error messages. Useful when being used within another procedure.
recsout, optional, type=integer array: This contains the records (index numbers) from this sampler in the indicated scan. This is useful when you want to fetch that data immediately using getchunk since that will not involve any further selection and hence will be faster. This is used by all of the get* calibration routines (which use get_calib_data, where the work is actually done). If there is no matching data, this value will be -1.

Returns:

array of [ifnum,plnum,fdnum]

pro scale(factor, buffer)#

This procedure scales the data container’s data by a scalar value.

Equivalent to: *!g.s[0].data_ptr = *!g.s[0].data_ptr * factor

Params:

factorin, required, type=float: scale factor
bufferin, optional, type=int: The global buffer number containing the data to be scaled

Examples:

get,index=1
show
scale,1.3
show

Uses:: dcscale

function scan_info(scan, file, keep=keep, quiet=quiet, count=count)#

Get scan information structure from the appropriate I/O object.

This uses !g.line to determine which I/O object to get the information from, unless keep is set, in which case it gets it from the keep file.

Note that this may return more than one structure (an array of structures would be returned). This can happen if the same scan number appears in the data with more than one timestamp. The instance and timestamp keywords of the various data retrieval procedures (getscan, get, getnod, getps, etc) can be used to differentiate between these duplicate scans. The instance keyword in those cases corresponds to the element number of the array returned by scan_info. The timestamp keyword corresponds to the timestamp field in the scan_info structure.

The data corresponding to a given instance are always found in consecutive records. The index_start and nrecords fields can be used to get just the data associated with a specific instance. See the examples.

The fields in the returned structure are:

SCAN	the scan number, long integer
PROCSEQN	the procedure sequence number, long integer
PROCEDURE	the procedure name, string
TIMESTAMP	the timestamp associated with this scan, string
FILE	the name of the file where this scan was found
N_INTEGRATION	the number of integrations, long integer. Note that different samplers may have different numbers of integrations. This value is the number of unique times (MJD) found for this scan. Use `N_SAMPINTS` for the number of integrations from a given sampler.
N_FEEDS	the number of feeds, long integer
FDNUMS	the specific FDNUM values for this scan
N_IFS	the number of IFs, long integer
IFNUMS	the specific IFNUM values for this scan
IFTABLE	a 3-axis array indicating which combinations of `ifnum`, `fdnum` and `plnum` are present in the data. The first axis is `ifnum`, the second axis is `fdnum` and the 3rd is `plnum`. Combinations with data have 1 in this array. Combinations without data have a 0. Note: IDL removes any trailing axis of length 1 (degenerate) so care must be taken when using the shape of this array. E.g. if there is no third axis, then there is only one plnum, `plnum=0`.
N_SWITCHING_STATES	the number of switching states, long integer
N_CAL_STATES	the number of cal switching states, long integer
N_SIG_STATES	the number of sig switching states, long integer
N_WCALPOS	the total number of unique WCALPOS values in this scan. (spectral line data only)
WCALPOS	a vector giving the list of unique WCALPOS (WBand receiver calposition) values for this scan (spectral line data only)
N_POLARIZATIONS	the number of unique polarizations, long integer, will always be less then or equal to 4
POLARIZATIONS	a vector containing the actual polarizations, string (unused elements are the null string)
PLNUMS	vector containing the PLNUM values corresponding to each POLARIZATION, long integer (unused elements are -1)
FEEDS	a vector containing the unique feed ids, long integer (unused elements are -1)
BANDWIDTH	a vector containing the unique bandwidths, one for each IF (Hz)
INDEX_START	the starting index number for this scan
NRECORDS	the total number of records in this scan
N_SAMPLERS	the total number of unique sampler names in this scan
SAMPLERS	the list of unique sampler names
N_SAMPINTS	the number of integrations for each sampler
N_CHANNELS	the number of channels in each spectrum for each sampler

Params:

scanin, required, type=integer: Scan number to get information on.
filein, optional, type=string: Limit the search for matching scans to a specific file. If omitted, scans are found in all files currently opened through filein (a single file) or dirin (possibly multiple files).

Keywords:

keepin, optional, type=boolean: If set, the scan information comes from the keep file.
quietin, optional, type=boolean: When set, suppress most error messages. Useful when being used within another procedure.
countin, optional, type=integer: Returns the number of elements of the returned array of scan_info structures.

Returns:

Scan information structure. Returns -1 on error.

Examples:

Get all of the data associated with one scan.

a = scan_info(65)
indx = lindgen(a.nrecords) + a.index_start
d65 = getchunk(index=indx)
... do stuff with d65, but don't forget to free it when done
data_free, d65

Find paired scan’s and their info structure (e.g. position switched)

a = scan_info(65)
b = find_paired_info(a)

pro sclear(accumnum)#

Clears one of the global accum buffers (frees the pointer, zeros values).

Params:

accumnumin, optional, type=integer, default=0: the accum buffer to clear, in the range of 0 through 3. Defaults to 0.

Uses:

accumclear

pro select(count, keep=keep, quiet=quiet, _EXTRA=ex)#

This procedure is used to select data from the current data file for later processing.

Selection puts the index numbers that match the selection criteria onto the end of the stack using appendstack. Once the index numbers are there, the can be used in a call to get or to kget to retrieve them from the data source.

Data can be selected based on entries in the index file, such as source name, polarization type, IF number, etc. For a complete list of eligible parameters use the procedure listcols.

See the discussion on “Select” in the GBTIDL User’s Guide here for a summary of selection syntax.

The selection criteria are ultimately passed to the io class’s search_index via the _EXTRA parameter.

Params:

countout, optional, type=integer: The number of records selected and added to the stack.

Keywords:

keepin, optional, type=boolean: If set, the selection comes from the keep file. If not set, the selection comes from the input file.
quietin, optional, type=boolean: Turn off informational messages.
_EXTRAin, optional, type=extra keywords: These are the selection parameters.

Examples:

select,source='Orion*',/keep
for i=0,(!g.acount-1) do begin
    get,index=astack(i)
    ; do things here
endfor

Uses:

select_data appendstack

pro set_data_container(data, buffer=buffer, ignore_line=ignore_line, noshow=noshow)#

Set the element of the appropriate GUIDE data structure array.

If !g.line is true, the value is copied into the desired buffer in !g.s, otherwise it is copied in to !g.c. This is most often used when working with toolbox procedures and function where a data container is used directly as an IDL variable and then copied into the guide structure so that it can be used with guide procedures and functions (e.g. show).

Params:

datain, required: A data container (continuum or spectrum) to put into the indicated location.

Keywords:

bufferin, optional, type=integer: The location to put the data. When not supplied the 0 location is used.
ignore_linein, optional, type=boolean: When set, the value of !g.line is ignored and the choice of which data array to use is determined by the contents of data.
noshowin, optional, type=boolean: Normally, if buffer is 0 and !g.frozen is 0 then show is called at the end. If this is set, that behavior is turned off.

pro setdata(value, elements, buffer=buffer)#

Convenience function for setting data array of a data container.

Params:

valuein, required, type=float: data values to be inserted into the data container. Either a single float value or an array of floats are valid.
elementsin, optional, type=long, default=all: The data array indices to be changed. Use one integer to set a single element in the data array. Use a two element array to specify a range to be set.

Keywords:

bufferin, optional, type=integer, default=0: The data container buffer number from which the data values are retrieved.

Examples:

Put the first spectra into !g.s[0], retrieve all its data, and then just the first element

filein,'file.fits'
getrec,1
help, *!g.s[0].data_ptr
<PtrHeapVar257> FLOAT     = Array[2048]
x = fltarr(1026)
setdata, x
help, *!g.s[0].data_ptr
<PtrHeapVar257> FLOAT     = Array[1026]
setdata, 2.5, 0
help, (*!g.s[0].data_ptr)[0]
<PtrHeapVar257> FLOAT     = 2.5

Uses:

data_valid setdcdata

pro setfframe(buffer, toframe=toframe)#

Procedure to reset the frequency reference frame of the indicated buffer (defaults to the primary data container, buffer 0)

The frequency axis reference frame is given by the frequency_type header value. Normally this remains “TOPO”, the topocentric frame in which the data were originally taken. The default GBTIDL display routines use the reference frame found in the velocity_definition header value. This procedure can be used to set the frequency axis values to that frame (or any other valid reference frame). This can be useful when exporting the data to an environment that doesn’t know about anything except the frequency information.

This routine will not change the displayed frequency axis.

If the frame is not set, the one implied by the data header velocity_definition is used.

This routine adjusts the following header values: reference_frequency, frequency_interval, frequency_type and center_frequency. When written to an SDFITS table, the first three of these four values correspond to CRVAL1, CDELT1, and CTYPE1, in that order.

Nothing is changed if the frame is already set to the desired frame.

Nothing is changed if the frame is unrecognized.

Params:

bufferin, required, type=spectrum: The data container to be adjusted. Defaults to the primary data container (0).

Keywords:

toframein, optional, type=string: The reference frame to use. If not supplied, the value implied by the last 4 characters of the velocity_definition the data container. See frame_velocity for a full list of supported reference frames.

Uses:

dcsetfframe

pro setfind(param, val1, val2, append=append)#

Set a selection parameter to be used later by find.

This sets one of the fields in the structure used by FIND. There is one field for each of the possible selection parameters (use listcols to see a list of the available search parameters). A single value can be entered as can a range of values. Or, a single string can be used here in which case that string is saved as is to be used by SELECT inside of FIND. See the discussion on “Find” in the GBTIDL User’s Guide here for selection syntax examples. This routine can be used to either replace the current selection parameter value with another (the default behavior) or it can be used to append more information to the current selection parameter value.

See listfind to show the current value of any of the possible selection parameters used by FIND.

clearfind can be used to unset selection parameters used by FIND.

Params:

paramin, optional, type=string: The selection parameter to set. If this parameter is omitted, the user is asked to choose from the list of available parameters and all other parameters (val1 and val2) are ignored. Min-match is used to find the parameter to set. If more than one parameter matches, a warning is printed and the procedure ends without setting any values. Case is not important.
val1in, optional, type=appropriate to param: The value that param is set to. Any valid selection syntax (strings, integers or floating point values) is allowed here. If val2 is also used, then these two values define a range and that range is the value that the selection parameter is set to. In that case, val1 and val2 must not be strings since string selection parameters (e.g. source) do not allow ranges. If val1 is a string then val2 is ignored if supplied and val1 is used “as is” for the selection parameter. There is no syntax checking of string values at this step so an impromperly formed selection string may generate an error later when FIND is used. If not supplied, the user is asked for a value.
val2in, optional, type=floating or integer: This is used with val1 to define a selection range. If not supplied, only val1 is used and the user is not prompted for val2.

Keywords:

appendin, optional, type=boolean: When set, the selection parameter value is appended to the existing parameter value for this parameter. Otherwise, the existing value is replaced with the new value.

Examples: