GBTIDL plotter commands

GBTIDL plotter commands#

`annotate`	This procedure places a text string on the plot
`bdrop`	This procedure is used to specify how many channels at the beginning of
`chantox`	Convert the given channels numbers to the x values appropriate for
`clearannotations`	Removes all annotations from the current plot.
`clearmarks`	Clear all marks (+ plus associated text) from the plotter.
`clearoplots`	Clear any over plots. This removes them from the plotters state and
`clearvlines`	Clear all vertical lines and associated text from the plotter.
`click`	Get cursor position when the user presses a mouse button. Positions
`crosshair`	This procedure toggles a flag to draw a crosshair cursor. Use the
`edrop`	This procedure is used to specify how many channels at the end of
`gbtoplot`	Overplots using oplot on to the GBT plotter's surface. It also
`getxarray`	Get the current x-array. Useful so that the caller doesn't have to
`getyarray`	Get the current array of y values. Useful so that the caller
`getplotterdc`	Get the current data container. If copy is true, make this a true
`getxrange`	Get the current x-range
`getyrange`	Get the current y-range
`histogram`	This procedure toggles a flag to draw the plot in histogram
`oplotfn`	Overplots a function using oplot on to the GBTIDL plotter's surface.
`oshow`	Plot a data container on top of (over) the current plot.
`print_ps`	This procedure prints a postscript file that reproduces the spectrum
`setabsrel`	This procedure sets the flag that indicates whether the xaxis is in
`setframe`	This procedure sets the reference frame to be used in
`setmarker`	This procedure sets a marker on the plot at the given location.
`setveldef`	This procedure sets the velocity definition to be used in
`setvoffset`	Procedure to set the velocity offset in the plotter, in the current frame.
`setx`	Set the x-axis range either directly or with the cursor. If
`setxunit`	This procedure sets the units on the X-axis of the plot
`setxy`	Use a box cursor to set the x-axis and y-axis scaling or provide
`sety`	Set the y-axis range either directly or with the cursor. If
`show`	This procedure displays a spectral line data container in the plotter.
`showregion`	Procedure to show the regions in !g.regions (baseline regions).
`spurshow`	Using the current displayed data container, mark any VEGAS ADC spurs
`toggleovers`	Toggle the overlays (oshows and gbtoplots) on and off. Use the `/on`
`unzoom`	This procedure unzooms to the full X- and Y-axis ranges.
`vline`	Mark a verticle line at the given x-location. Optionally include a
`write_ascii`	This procedure writes the data in the displayed spectrum to an ASCII
`write_ps`	This procedure writes a postscript file that reproduces the spectrum
`xtochan`	Convert the given x-axis value to channels assuming that the x-axis
`zline`	This procedure toggles a flag to draw a horizontal line on the plot

pro annotate(x, y, text, color=color, charsize=charsize, normal=normal, noshow=noshow)#

This procedure places a text string on the plot

Params:

xin, required, type=float: X position of the string
yin, required, type=float: Y position of the string
textin, required, type=string: The text to write

Keywords:

colorin, optional, type=integer, default=``!g.annotatecolor``: Text color index
charsizein, optional, type=float: character size
normalin, optional, type=boolean: positions are normalized coordinates.
noshowin, optional, type=boolean: Don’t immediately show the new annotation. This is useful if you are stringing several annotations together. It keeps the plotter from updating after each call.

Examples:

annotate,10.5,1.5,'Hello',color=!blue,charsize=2.0

pro bdrop(nchan)#

This procedure is used to specify how many channels at the beginning of the spectrum should be ignored, when plotting. You then avoid the bad autoscaling that can result when the edge of the spectrum contains bad values.

Note that the values are applied in channel space, so depending on whether the plot is shown in channels, frequency, or velocity, a bdrop value may affect the left or right side of the plotted spectrum.

Params:

nchanin, required, type=int: number of channels to drop from the beginning of the plot

Examples:

show       ; show some spectrum with bad channels 
bdrop,10   ; the spectrum is replotted with better scaling
bdrop,0    ; unset the bdrop value

function chantox(chans, type=type, dc=dc)#

Convert the given channels numbers to the x values appropriate for the currently displayed data container and x-axis settings.

Params:

