Quick Reference for GBTIDL v2.8

Quick Reference for GBTIDL v2.8#

For help with a routine from the gbtidl command line, use the usage command, for example:

usage, "show"

or for more information:

usage, "show", /verbose

or to view the IDL source:

usage, "show", /source

GUIDE starts in spectral line mode. To switch to continuum mode, type cont at the GBTIDL prompt. To switch to line mode, type line at the GBTIDL prompt.

Note

In the following tables, optional arguments are in [brackets].

Data Operations#

Retrieving and Saving Data#

Table 38 Retrieving and Saving Data#

dirin, [dir_name, /new_index]

Input from the given directory

filein, [file_name, /new_index]

Input from the given SDFITS file

fileout, file_name [/new]

Open an SDFITS file for writing

files, [/full]

Lists the input and output files currently in use

flag, [scan, intnum, plnum, ifnum, fdnum, sampler, bchan, echan, chans, chanwidth, idstring, scanrange, /keep]

Add a flag rule to the line data file

flagrec, record,[bchan,echan,chans, chanwidth, idstring, /keep]

Add a record-based flag rule to the line data file

get, [useflag, skipflag, parameters]

Retrieve a record from the input file

getchunk ([count,useflag, skipflag, indicies, /keep, parameters])

Retrieve multiple data containers at a time

getdata ([buffer,elements,count])

Returns the data into an IDL array

getrec, index [useflag, skipflag]

Retrieve a record at the given index

getscan, scan [useflag, skipflag]

Retrieve the first record with the given scan number

keep, [dc)

Save a spectrum to the output SDFITS file

kget, [useflag, skipflag, parameters]

Retrieve a record from the output file

kgetrec, index, [useflag, skipflag]

Retrieve a record at the given index from the output file

kgetscan, scan, [useflag, skipflag]

Retrieve the first record with the given scan number from the output file

nget, nsave, [buffer,/infile, useflag, skipflag, ok]

Retrieve a record with a given nsave identifier

nsave , nsave, [buffer, dc, ok]

Save to the output file, with an nsave identifier

offline, project, [/acs, /sp]

A shortcut for filein, used only in Green Bank

online, [/acs, /sp]

Connect to the online data file, used only in Green Bank

putchunk, chunk

Save multiple data containers to the output file

setdata, value, [elements, buffer]

Replaces the data in a DC with the values in an IDL array

set_data_container, data, [buffer, /ignore_line, /noshow]

Copy a data container into a global buffer

sprotect_off

Turns off write protection for nsave entries

sprotect_on

Turns on write protection for nsave entries

unflag, id, [/keep, /all]

Remove all flag rules with the same idstring or id number

Using the Stack#

Table 39 Using the Stack#

addstack, first, [last, step]

Add enumerated entries to the stack

appendstack, index

Append array of entries to the stack

astack ([elem, count])

Returns the value of a given entry or all entries in the stack

avgstack, [/noclear, /keep, useflag, skipflag]

Average spectra identified by entries in the stack

clearfind, [param]

Clear selection parameters used by find

delete, index

Remove individual entries from the stack

deselect, [/keep, parameters]

Remove entries from the stack based on the given selection criteria

emptystack, [/reset, /shrink]

Clear the stack

find, [/append,/keep]

Put selections in the stack using previously set parameters (setfind)

listfind,[param]

List selection parameters used by find

liststack, [start, finish, sortcol, columns, /user, /keep, parameters]

List records from the input data file that correspond to entries in the stack

select, [count, /keep, /quiet, parameters]

Add entries to the stack based on the given selection criteria

setfind, [param, val1, val2, /append]

Set a selection parameter used by find

tellstack

List the stack entries

Parameters for Data Retrieval and Selection#

Table 40 Available search parameters for data retrieval and selection using listcols in line mode#

azimuth

bandwidth

cal

centfreq

dateobs

e2escan

elevation

exposure

extension

fdnum

feed

file

freqint

freqres

ifnum

index

int

latitude

longitude

lst

nsave

numchn

obsid

plnum

polarization

procedure

procseqn

project

restfreq

row

sampler

scan

sig

source

subref

timestamp