chansin, required, type=array: The channel numbers to convert.

Keywords:

typein, optional, type=integer: The axis array type (0=channels, 1=frequency, 2=velocity). If not supplied, it will use the current x-axis type. When type is not the currently displayed x-axis type, the scaling is to standard SI units (m/s, Hz, and channels).
dcin, optional, type=data container: A data container to use. If not supplied, the most recently plotted (via show) data container is used.

Returns:

The converted channel numbers in the x-axis units currently displayed. If there is a problem (invalid arguments, no data found, etc.) then the returned value is the chans argument.

Examples:

Get the x-axis value at channel 100 for the current plot

a=chantox(100)

Get the frequency at channel 100 for the current plot Note that the units of a depend on what the current x-axis is. If x-axis is frequency, the units (MHz, GHz, Hz) will be the same as that in the current display. If the x-axis is something else, then the units of a will be Hz.

a = chantox(100,type=1)

Get the velocity at channel 100 for a data container at buffer 7.

a = chantox(100,type=2,dc=!g.s[7])

pro clearannotations(noshow=noshow)#

Removes all annotations from the current plot.

Keywords:

noshowin, optional, type=boolean: If set, don’t call reshow here.

pro clearmarks(noshow=noshow)#

Clear all marks (+ plus associated text) from the plotter.

Keywords:

noshowin, optional, type=boolean: Don’t immediately update the plotter. This is useful if you are stringing several plotter calls together. It keeps the plotter from updating after each call.

pro clearoplots(index=index, idstring=idstring)#

Clear any over plots. This removes them from the plotters state and does a reshow.

Under normal use, this will not clear region box overlays if the value of !g.regionboxes is true (1). That behavior can be overridden by specifying the idstring of the region boxes (see showregion), but that is intended for internal use only and is not recommended for general users. Instead, use showregion,/off or set !g.regionboxes to false (0) before calling clearoplots.

Keywords:

indexin, optional, type=integer: The index numbers to clear. This is the index number set by gbtoplot. Note that once an index has been cleared, subsequent index numbers are renumbered appropriately so that index numbers are always 0:(n_indexes-1).
idstringin, optional, type=string: A string that can be used to identify which oplots should be cleared. This is a string that is set by the user when gbtoplot was called. Withing GBTIDL, all internal id strings begin with two underscores so that they are less likely to conflict with user-defined idstrings. When not specified (the default) no checks on idstring are done prior to clearing it from the list.

pro clearvlines(noshow=noshow, idstring=idstring)#

Clear all vertical lines and associated text from the plotter.

Keywords:

noshowin, optional, type=boolean: Don’t immediately update the plotter. This is useful if you are stringing several plotter calls together. It keeps the plotter from updating after each call.
idstringin, optional, type=string: Only clear those vertical lines that match idstring. Default is to clear all vertical lines. An empty string matches all vlines and is equivalent to omitting this idstring keyword.

function click(frame=frame, veldef=veldef, nocrosshair=nocrosshair, noshow=noshow, label=label)#

Get cursor position when the user presses a mouse button. Positions are translated to include channels, frequency, and velocity in the requested reference frame and velocity definition.

The return value is a named structure (cvfstruct) containing the following fields:

x	The x value in the data coordinates.
y	The y value in the data coordinates.
xdevice	The x value in device coordinates.
ydevice	The y value in device coordinates.
button	The button pressed (1=left,2=middle,4=right).
chan	The channel number corresponding to x.frame with the voffset.
velo	The velocity (m/s) corresponding to x in frame using veldef and voffset.
frame	The supplied frame argument, defaults to the current frame in the plotter.
veldef	The veldef argument (velocity definition), defaults to the current velocity definition in the plotter.
voffset	The velocity offset (in frame and veldef) as found in the plotter.
ok	If everything went fine, this is 1, otherwise it’s 0.

Keywords:

framein, optional, type=string: The desired reference frame for the velocity and frequency values. The list of possible choices can be found in the documentation for frame_velocity. This defaults to the frame currently in use in the plotter.
veldefin, optional, type=string: The velocity definition to use in converting the cursor x position. This must be one of OPTICAL, RADIO or TRUE. This defaults to the veldef currently in use in the plotter.
nocrosshairin, optional, type=boolean: When set, this function will ensure that the plotter’s crosshair is on until the click is received. At that point, the plotter’s crosshair will be returned to its state before click was invoked. If not set, the plotters crosshair state will not be changed.
noshowin, optional, type=boolean: If set, then the plotter will not be brought to the foreground (shown).
labelin, optional, type=string: A label to use in the “Left Click:” field of the plotter. Defaults to “Click a Mouse Button”.

Returns:

cfvstruct structure as described above.

Examples:

print,click()
; or
c = click()
v = c.velo ; velocity at frame and velocity definition in header

Uses:

chantofreq chantovel freqtochan

pro crosshair(on=on, off=off)#

This procedure toggles a flag to draw a crosshair cursor. Use the /on or /off keywords to ensure that the crosshair is on or off (otherwise it simply toggles the state).

If both /on and /off are used at the same time, an error message is printed and the state of the zero line is not changed.

Keywords:

onin, optional, type=boolean: Turn the crosshair on.
offin, optional, type=boolean: Turn the corrhair off.

Examples:

crosshair

pro edrop(nchan)#

This procedure is used to specify how many channels at the end of the spectrum should be ignored, when plotting. You then avoid the bad autoscaling that can result when the edge of the spectrum contains bad values.

Note that the values are applied in channel space, so depending on whether the plot is shown in channels, frequency, or velocity, an edrop value may affect the left or right side of the plotted spectrum

Params:

nchanin, required, type=int: number of channels to drop from the end of the plot

Examples:

show       ; show some spectrum with bad channels 
bdrop,10   ;
edrop,10   ; the spectrum is replotted with better scaling
edrop,0    ; unset the edrop value.  bdrop is still in effect.

pro gbtoplot(x, y, color=color, chan=chan, index=index, idstring=idstring)#

Overplots using oplot on to the GBT plotter’s surface. It also remembers the x and y values so that they can be replotted as needed (e.g. the x-axis changes). Overplots, if toggled off, are automatically toggled on by a call to gbtoplot.

Params:

xin, optional, type=numerical vector: The x values to be plotted. If omitted, then x is assumed to be channels starting at 0 and going through n_elements(y) - 1. When supplied, it must have the same number of elements as y. Unless chan is specified, this is assumed to be in the same units as the existing x axis.
yin, required, type=numerical vector: The y values to be plotted.

Keywords:

colorin, optional, type=long integer, default=!g.oplotcolor: The color of the line to be plotted.
chanin, optional, type=boolean: When set, the x axis is assumed to be in channels and a conversion to the existing x axis is necessary to plot them. That conversion is done using the header information of the primary plot (the argument to the most recent show).
indexout, optional, type=integer: Returns the index associated with this oplot. This index can be used to clear this over plot using clearoplots. Note that once an index is cleared, subsequent indexes are renumbered - i.e. there are never any gaps in in index number.
idstringin, optional, type=string: A string that can be used to identify this oplot and thereby group oplots together. This is most useful with clearoplots to remove just those oplots with the same idstring. Withing GBTIDL, all internal id strings begin with two underscores so that they are less likely to conflict with user-defined idstrings. The default is ‘’.

function getxarray(count=count)#

Get the current x-array. Useful so that the caller doesn’t have to know how the plotter has stored this quantity.

Keywords:

countout, optional, type=integer: The number of values. If there is nothing in the plotter, this will be 0 and the returned value will be -1.

Returns:

the current array of x-axis values.

Note:

This is part of a collection of routines that return information found in the gbtplot_common common block. It exists so that users don’t need to include that common block in their code and so that they don’t need to know specifically where that information is in the common block. Developers of the plotter can then feel free to move that information around so long as these functions still return it correctly.

function getyarray(count=count)#

Get the current array of y values. Useful so that the caller doesn’t have to know how the plotter has stored this quantity.

Keywords:

countout, optional, type=integer: The number of values. If there is nothing in the plotter, this will be 0 and the returned value will be -1.

Returns:

the current array of y values.

Note:

This is part of a collection of routines that return information found in the gbtplot_common common block. It exists so that users don’t need to include that common block in their code and so that they don’t need to know specifically where that information is in the common block. Developers of the plotter can then feel free to move that information around so long as these functions still return it correctly.