trgtlat

trgtlong

tsys

velocity
Table 41 Available search parameters for data retrieval and selection using listcols in continuum mode#

cal

e2escan

extension

file

firstrow

ifnum

index

nsave

numrows

obsid

polarization

procedure

procseqn

project

scan

sig

source

stride

trgtlat

trgtlong

Using Data Containers#

Table 42 Using Data Containers#

add, [in1, in2, out]

Adds DC’s based on buffer numbers. out = in1+in2

bias, factor, [buffer]

Add a bias to the spectrum in the buffer

copy, in, out

Copies a data container to another buffer

divide, [in1, in2, out]

out=in1/in2

move, in, out

Moves a data container to another buffer

multiply, [in1, in2, out]

out=in1*in2

scale, factor, [buffer]

Scale the spectrum in the PDC

subtract, [in1, in2, out]

out=in1-in2

Getting Information about Scans and Files#

Table 43 Getting Information about Scans and Files#

get_scan_numbers ([count, /keep, /unique, parameters])

Get a list of scan numbers from the input data file

header, [dc]

Show the record header

lastrec ([/keep])

Record number of the most recently retrieved data container

lastscan ([/keep])

Scan number of the most recently retrieved data container.

list, [start, finish, sortcol, columns, file, /user, /keep, parameters]

List records from the input file

listflags,[idstring, /summary, /keep]

List the flag rules

listids,[/keep]

List the unique idstrings in the current set of flag rules

ls, [pattern, options]

List FITS files (default) or any other files in the directory

nrecords ([/keep])

Returns the number of records in the input or output file

scan_info (scan,[file, /keep, /quiet, count])

Returns some info such as num IFs, num integrations, etc.

summary, [file]

Gives a summary of scans in the input file

table, [buffer, brange, erange]

List data in tabular form

Plotter Operations#

Table 44 Plotter Operations#

annotate, x, y, text, [color, charsize, /normal, /noshow]

Add text annotation to a plot

bdrop, nchan

Drop initial channels from spectrum display

chan

Set X-axis units to channels

chantox (chans, [type, dc])

Returns X-values for given list of channels

clear

Erase the plotter

clearannotations, [/noshow]

Clear annotations

clearmarks, [/noshow]

Clear marks (the “+” markers)

clearoplots, [index, idstring]

Clear overplots

clearoshows

Clear oshows

clearovers

Clear oshows and oplots

clearvlines, [/noshow,idstring]

Clear vlines

click ([frame, veldef, /nocrosshair, /noshow, label])

Returns position of a mouse click

crosshair, [/on, /off]

Toggle crosshair cursor

edrop, nchan

Drop end channels from spectrum display

freex

Sets the X-axis range to autoscale

freexy

Sets X- and Y-axis to autoscale (equivalent to unzoom)

freey

Sets the Y-axis range to autoscale

freeze

Freeze the plotter, i.e. set auto update off

freq

Set the X-axis units to frequency

gbtoplot, [x], y, [color, /chan, index, idstring]

Overplot a set of X, Y points

getplotterdc ([/copy])

Get the currently displayed data container

getxarray ([count])

Get the xarray values for the currently displayed data

getxframe ()

Get the current reference frame (LSR, TOPO, etc)

getxoffset ()

Get the current X-offset (0.0 unless relative X-axis has been toggled)

getxrange ([empty])

Get the current X-range

getxunits ()

Get the current X-axis unts (counts, km/s, GHz, etc)

getxveldef ()

Get the current velocity definition (RADIO, OPTICAL, TRUE)

getxvoffset ()

Get the current velocity offset in m/s

getyarray ([count])

Get the data values for the currently displayed data

getyrange ([empty])

Get the current Y-range

histogram, [/on, /off]

Toggles between histogram-style and connected-points style plots

oshow, [dc, color]

Overlay spectrum on the displayed plot

print_ps, [filename, device, /portrait]

Send the plot to the printer

reshow

Re-draw everything known to the plotter

setabsrel, absrel

Sets X-axis in Absolute (absrel=’Abs’) or Relative (absrel=’Rel’) units

setframe, frame

Sets reference frame for X-axis