function getplotterdc(copy=copy)#

Get the current data container. If copy is true, make this a true copy.

If you do not request a true copy then you should not free this data container or change the data values since that will confuse the plotter. If a true copy is returned, you are responsible for calling data_free to free up its pointer when no longer needed.

Useful so that the caller doesn’t have to know how the plotter has stored this quantity.

Keywords:

copyin, optional, type=boolean: When set, return a true copy, which must be freed using free_data when you are finished with it. If not set, do not free.

Returns:

the current data container.

Note:

This is part of a collection of routines that return information found in the gbtplot_common common block. It exists so that users don’t need to include that common block in their code and so that they don’t need to know specifically where that information is in the common block. Developers of the plotter can then feel free to move that information around so long as these functions still return it correctly.

function getxrange(empty=empty)#

Get the current x-range

Keyword:

emptyout, optional, type=boolean: Set to 1 (true) if the plotter is empty.

Returns:

the current x-range

Note:

This is part of a collection of routines that return information found in the gbtplot_common common block. It exists so that users don’t need to include that common block in their code and so that they don’t need to know specifically where that information is in the common block. Developers of the plotter can then feel free to move that information around so long as these functions still return it correctly.

function getyrange(empty=empty)#

Get the current y-range

Keywords:

emptyout, optional, type=boolean: Set to 1 (true) if the plotter is empty.

Returns:

the current y-range

Note:

This is part of a collection of routines that return information found in the gbtplot_common common block. It exists so that users don’t need to include that common block in their code and so that they don’t need to know specifically where that information is in the common block. Developers of the plotter can then feel free to move that information around so long as these functions still return it correctly.

pro histogram(on=on, off=off)#

This procedure toggles a flag to draw the plot in histogram mode. Use the /on or /off keywords to ensure that the histogram plotting is on or off (otherwise it simply toggles the state).

If both /on and /off are used at the same time, an error message is printed and the state of the zero line is not changed.

Keywords:

onin, optional, type=boolean: Turn histogram mode on.
offin, optional, type=boolean: Turn histogram mode off.

Examples:

histogram

pro oplotfn(fnname, params, color=color, index=index, idstring=idstring, noshow=noshow)#

Overplots a function using oplot on to the GBTIDL plotter’s surface. It also remembers the function and parameters so that they can be replotted as needed to the desired screen resolution (e.g. the x-axis changes). Overplots, if toggled off, are automatically toggled on by a call to oplotfn. Overplots include both function calls (set using this function) and simple x,y overplots set using gbtoplot.

The syntax of the function call using the fnname parameter is:

arr = fnname(params, minchan, maxchan, chanperpix, count=count)

where params are exactly as supplied to oplotfn, minchan and maxchan are the current x-axis limits, in channels, and chanperpix is the current number of channels per pixel (that is a double-precision value). Count should be set by fnname to be the total number of points to be plotted. Use that to signal that no points should be plotted for this call (e.g. the x channel range is out of the significant range of the function). The returned value is a 2-D array where arr[0,*] is the set of x-axis values, in channels, and arr[1,*] is the set of y-axis value corresponding to those x-axis values. Typically, the x-axis values would be generated using seq as:

x = seq(minchan, maxchan, chanPerPix)

and then y is generated from x using params and the array of [x,y] is then returned. The returned value (arr) is not examined if count is 0.

Params:

fnnamein, required, type=string: The name of the function to be invoked to generate the values to be plotted (see above).
paramsin, required, type=any: The parameters passed to fnname.

Keywords:

colorin, optional, type=long integer, default=!g.oplotcolor: The color of the line to be plotted.
indexout, optional, type=integer: Returns the index associated with this oplot. This index can be used to clear this over plot using clearoplots. Note that once an index is cleared, subsequent indexes are renumbered - i.e. there are never any gaps in index number.
idstringin, optional, type=string, default=”.”: A string that can be used to identify this oplot and thereby group oplots together. This is most useful with clearoplots to remove just those oplots with the same idstring. Withing GBTIDL, all internal id strings begin with two underscores so that they are less likely to conflict with user-defined idstrings. The default is ‘’.
noshowin, optional, type=boolean, default=unset: When this is set, the function is not immediately displayed. This is useful when you have several graphical commands to issue and you don’t want the plotter to have to replot everything each time. Instead, remember to do a reshow at the end to show everything that has been added. The default behavior is to show the plots immediately.

Examples:

See the source code for gauss_plot_fn for an example function suitable for use by oplotfn.

pro oshow(dc, color=color)#

Plot a data container on top of (over) the current plot. The x-axis will be automatically constructed to match that of the current plot. If the plot is not zoomed, the x and y range will be adjusted to accomodate this data along with all previously plotted data. If overlays are turned off, calling this automatically turns it on.

Params:

dcin, optional, type=data container or integer, default=0: The data container to over plot. If an integer is entered here, it is the global buffer number to over plot. If not specified, the primary (0) data container is used.

Keywords:

colorin, optional, type=color, default=!g.oshowcolor: A color to use when drawing the line.

Examples:

getrec,1   ; retrieve record 1 into !g.s[0]
copy,0,1   ; copy the data container !g.s[0] to !g.s[1]
getrec,2   ; retrieve record 2 into !g.s[0]
show,0     ; show record 2
oshow,1    ; overlay record 1

pro print_ps(filename, portrait=portrait, device=device)#

This procedure prints a postscript file that reproduces the spectrum in the plotter. To save the postscript to a file and not print it use write_ps.

Params:

filenamein, optional, type=string: The postscript filename can be specified using this parameter. If omitted, the file will be called gbtidl.print.file.ps.

Keywords:

devicein, optional, type=string: The name of the printer to use. If not set, this defaults to the value of !g.printer. If !g.printer has zero-length, it falls back to using lp.
portraitin, optional, type=boolean: If set then the postscript will be generated in portrait mode instead of the default landscape mode.

Examples:

print_ps,'myplot.ps',device='ps2',/portrait

Uses:

write_ps

pro setabsrel(absrel)#

This procedure sets the flag that indicates whether the xaxis is in absolute units or relative to the value at the reference channel.

Params:

absrelin, required, type=string: The string that determines the setting of the flag. Recognized values are ‘Abs’ and ‘Rel’. This is case-insensitive.

pro setframe(frame)#

This procedure sets the reference frame to be used in constructing the x-axis prior to displaying the data.

Params:

framein, required, type=string: The reference frame to use. Recognized velocity definitions are the same ones found in the frames menu in the plotter.

pro setmarker(x, y, text=text)#

This procedure sets a marker on the plot at the given location.

Params:

xin, required, type=float: X position in current plotter units
yin, required, type=float: Y position in current plotter units

Keywords:

textin, optional, type=string: text to be associated with the marker. If omitted, the text will represent the x and y positions.

Examples:

setmarker,1420.405,1.3

pro setveldef(veldef)#

This procedure sets the velocity definition to be used in constructing the x-axis prior to displaying the data.

Params:

veldefin, required, type=string: The velocity definition to use. Recognized velocity definitions are ‘Radio’, ‘Optical’, and ‘True’.

pro setvoffset(voffset, veldef=veldef)#

Procedure to set the velocity offset in the plotter, in the current frame.

Params:

voffsetin, optional, type=double: The new velocity offset in km/s. If not supplied it uses the source velocity of the spectrum in the plotter. In that case, the veldef also comes from the spectrum in the plotter and the veldef keyword here is not used. If there is no spectrum in the plotter, it does nothing.
veldefin, optional, type=string: The velocity definition to use. If not set, the current definition in use in the plotter will be used.

pro setx(x1, x2)#

Set the x-axis range either directly or with the cursor. If interacting via the cursor, mouse button 3 aborts out of this function without changing the x-axis range.

Params:

x1in, optional, type=double: Desired minimum x-axis value in the current x-axis units. If not supplied, the cursor will be used to set this.
x2in, optional, type=double: Desired maxiumum x-axis value in the current x-axis units. This must be supplied if x1 has also been supplied.

Note:

If x2 is less than x1, this procedure will reverse them internally before they are used.

pro setxunit(unit, noreshow=noreshow)#

This procedure sets the units on the X-axis of the plot Valid units are Channels, Hz, kHz, MHz, GHz, m/s, and km/s