setmarker, x, y, [text]

Places a marker on the plot at the desired location

setveldef, veldef

Sets velocity definition for X-axis

setvoffset, voffset, [veldef]

Sets the offset velocity

setx, [x1, x2]

Sets the range on the X-axis

setxunit, unit [/noreshow]

Sets the units for the X-axis

setxy, [xmin, xmax, ymin, ymax]

Sets the range on the X- and Y-axes

sety, [y1, y2]

Sets the range on the Y-axis

show, [dc, color, /defaultx, /smallheader, /noheader]

Displays a data container on the plotter

showregion, [/off]

Turn on and off the display of baseline region boxes

toggleovers, [/on, /off]

Toggles overlays

unfreeze

Unfreeze the plotter, i.e. set auto update on

unzoom, [/onestep]

Unzoom the plot

velo

Set the x-axis units to velocity

vline, x, [ylabel, label, /noshow, /ynorm, idstring]

Draw a vertical line on the plot

write_ascii, [filename, /prompt, brange, erange]

Writes the data in PDC to an ASCII file

write_ps, [filename, /portrait, /prompt]

Writes the displayed plot to a postscript file

xtochan (xvalues, [dc])

Returns channel number that corresponds to the given x-values

zline, [/on, /off]

Toggles the zero line

Analysis Procedures#

Averaging#

Table 45 Averaging#

accum, [accumnum, weight, dc]

Add a spectrum to the accumulator

ave, [accumnum, wtarray, count, /noclear,/quiet]

Average data in the accumulator

avgstack, [/noclear, /keep, useflag, skipflag]

Average entries in the stack

fshift ([accumnum, buffer, frame])

Determine a shift to align in frequency

gshift, offset, [buffer, /wrap, ftol, /nowelsh, /nopad, /linear, /quadratic, /lsquadratic, /spline, /cubic, ok]

Apply a shift to align spectra

sclear, [accumnum]

Clear the accumulator buffer

vshift ([accumnum, buffer, frame, veldef, voffset])

Determine a shift to align in velocity

xshift ([accumnum, buffer])

Determine a shift to align in current X-axis units

Baselines#

Table 46 Baselines#

baseline, [nfit, modelbuffer, ok]

Fits and subtracts a baseline from the PDC spectrum

bmodel, [modelbuffer, nfit, ok]

Writes a baseline model into a DC using coeffs from a previous fit

bshape, [nfit, /noshow, modelbuffer, ok, color]

Fit and display a baseline as an overplot without subtracting it

bshow, [nfit, ok, color]

Overplot the most recently fit baseline

bsubtract, [nfit, ok]

Subtracts a baseline determined from the stored coeffs

clearregion

Clear all baseline regions

getbasemodel ([ nfit, ok])

Return a baseline polynomial evaluated at all channels in the PDC

nfit, order

Sets the order of the (orthogonal) polynomial to be fit

nregion, regions

Defines the regions to be used for a baseline fit

setregion

Interactive use of the cursor to define the baseline region

Calibration#

Table 47 Calibration#

fold, [sig, ref, ftol]

Fold a frequency-switched scan (also done in getfs)

getbs, scan, [ifnum, intnum, plnum, sampler, trackfdnum, bswitch, tsys, tau, ap_eff, smthoff, units, tcal, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file, timestamp, status]

Retrieves and calibrates a total power nod beamswitched scan pair

getcal, scan, [ifnum, intnum, plnum, fdnum, sampler, tcal, sig_state, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file, timestamp, status]

Retrieves the “cal” signal from a cal-switched scan.

getfs, scan, [ifnum, intnum, plnum, fdnum, sampler, tsys, tau, ap_eff, smthoff, units, tcal, /nofold, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file, timestamp, status]

Retrieves and calibrates a frequency switched scan

getnod, scan, [ifnum, intnum, plnum, sampler, trackfdnum, tsys, tau, ap_eff,smthoff,units, tcal, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file,timestamp,status]

Retrieves and calibrates a total power nod scan pair

getps, scan, [ifnum, intnum, plnum, fdnum, sampler, tsys, tau, ap_eff, smthoff, units, tcal, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file, timestamp, status]

Retrieves and calibrates a total power position switched scan pair

getsigref, sigscan, refscan, [ifnum, intnum, plnum, fdnum, sampler, tsys, tau, ap_eff, smthoff, units, tcal, /eqweight, /quiet, /avgref, /keepints, useflag, switched pair, skipflag, siginstance, sigfile, sigtimestamp, refinstance, reffile, reftimestamp, status]

Retrieves and calibrates a total power position with the user identifying the sig scan and ref scan separately

gettp, scan, [ifnum, intnum, plnum, fdnum, sampler, tcal, sig_state, cal_state, /eqweight, /quiet, /keepints, useflag, skipflag, instance, file, timestamp, status]

Retrieves and calibrates a single total power scan

Gaussians#

Table 48 Gaussians#

fitgauss, [fit, fitrms, modelbuffer, highlightcolor]

Interactive procedure to fit Gaussians to the spectrum

gauss, [fit, fitrms, buffer, modelbuffer, ok, /quiet]

Fits Gaussians to the spectrum, based on initial values set by procedures gregion, ngauss, gmaxiter, and gparamvalues

gmaxiter, maxiter

Sets max number of iterations for Gauss fitter

gparamvalues, gauss_index, values

Sets initial guesses for Gauss fitter

gregion, regions

Sets the regions used for Gauss fitter

gshow, [modelbuffer, /parts, color]

Displays the Gaussian fits on the plotter

ngauss, ng

Sets the number of Gaussians to be fit

report_gauss, [/fits, /params]

Prints the results of a Gaussian fit on terminal

Other#

Table 49 Other commands#

boxcar, width, [buffer, /decimate]

Boxcar smoothing

clip, datamin, datamax, [buffer, /blank]

Truncate spectrum to a min and max data value

decimate, [nchan, startat, buffer, ok]

Decimate the spectrum by paring channels

gconvol, kernel, [scale_factor, buffer, ok, /normalize, /center, /edge_wrap, /edge_truncate, missing, /nan, /normalize]

Convolve the spectrum in the PDC with an array

gfft, [real_buffer, imag_buffer, /inverse, bdrop, edrop]

FFT or inverse FFT the spectrum

ginterp,[buffer, bchan, echan, /linear, /quadratic, /lsquadratic, /spline]

Interpolate across blanked channels

gmeasure,mode,fract,[brange, erange, rms, /chan, lefthorn, righthorn, /quiet,ret]

Find paramaters of a galaxy profile

gmoment,[bmoment, emoment, /chan, /full, /quiet, ret]

Find moments of the data in the PDC

gsmooth, newres, [buffer, /decimate]

Gaussian smooth the spectrum in the PDC to the newres resolution (channels)

gstatus, [/full]

Summarize status of GBTIDL

hanning, [buffer, /decimate, ok]

Hanning smooth the spectrum in the PDC

invert, [buffer]

Flip the data end-to-end

mediansub, width, [buffer]

Subtract the median filtered values of the given width from the data

molecule, [/doprint]

Show molecular transition frequencies on the plotter

powspec, [buffer]

Compute power spectrum of the specified DC

recomball, [/doprint]

Plot the H alpha, beta, gamma; He \(\alpha\), beta and C alpha recombination lines

recombc, [dn, /doprint]

Compute and plot frequencies of Carbon recombination lines

recombhe, [dn, /doprint]

Compute and plot frequencies of Helium recombination lines

recombh, [dn, /doprint]

Compute and plot frequencies of Hydrogen recombination lines

recombn, [dn, /doprint]

Compute and plot frequencies of Nitrogen recombination lines

recombo, [dn, /doprint]

Compute and plot frequencies of Oxygen recombination lines

replace, [bchan, echan, /zero, /blank]

Replace bad data values with interpolated or zero values

resample, newinterval, [keychan, buffer, /nearest, /linear, /lsquadratic, /quadratic, /spline]

Resample the spectrum in the PDC at the new interval (channels)

stats, [brange, erange, /full, /chan, /quiet, ret]

Provide statistics

usage, proname, [/verbose, /source]

Print out usage information on the named procedure or function