Params:

unitin, required, type=string: unit

Keywords:

noreshowin, optional, type=boolean: If set, the plotter is not updated with the new units. This is useful if this is embedded in a procedure and you want to delay updating the plotter until several changes have been made. This features is used internally in show_support.

Examples:

get,index=1
show
setxunit,'MHz'

pro setxy(xmin, xmax, ymin, ymax)#

Use a box cursor to set the x-axis and y-axis scaling or provide those values directly.

If there are no arguments, then gbtbox_cursor is used to set the region of interest.

Click Left button to set box bottom right corner.
Drag Left button to move box.
Drag Middle button near a corner to resize box.
Right button when done.

If any one argument is present, they must all be present.

Params:

xminin, optional, type=double: The desired new minimum x value.
xmaxin, optional, type=double: The desired new maximum x value.
yminin, optional, type=double: The desired new minimum y value.
ymaxin, optional, type=double: The desired new maximum y value.

pro sety(y1, y2)#

Set the y-axis range either directly or with the cursor. If interacting via the cursor, mouse button 3 aborts out of this function without changing the y-axis range.

Params:

y1in, optional, type=double: Desired minimum y-axis value in the current y-axis units. If not supplied, the cursor will be used to set this.
y2in, optional, type=double: Desired maxiumum y-axis value in the current y-axis units. This must be supplied if y1 has also been supplied.

Note:

If y2 is less than y1, this procedure will reverse them internally before they are used.

pro show(dc, color=color, defaultx=defaultx, smallheader=smallheader, noheader=noheader)#

This procedure displays a spectral line data container in the plotter. The primary data container is displayed by default. Pass an integer in the dc variable to show one of the other buffers, or pass a data container in the dc parameter explicitly.

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

Keywords:

colorin, optional, type=long integer, default=!g.showcolor: The color for the data to be plotted.
defaultxin, optional, type=boolean: When defaultx is set, the reference frame, velocity definition, and units from the data header in will be used on the x-axis. Otherwise, the current plotter settings are retained.
smallheaderin, optional, type=boolean: When set, only a small, one line header consisting of RA, DEC, source name, and date is placed at the top of the plot. The footer line is displayed when smallheader is set. By default, the full, multi-line header and the single line footer are displayed.

noheaderin, optional, type=boolean: When set, no header information is displayed at the top of the plot or below the x-axis label of the plot (footer). This takes precedence over smallheader. By default, the full, multi-line header and the single line footer are displayed.

Examples:

; a simple use of show:
getrec,1
show

; retrieve some records and place them in global data containers 1-10
for i=1,10 do begin & getrec,i & copy,0,i & end

show,2   ; show the data in buffer 2
show,5   ; show the data in buffer 5
oshow,6  ; overlay the data from buffer 6

pro showregion(off=off)#

Procedure to show the regions in !g.regions (baseline regions).

Previously shown regions are first erased and then the current regions are shown on the plotter as boxes where the y-size of each box it the RMS of the data within that box. You must set the the value of !g.regionboxes to 1 if you want these region boxes to persist when a new spectrum is plotted using show. The default behavior (!g.regionboxes=0) is to clear all overlaid plots, including region boxes, on each use of show.

The idstring used when plotting the boxes is ‘__showregion’. That can be used in gbtoplots to turn off just these regions. Any region that already contains that id string will be removed by this procedure.

Keywords:

offin, optional, type=boolean: If set, the regions are turned off on the plotter and no new regions are drawn. The regions remain set in !g.regions, they are simply not shown in the plotter.

pro spurshow(showcenteradc=showcenteradc)#

Using the current displayed data container, mark any VEGAS ADC spurs associated with it using vertical lines (vline).

If the vegas spur header parameters are invalid or there are no spurs found within the number of channels present in the data then no vertical lines will be drawn.

All of these vertical lines will have the idstring ‘vegas_spur’. They can all be cleared by using clearvlines for that idstring.

Note: Vertical lines are persistent in the GBTIDL plotter. They remain as different data containers are displayed. clearvlines or clear must be used to erase these lines.

This routine always clears all ‘vegas_spur’ vertical lines before it tries to redraw any at the spur locations.

Keywords:

showcenteradcin, optional, type=boolean: When set, the marked spurs will include the center ADC spur. Normally this is unset and the center ADC spur is not marked. The usual sdfits behavior is to replace the data value at the center ADC spur with the average of the two adjacent channels.

pro toggleovers(on=on, off=off)#

Toggle the overlays (oshows and gbtoplots) on and off. Use the /on or /off keywords to ensure that the overlays are either on or off (otherwise it simply toggles the state).

If both /on and /off are used at the same time, an error message is printed and the state of the zero line is not changed.

Keywords:

onin, optional, type=boolean: Turn the overlays on.
offin, optional, type=boolean: Turn the overlays off.

pro unzoom(onestep=onestep)#

This procedure unzooms to the full X- and Y-axis ranges.

Keywords:

onestepin, optional, type=boolean: When set, just unzoom by one level. This is equivalent to pressing the “Unzoom” button on the plotter.

Examples:

unzoom

pro vline(x, label=label, ylabel=ylabel, noshow=noshow, ynorm=ynorm, idstring=idstring)#

Mark a verticle line at the given x-location. Optionally include a label at the same x and the given y-location.

Params:

xin, required, type=float: The x-location to draw the vertical line. In the current x-axis units.

Keywords:

ylabelin, optional, type=float: The y-location to put the optional label text. ylabel is required if label is specified.
labelin, optional, type=string: The label to associate with this vertical line.
noshowin, optional, type=boolean: Don’t immediately show the new vline. This is useful if you are stringing several vline calls together. It keeps the plotter from updating after each call and make the whole operation run faster. Simply call “reshow” when you are ready to show the final result.
ynormin, optional, type=boolean: The y-position for the label is in normalized coordinates when this keyword is set. That means that the label maintains its position relative to the entire y-axis no matter what changes in y-range (zoom) and x-axis.
idstringin, optional, type=string: An string to use to identify this particular vline. This can be used in clearvlines to clear a particular vline or group of vlines having the same idstring. The default is an empty string.

pro write_ascii(filename, brange=brange, erange=erange, prompt=prompt)#

This procedure writes the data in the displayed spectrum to an ASCII file. See the documentation in dcascii for an explanation of the format of the output.

Params:

filenamein, optional, type=string: The filename can be specified using this parameter. If omitted, the file will be called ‘gbtidl.ascii’ unless /prompt is used.

Keywords:

brangein, optional, type=integer, default=0: The beginning of the range to be written, in units of the current plotter X-axis.
erangein, optional, type=integer, default=0: The end of the range to be written, in units of the current plotter X-axis.
promptin, optional, type=boolean: When set, a file chooser dialogue is used to set the file name, even if filename was set as an argument.

Examples:

write_ascii,'mydata.txt'

Uses:

dcascii

pro write_ps(filename, portrait=portrait, prompt=prompt)#

This procedure writes a postscript file that reproduces the spectrum in the plotter. To send the postscript directly to a printer, use print_ps.

Params:

filenamein, optional, type=string: The postscript filename can be specified using this parameter. If omitted, the file will be called ‘gbtidl.ps’ unless /prompt is used.

Keywords:

portraitin, optional, type=boolean: If set then the postscript will be generated in portrait mode instead of the default landscape mode.
promptin, optional, type=boolean: When set, a file chooser dialogue is used to set the file name, even if filename was set as an argument.

Examples:

write_ps,'myplot.ps'

function xtochan(xvalues, dc=dc)#

Convert the given x-axis value to channels assuming that the x-axis values are in the same units and settings of the currently displayed x-axis.

Params:

xvaluesin, required, type=array: The x-axis values to convert.

Keywords:

dcin, optional, type=data container: An alternative data container to use. If not supplied, the most recently plotted (via show) data container is used.

Returns:

The converted channel numbers.

pro zline(on=on, off=off)#

This procedure toggles a flag to draw a horizontal line on the plot at the zero level. Use the /on or /off keywords to ensure that the zero line plot is on or off (otherwise it simply toggles the state).

If both /on and /off are used at the same time, an error message is printed and the state of the zero line is not changed.

Keywords:

onin, optional, type=boolean: Turn the zero line on.
offin, optional, type=boolean: Turn the zero line off.

Examples:

zline