Subsections

# 2. ChIPS Commands

All of the information provided here is available within CIAO and ChIPS from the ahelp system; ahelp -c chips'' returns a list of all the help files relating to ChIPS .

ChIPS also understands the S-Lang programming language; see Chapter 3 for more information.

The following conventions are used for describing the syntax:

• chips> is the ChIPS command-prompt.
• arg is an argument to a command.
• # is an integer argument.
• Brackets - - indicate an optional argument.
• A pipe - | - means or''. By extension, {command_a | command_b } indicates a choice between equivalent commands and {arg_a | arg_b } indicates a choice between different arguments.

Keep in mind that ChIPS commands are not case sensitive and so may be issued in either uppercase or lowercase.

# 2.1 $Must precede any Unix command issued within Sherpa or ChIPS. sherpa>$<arg>
chips> $<arg>  where arg is a Unix command. Alternatively, ! can be used in place of$.

However, the Unix command cd is an exception to this syntax, and must be issued within Sherpa or ChIPS without a preceding $character. The Unix commands ls and pwd are also exceptions to this syntax, and may or may not be issued within Sherpa or ChIPS without a preceding$ character.

Examples:

1. Issue various Unix commands within Sherpa:

sherpa> cd /disks/a/mydata
sherpa> ls
sherpa> pwd
/disks/a/mydata


2. Issue various Unix commands within Sherpa:

sherpa> $more data.dat 0.5 1.80766 1.5 2.21929 2.5 2.64117 3.5 3.10638 4.5 3.51711 5.5 3.74749  3. Use a Unix command to clear the screen: sherpa>$clear


This Unix command will clear the screen.

# 2.2 # | %

Denotes a comment. The symbol % also denotes a comment.

sherpa> {# | %} <arg>

chips> {# | %} <arg>

where <arg> is a comment.


Examples:

1. Issue a comment:


sherpa> # My comment
sherpa> POLY[modela]


2. chips> # My comment
chips> CURVE data/example.dat X 1 Y 2


# 2.3 AXES | AXIS

Specifies the appearance of the bounding box surrounding a drawing area. The command AXIS is equivalent.

chips> [D #] [{AXES | AXIS}] <axesstyle>
chips> [D #] {AXES | AXIS} <color>
chips> [D #] [{AXES | AXIS}] <scale> [<coor>]
chips> [D #] {AXES | AXIS} WIDTH <width_value>


Argument: D #
Description: drawing area number designation
Options: integer number
Default: current drawing area


Argument: <axesstyle>
Description: axes style
Options: FOURAXES - all four axes, with tick marks
TWOAXES - left and bottom axes only, tick marks on both
TWOAXESFRAME - left and bottom axes with tick marks,
right and top axes without ticks
Default: FOURAXES

Argument: <color>
Description: axes color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE, YELLOW
Default: DEFAULT (appears in ChIPS window as white, prints as black)

Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y

Argument: <scale>
Description: axis scale
Options: LINEAR, LOG
Default: LINEAR

Argument: <width_value>
Description: axes thickness
Options: real number
Default: 1.0


For contour and surface plots, the scale cannot be changed; additionally, axesstyle cannot be changed for surface plots. See the CONTOUR and SURFACE commands for further information about plotting 2-D data in ChIPS.

See the TICKS and TICKVALS commands for information on specifying other attributes of the box surrounding the drawing area.

Figure is an illustration of the different axesstyle options.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> AXES CYAN
chips> AXES WIDTH 4.0
chips> AXES TWOAXES
chips> LOG


First, a plot is produced using the CURVE command. The subsequent AXES commands change the axes to the color CYAN, make the lines composing the axes thicker (to the value of 4.0), and change the style to include only the left and bottom axes. The final command switches both the X and Y axes to logarithmic scale.

# 2.4 AXIS | AXES

Specifies the appearance of the bounding box surrounding a drawing area.

See the AXES command, for further information and examples.

# 2.5 BATCH

Turns on/off use of a plotting device.

chips> BATCH {ON | OFF}


By default, BATCH is turned off (use of a plotting device is turned on).

Examples:

1. chips> BATCH ON
chips> CURVE data/example.dat
chips> PRINT POSTFILE batch.myplot.ps


By turning on the BATCH command, use of a plotting device is turned off. This means that when the CURVE command is issued, the plotting device is not opened. The results of the CURVE command (and any other ChIPS commands that are issued) may still be printed to a PostScript file using the PRINT command.

# 2.6 BROWSE | PRISM

Launches the CIAO file-browsing GUI, Prism. The command PRISM is equivalent.

chips> {BROWSE | PRISM} [<filename>]


If a Prism process is already running, issuing this command with the filename specification will utilize the current Prism process. Otherwise, a new Prism process will be invoked.

The Prism GUI will remain open after exiting ChIPS.

# 2.7 C

Defines the current curve.

chips> [D #] C {# [,#, ...] | #:# | ALL}


where # is an integer argument, #:# specifies an inclusive range of curve numbers, and D # may specify the number of the drawing area.

Note that wherever the "C #" is used, the above extended syntax may be utilized to alter multiple curves at once. If a non-existent curve is specified, ChIPS will act on the current curve.

Examples:

1. chips> CURVE data/exampleA.dat
chips> CURVE data/exampleB.dat
chips> SIMPLELINE
chips> LABEL 6.0 50.0 "Curve 1"
chips> LABEL 6.0 5.0 "Curve 2"


The two curves are numbered in the order in which they were plotted. The most recently plotted curve (curve 2) is the current curve. Therefore, SIMPLELINE acts on curve 2, then each curve is labeled.

2. chips> D 1 C 1
chips> SIMPLELINE


Building on the prvious example, the command "D 1 C 1" selects curve 1 as the current curve. The subsequent SIMPLELINE command acts on curve number 1, changing the style to a line.

3. chips> C 2
chips> WIDTH 4.0


The command C 2 defines curve number 2 as the current curve, then the line is changed to have a width of 4.0.

4. chips> C 1,2
chips> BLUE


Both curves are chosen such that the BLUE command acts on both curves. In this example, the following commands would be equivalent to the "C 1,2" command:

chips> C 1:2

chips> C ALL


# 2.8 CLEAR

Removes all plotting objects and creates a new blank drawing area.

chips> CLEAR


The newly-created drawing area is given the number designation 1.

Examples:

1. chips> CLEAR


This command clears the plotting window and restores the drawing area number designation to 1.

# 2.9 COLORSYS

Sets the color system for hardcopy plots.

chips> colorsys <color>


In this context, "hardcopy" refers to both sending the plot directly to a printer and printing it to a postscript file.

Argument: <color>
Description: color system
Options: CMYK, GRAYSCALE, RGB
Default: RGB


CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Unlike most other ChIPS commands, the "colorsys" command modifies the state object. This means that once the color system is changed, the command does not need to be reissued. The current color system may also be determined by checking the state object, as shown in the EXAMPLES section.

Examples:

1. chips> x = [1:10:0.1]
chips> y = sin(x)
chips> () = curve( x, y )
chips> simpleline
chips> red
chips> axes yellow
chips> colorsys grayscale
chips> print postfile gray.ps


A plot is created and a few attributes are modified. The color system is then set to grayscale, and a postscript file is created.

2. chips> print(chips.colorsys)
rgb
chips> colorsys cmyk
chips> print(chips.colorsys)
cmyk


This illustrates that changing the color system on the command line also updates the ChIPS state object field.

# 2.10 CONTOUR

Adds a contour plot to a drawing area.

chips> [D #] CONTOUR <filename>[<virtual_file_syntax>] [LEVELS] <lev1> <lev2> ... <levN>


Argument: D #
Description: drawing area number designation
Options: integer number
Default: current drawing area


Argument: <filename>
Description: name of datafile and path, if necessary.  If the file
contains tabulated data, it must be sorted with row
precedence (see below).  May be filtered data from a
FITS image file, as shown in the EXAMPLES.

Argument: <virtual_file_syntax>
Description: A filtering and/or binning command argument.  The
<virtual_file_syntax> must be surrounded by
quotes (" ").


Argument: <lev1> <lev2> ... <levN>
Description: numbers specifying Z axis values of each contour level
Options: real numbers
Description: the <lev1> value specifies the Z axis data value of
the first contour line, <lev2> specifies the value
of the second contour line, and so on.


See the LEVELS command for information on setting the levels in the current contour plot.

Contour plots are considered variants of curves, and therefore the attributes of contours (color, linestyle, scale, width) may be changed in the same manner. However, the limits of the x and y axes in a contour plot cannot be modified.

New functionality for plotting contours was added to ChIPS in CIAO 3.0 via the "chips.mingridsize" state object field; see the "Plotting contours" section of "ahelp chips" for more information.

SORTING THE INPUT DATA

The input data file must be sorted with row precedence. For example, the following data:

1 1 1
2 1 -4.97206e-24
3 1 2
4 1 1
5 1 2
1 2 -6.79138e-24
2 2 -2.23247e-23
3 2 1
4 2 -2.1879e-22
5 2 1


Would have to be re-ordered for use in ChIPS:

1 1 1
1 2 -6.79138e-24
2 1 -4.97206e-24
2 2 -2.23247e-23
3 1 2
3 2 1
4 1 1
4 2 -2.1879e-22
5 1 2
5 2 1


Examples:

1. chips> CONTOUR data/sorted.dat 2 4 20


Plots the ASCII data file data/sorted.dat as a contour plot, with the first contour line at a Z-axis value of 2, the second at a value of 4, and the third at a value of 20.

2. chips> CONTOUR data/exampleImage.fits[10:100,10:100] 2 4 20


Plots the data in the specified ranges from the FITS file. The Z-axis values are the same as in Example 1.

3. chips> C 1 DEL
You have no more curves in this drawing area.
chips> CONTOUR "data/sorted.fits[cols col1, col2, col3]" 2 4 20
chips> C 1 WIDTH 4.0


The existing curve is deleted before the data in the first three columns of data/sorted.fits is plotted; the same Z-axis values as before are used. The final command changes the contour curve to a thicker width.

4. chips> CONTOUR s3_img.fits 10 20 30


A contour plot is created from the filtered data stored in "s3_img.fits".

5. chips> CONTOUR data/data3D.dat 40 50 60
chips> C 1 DOT
chips> CONTOUR data/data3D.dat 70 80 90
chips> C 2 LONGDASH


Two contour curves are plotted with different Z-axis values. The linestyle of each is changed so that the levels may be differentiated.

# 2.11 CURVE | PLOT

Plots a curve or change its attributes (PLOT is equivalent).

chips> CURVE <filename> # # #
chips> PLOT <filename> # # #

chips> CURVE <filename> [X #] [Y #] \
[{XERR # | XUP # | XDOWN # | XDN #}] \
[{E # | YERR # | YUP # | YDOWN # | YDN #}] \
[SCOL #]
chips> PLOT <filename> [X #] [Y #] \
[{XERR # | XUP # | XDOWN # | XDN #}] \
[{E # | YERR # | YUP # | YDOWN # | YDN #}] \
[SCOL #]

() = curve( x, y );
() = curve( x, y, yerr );
() = curve( x, y, yerrlo, yerrhi );
() = curve( x, y, xerrlo, xerrhi, yerrlo, yerrhi );


When used to plot data from a file CURVE and PLOT are synonyms but curve() is the only valid S-Lang function name.

## 2.11.1 Plotting data from a file

The CURVE command is used to plot data from either an ASCII data file or a FITS table file.

If you are only plotting x against y values - i.e. no errors - then you just need to specify the columns using the Data Model column filtering syntax (see "ahelp dmcols"). So

  chips> curve "lc.fits[cols time,rate]"


plots the rate column (Y axis) against the time column (X axis). For an ASCII file this would just be

chips> curve lc.dat


To include error bars you need to specify - after the filename - which columns contain the error information. If only symmetric errors on the Y axis are required then the simplest way is to say

chips> curve lc.fits 1 3 5


- which means that the X and Y columns are taken from the first and third column of lc.fits and the error on the Y value is taken from the fifth column. This can also be written as

  chips> curve lc.fits x 1 y 3 e 5


where we explicitly include the type for each column. If the X and Y columns are the first two columns in the file then this can be shortened to

chips> curve lc.fits e 5


(yerr can be used instead of e).

For non-symmetric Y errors, use the YUP and YDOWN (or YDN) labels to give the the number of the columns containing the low and high error values. The XERR, XUP, and XDOWN (or XDN) labels indicate the numbers of the columns which contain errors for the X axis.

The SCOL label is used to indicate the column from which the symbol type for each element is found. This column must be an integer and the values are discussed below.

## 2.11.2 Plotting data from S-Lang

The S-Lang function "curve()" can be used to plot two arrays against each other. So,

  variable x = [0:10:0.01];
() = curve( x, sin(x) );


draws sin(x) for all points between 0 and 10 with a step-size of 0.01. As shown in the SYNTAX section above, the curve() command can also plot Y errors (symmetric or non-symmetric) and for the X axis too (although if X errors are given then the YERRLO, YERRHI, XERRLO, and XERRHI values must be given). So,

  variable x = [1:20];
() = curve( x, x+2, sqrt(x+2) );


plots up a set of points with symmetric Y errors.

The curve() functions returns 0 on success, -1 on error. In the examples above we use "() " to ignore this return value.

## 2.11.3 Changing how the plot looks

Whether a curve has been created from a file using the ChIPS CURVE command, or created from S-Lang using the curve() function, the same set of commands can be used to change its attributes.

Firstly, all curves are created with their attributes set to the values given in the ChIPS state object. Therefore, setting

  chips.symbolstyle = _chips->square;


(whether in the ChIPS resource file or at the ChIPS prompt) will cause any new curves to be drawn using an open square for the sybol. Note that this will not change the attributes of curves that have already been drawn.

Secondly, the CURVE command can be used to change the attributes of a curve that has already been drawn. Each of the following commands can be preceeded by one - or both - of D # and C # to select the curve you wish to change. See "ahelp d" and "ahelp c" for more information on these two commands.

chips> [{CURVE | PLOT}] <color>
chips> [{CURVE | PLOT}] <curvestyle>
chips> [{CURVE | PLOT}] <linestyle>
chips> [{CURVE | PLOT}] SCALE [<coor>] <scale_value>
chips> [{CURVE | PLOT}] WIDTH <width_value>
chips> ERRS [<coor>] <color>
chips> ERRS [<coor>] <errorstyle>
chips> ERRS [<coor>] <errortype>
chips> ERRS [<coor>] <linestyle>
chips> ERRS [<coor>] {ABSOLUTE | RELATIVE}
chips> ERRS [<coor>] SIZE <errortick_size_value>
chips> SYMBOL <color>
chips> SYMBOL <symbolstyle>
chips> SYMBOL [SIZE] <symbol_size_value>


A description of the various arguments used in these calls can be found in the "ARGUMENT LIST" section at the end of this document.

## 2.11.4 Plotting Multiple Curves

Multiple curves may be plotted within the same drawing area. The limits of the drawing area are affected by the {CURVE PLOT} command as follows:

When the first curve is added, the limits of the drawing area are automatically sized to fit.

When each subsequent curve is added, ChIPS automatically changes the limits of the drawing area. If the range and domain of the new curve overlaps with the range and domain of the current drawing area, the drawing area is resized, using as new limits the smallest minimum and the largest maximum values. If either the range or the domain of the new curve do not overlap with the range or domain of the current drawing area, the limits are set to display the new curve, and a warning message is given to indicate that the drawing area limits were changed significantly.

This automatic calculation of the plot limits can be stopped by using the LIMITS command to set the axis ranges to fixed values.

ChIPS converts double-precision numbers to floating-point values before plotting them, which can cause problems for values that are either too large or too small. The allowed range is approximately 1e-38 to 3e38 (for both positive and negative values).

## 2.11.5 Interrupting a Plot

Note that ChIPS does not recognize "CTRL-C" as an interrupt command. There is no way to cancel the drawing of a long plot once it has begun.

Examples:

1. chips> CURVE "lc.fits[cols time,rate]"


Here we plot the rate versus time columns from the FITS file "lc.fits". The Data model column filter "cols time,rate" is used to select the X and Y columns for the plot (since we do not explicitly set them they default to the first two columns in the file). The following commands are equivalent:

chips> D 1 CURVE "lc.fits[cols time,rate]"
chips> CURVE "lc.fits[cols time,rate]" X 1 Y 2


2. chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> SYMBOL SQUARE


First we remove any existing data from ChIPS with the CLEAR command, otherwise the new data would be overplotted on any existing data. The data is ploted as in the previous example except that we then change the symbol to be a square.

3. chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> SYMBOL SQUARE
chips> SYMBOL RED


This changes the symbol type to a red square.

4. chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> SIMPLELINE
chips> SYMBOL NONE


The default behaviour for CURVE is to draw symbols at each point. Here we change it to drawing lines between each point and then remove the symbols.

5. chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> SIMPLELINE
chips> RED


Here we draw a red line between the points but leave the symbol. Note that the symbol color has not been changed to red: this would be done by saying

  chips> SYMBOL RED


6. chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> STEP
chips> RED
chips> SYMBOL YELLOW


There are two ways that points can be connected by lines: SIMPLELINE draws lines between the points whereas STEP (or its alias HIST) considers the data points to represent a histogram (the X values give the center of each bin).

The line color is changed to red and the symbol color is changed to yellow.

7. chips> REDRAW OFF
chips> CLEAR
chips> CURVE "lc.fits[cols time,rate]"
chips> STEP
chips> RED
chips> SYMBOL YELLOW
chips> REDRAW ON


This has the same result as the previous example except that the plot is not changed until the REDRAW ON command is called. See "ahelp redraw" for more information.

8. chips> CLEAR
chips> chips.curvestyle = _chips->step
chips> chips.curvecolor = _chips->red
chips> chips.symbolcolor = _chips->yellow
chips> CURVE "lc.fits[cols time,rate]"


The previous examples all used the CURVE command to change the attributes of an existing plot. The ChIPS state object (see "ahelp chips") provides a way of setting the attributes for any new plots. With the above commands the result is the same plot as previous (a set of points connected as if a histogram with a red line and yellow symbols). The difference is that if another curve is plotted it will also be drawn with the same settings.

9. chips> chips_clear
chips> () = curve(lc.time,lc.rate)
chips> STEP
chips> RED
chips> SYMBOL YELLOW


Here we have read in the contents of "lc.fits" using the Varmm function readfile (see "ahelp readfile") and have used the S-Lang function curve() to plot the time and rate columns of the file. Once the curve has been created it can be manipulated as any other curve.

10. chips> chips_clear
chips> chips.curvestyle = _chips->step
chips> chips.curvecolor = _chips->red
chips> chips.symbolcolor = _chips->yellow
chips> () = curve(lc.time,lc.rate)


The curve() command also follows the settings of the ChIPS state object when creating the plot.

11. chips> CURVE data/exampleB.dat


Plots the ASCII data file data/exampleB.dat using the default settings, where column 1 is Xx and column 2 is y. The following commands are equivalent:

chips> D 1 CURVE data/exampleB.dat
chips> CURVE data/exampleB.dat X 1 Y 2


12. chips> CURVE "data/exampleB.fits[cols col1,col2]"


The virtual_file_syntax argument is used to plot columns col1 and col2 from a FITS file. Again, the default setting are used, i.e. the first column listed in the DM filter (col1) is x and the second (col2) is y. The following commands are equivalent:

chips> D 1 CURVE "data/exampleB.fits[cols col1,col2]"
chips> CURVE "data/exampleB.fits[cols col1,col2]" X 1 Y 2


13. chips> CURVE "data/exampleB.fits[cols col1,col2,col6]" 1 2 3


Columns named col1, col2, and col6 are plotted from the FITS data file data/exampleB.fits. The first column listed in the DM filter is x, the second is y, and the third is the symmetric error bar in y. The following commands are equivalent:

chips> D 1 CURVE "data/exampleB.fits[cols col1,col2,col6]" 1 2 3
chips> CURVE "data/exampleB.fits[cols col1,col2,col6]" X 1 Y 2 E 3
chips> CURVE "data/exampleB.fits[cols col1,col2,col6]" X 1 Y 2 YERR 3


14. chips> CURVE data/exampleB.dat X 1 Y 2 YUP 7 YDOWN 8


The ASCII data file data/exampleB.dat is plotted, with column 1 as x, column 2 as y, column 7 as the positive error in y, and column 8 as the negative error in y. The following commands are equivalent:

chips> D 1 CURVE data/exampleB.dat X 1 Y 2 YUP 7 YDOWN 8
chips> CURVE data/exampleB.dat YUP 7 YDOWN 8


15. chips> CURVE "data.fits[cols col1, col2, col7, col8]" X 1 Y 2
YUP 3 YDOWN 4


The same as the previous example, but the data is read from a FITS file. The following commands are equivalent:

chips> D 1 CURVE "data.fits[cols col1, col2, col7, col8]" X 1 Y 2
YUP 3 YDOWN 4
chips> CURVE "data.fits[cols col1, col2, col7, col8]" YUP 3 YDOWN 4


16. chips> CURVE data/exampleB.dat X 1 Y 2 XUP 4 XDOWN 5 YERR 6


This command plots x, y, the positive and negative errors in x, and the symmetric error in y. The following commands are equivalent:

chips> D 1 CURVE data/exampleB.dat X 1 Y 2 XUP 4 XDOWN 5 YERR 6
chips> CURVE data/exampleB.dat XUP 4 XDOWN 5 YERR 6


17. chips> CURVE data/exampleA.dat
chips> CURVE data/exampleB.dat


Two curves are plotted and numbered 1 and 2, respectively.

18. chips> C 1 DEL
You have no more curves in this drawing area.
chips> CURVE data/exampleB.dat 1 2 6


An existing curve is deleted before the ASCII data is plotted; column 1 is x, column 2 is y, column 6 is the symmetric error bar in Y. The following commands are equivalent:

chips> D 1 CURVE data/exampleB.dat 1 2 6
chips> CURVE data/exampleB.dat X 1 Y 2 E 6
chips> CURVE data/exampleB.dat X 1 Y 2 YERR 6


19. chips> CURVE data/exampleB.dat
chips> D 1 C 1 CURVE HISTO


A single curve is plotted and the curve style is changed to histogram. The following commands are equivalent:

chips> C 1 CURVE HISTO
chips> CURVE HISTO
chips> PLOT HISTO
chips> HISTO


20. chips> LONGDASH
chips> WIDTH 4.0
chips> RED
chips> SYMBOL UPTRI
chips> SYMBOL BLUE
chips> SYMBOL SIZE 5.0


Building on the previous example, various attributes to the curve are modified. The histogram line is changed from to a wide (width 4) line of long dashes. RED changes the color of the curve line, and the three SYMBOL commands change the type, color, and size of the plot symbols.

21. chips> C 1 DEL
You have no more curves in this drawing area.
chips> CURVE data/exampleB.dat 1 2 6
chips> ERRS BAR


All existing curves are removed, then data with symmetric Y-axis error bars is plotted. The final command modifies these error bars such that they do not have ticks on the top or bottom of the bars.

22. chips> CURVE data/exampleB.dat X 1 Y 2 XUP 4 XDOWN 5 YUP 7 YDOWN 8
chips> ERRS X UP
chips> ERRS X BAR


Data is plotted with asymmetric x- and y-axis error bars. The command ERRS X UP causes only the positive x errorbars to be plotted. Then the errors are changed so that they do not have ticks on the top or bottom of the bars.

23. chips> CURVE data/exampleA.dat
chips> CURVE DATA data/exampleA.dat YUP 5 YDOWN 6
chips> CURVE data/exampleB.dat
chips> CLEAR


The first CURVE command adds curve number 1 to the drawing area, from file data/exampleA.dat. The CURVE DATA command alters the curve so that it includes error bars from the same file. The third command adds curve number 2 to the drawing area, from file data/exampleB.dat. All plotting objects are then deleted, creating a new blank drawing area.

24. chips> CURVE data/exampleB.dat X 1 Y 2 YERR 6
chips> D 1 CURVE DATA data/exampleB.dat X 1 Y 2 YUP 7 YDOWN 8


X, y, and symmetric y errors are plotted from an ASCII data file. The curve is then altered to have separate positive and negative y errors plotted.

## 2.11.6 ARGUMENT LIST

The CURVE command (the ChIPS command not the S-Lang function) can take many arguments:

  chips> [D #] [C #] {CURVE | PLOT} DATA <filename> \
[X #] [Y #]} [{XERR # | XUP # | XDOWN # | XDN #} \
[{E # | YERR # | YUP # | YDOWN # | YDN #} [SCOL #]


The filename can include the path to the file (either relative or absolute) and - if a FITS file - any virtual file syntax as described in "ahelp dmsyntax". If a Data Model filter is used (i.e. something within "") then the whole file name has to be enclosed in "" characters.

	Argument: ABSOLUTE or ABS
Description: errors are not relative to the data value,
they are plotted as absolute values
Default: RELATIVE

	Argument: <color>
Description: Color of the axes
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE, YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

	Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y

	Argument: <curvestyle>
Description: style of curve
Options: NOLINE - no connecting line between data points,
SIMPLELINE - line connecting data points,
STEP - stepped connection between data points (alias for HISTO)
Default: NOLINE

	Argument: E #
Options: column number for the symmetric error on y
Default: integer numbers

	Argument: <errorstyle>
Description: style for errorbars
Options: STANDARD - errorbar with top and bottom ticks,
BAR - errorbar only (no ticks on top or bottom)
Default: STANDARD

	Argument: <errortick_size_value>
Description: size of top and bottom errorbar ticks
Options: real numbers
Default: 3.0

	Argument: <errortype>
Description: type of errorbars
Options: BOTH - both positive and negative errorbars,
NONE - no error bars,
UP - positive errorbar only,
{DOWN | DN} - negative errorbar only
Default: BOTH

	Argument: <linestyle>
Description: style for lines
Options: SOLID, DOT, DASH, LONGDASH, DOTDASH, DOTLONGDASH, DASHLONGDASH
Default: SOLID

	Argument: {RELATIVE | REL}
Options: errors are relative to the data value
Default: RELATIVE

	Argument: <scale_value>
Description: plot scaling factor
Options: real numbers
Default: 1.0

	Argument: SCOL #
Options: column number for the symbol specification
Default: integer numbers (see below for list)

	Argument: <symbol_size_value>
Description: size of symbols factor
Options: real numbers
Default: 3.0

	Argument: <symbolstyle>
Description: style for symbols
Options: BLOCK, CIRCLE, CROSS, DIAMOND, SOLIDDIAMOND, DOWNTRI,
SOLIDDOWNTRI, UPTRI, SOLIDUPTRI, SQUARE, POINT, BIGPOINT,
NONE
Default: CROSS

	Argument: <width_value>
Description: curve thickness
Options: real numbers
Default: 1.0

	Argument: X #
Description: column number for the X axis
Options: integer numbers
Default: X 1

	Argument: XERR #
Description: column number for the symmetric error on x
Options: integer numbers

	Argument: XUP #
Description: column number for the positive error on x
Default: integer numbers

	Argument: {XDOWN | XDN} #
Description: column number for the negative error on x
Options: integer numbers

	Argument: Y #
Description: column number for the Y axis
Options: integer numbers
Default: Y 2

	Argument: YERR #
Description: column number for the symmetric error on y
Options: integer numbers

	Argument: YUP #
Description: column number for the positive error on y
Options: integer numbers

	Argument: {YDOWN | YDN} #
Description: column number for the negative error on y
Options: integer numbers


## 2.11.7 SCOL values

The following table lists the possible values for the SCOL column.

 Value Symbol type 1 - 19 dot 20 - 29 horizontal dash 30 open triangle 31 inverted Y 32 starred triangle 33 solid triangle 40 open square 41 X 42 starred square 43 solid square AB The two-digit number AB means that the symbol (a polygon) has A sides and that these sides should be connected according the the value of B: 0open, 1skeletal, 2starred, and 3solid. No symbol will be produced if B is greater than 3.

# 2.12 D

Defines the current drawing area.

chips> D {# [,#, ...] | #:# | ALL}


where # is an integer argument specifying drawing area number, and #:# specifies an inclusive range of drawing area numbers.

Note that wherever the "D #" is used, the above extended syntax may be utilized to alter multiple drawing areas at once. If a non-existent drawing area is specified, ChIPS will act on the current drawing area.

Examples:

1. chips> SPLIT 2
chips> SPLIT GAP 0.04
chips> D 1 CURVE data/exampleA.dat
chips> D 2 CURVE data/exampleB.dat
chips> TWOAXESFRAME


The drawing area is first divided into two parts and and separated by a small amount (0.04). The first curve is plotted in drawing area 1, and the second in drawing area 2. Drawing area 2 is now the current drawing area, since it is the most recently created. The command TWOAXESFRAME acts on the current drawing area, changing the style of the axes.

2. chips> D 2
chips> TICKS X 10.0


First, drawing area number is defined as the the current drawing area. The TICKS X 10.0 command acts on drawing area number 2, changing the tick spacing to units of 10.

3. chips> D 1,2
chips> AXES BLUE


"D 1,2" defines drawing areas 1 and 2 as the current drawing areas, so that the following AXES BLUE command acts on both of them. The following commands are equivalent:

chips> D 1:2 AXES BLUE
chips> D ALL AXES BLUE


4. chips> SPLIT 3
chips> SPLIT GAP 0.1
chips> D 1 CURVE data/exampleA.dat
chips> D 2 CURVE data/exampleB.dat
chips> D 3 CURVE data/example.dat
chips> D ALL LIMITS X 0 20


Three drawing areas are created with a large separation between them. A separate curve is plotted in each area, then they are all set to have the same X-axis limits.

# 2.13 DELETE

Deletes plotting objects (drawing area, curves, lines and labels) from a plot.

chips> [D #] [C #] [LN #] [L #] DELETE
chips> DELETE [DRAWAREA] [#]


The first command deletes various plotting objects within a drawing area. To remove the entire drawing area and its contents, use the second command.

Argument: D #
Description: drawing area number designation
Options: integer number


Argument: C #
Description: curve number designation
Options: integer number


Argument: LN #
Description: line number designation
Options: integer number

Argument: L #
Description: label number designation
Options: integer number


Note that if a non-existent plotting object is specified, ChIPS will act on the current plotting object.

The PACK command controls how plotting objects are renumbered after deletions are made.

Examples:

1. chips> SPLIT 2
chips> SPLIT GAP 0.05
chips> D 1 CURVE data/exampleA.dat
chips> D 1 CURVE data/exampleB.dat
chips> D 1 LABEL 2.0 60.0 "Drawing Area 1"
chips> D 1 LABEL 2.0 20.0 "Curve 1"
chips> D 1 LABEL 5.5 10.0 "Curve 2"
chips> D 2 CURVE data/exampleB.dat
chips> D 2 LABEL 2.0 3.4 "Drawing Area 2"
chips> D 1 C 2 DELETE
Your new Current Curve number is: 1
chips> D 1 L 3 DELETE
Your new Current Label number is: 2
chips> D 2 DELETE
Your new Current Draw Area number is: 1


The drawing area is first divided into two parts. Three curves are plotted - two in drawing area 1 and one in drawing area 2 - and labeled. The command D 1 C 2 DELETE deletes the second curve that was plotted in drawing area number 1; the next DELETE command deletes the label for that curve. The final command removes drawing area number 2 enitrely.

2. chips> CLEAR
chips> CURVE data/exampleA.dat
chips> LABEL 4.0 5.0 "Label 1"
chips> LABEL 2.0 40.0 "Label 2"
chips> LABEL 4.0 60.0 "Label 3"
chips> LABEL 3.0 20.0 "Label 4"
chips> L 2,4 DELETE
Your new Current Label number is: 2
chips> L 2:4 DELETE
Your new Current Label number is: 1


A single curve is plotted and four labels are created. The command L 2,4 DELETE deletes label numbers 2 and 4. By default, renumbering of plotting objects is turned on, so the remaining labels are renumbered as 1 and 2. Issuing L 2:4 DELETE deletes any labels numbered 2 through 4, i.e. "Label 3" is deleted.

3. chips> CURVE data/exampleA.dat
chips> LABEL 4.0 5.0 "Label 1"
chips> LABEL 2.0 40.0 "Label 2"
chips> L 2 DEL
Your new Current Label number is: 1
chips> L 2 SIZE 4.0


A curve is plotted and two labels are created. The L 2 DEL command removes label number 2 (i.e. "Label 2"). Since there is no longer a label number 2 upon which to act, the L 2 SIZE 4.0 command is slightly misleading; this command will act on label number 1, as explained in the DESCRIPTION.

# 2.14 DISPLAY

Causes the specified 2-D data to be displayed, using the default imaging display tool (i.e. ds9)

chips> DISPLAY <filename>


The filename is the name of an image data file, and may include a directory path. Currently, only 2-D FITS images are supported.

Examples:

1. chips> DISPLAY data/example_img.fits


Displays the image contained in data/example_img.fits.

# 2.15 DRAWAREA

Specifies the location for a new drawing area.

chips> DRAWAREA <x1> <x2> <y1> <y2>


Argument: <x1>
Description: X coordinate of lower left corner
Options: real numbers between 0.0 and 1.0

Argument: <x2>
Description: X coordinate of upper right corner
Options: real numbers between 0.0 and 1.0

Argument: <y1>
Description: Y coordinate of lower left corner
Options: real numbers between 0.0 and 1.0

Argument: <y2>
Description: Y coordinate of upper right corner
Options: real numbers between 0.0 and 1.0


Examples:

1. chips> DRAWAREA 0.25 0.9 0.5 0.9
chips> D 1 CURVE data/example.dat


The drawing area location is set and then a curve is plotted.

# 2.16 ERRS

Specifies the appearance of errorbars.

chips> [D #] [C #] ERRS [<coor>] <color>
chips> [D #] [C #] ERRS [<coor>] <errorstyle>
chips> [D #] [C #] ERRS [<coor>] <errortype>
chips> [D #] [C #] ERRS [<coor>] <linestyle>
chips> [D #] [C #] ERRS [<coor>] {ABSOLUTE | RELATIVE}
chips> [D #] [C #] ERRS [<coor>] SIZE <errortick_size_value>


Argument: {ABSOLUTE | ABS}
Description: errors are not relative to the data value; instead
they are plotted as absolute values
Default: RELATIVE

Argument: C #
Description: curve number designation
Options: integer numbers
Default: current curve


Argument: <color>
Description: axes color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED,  WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <errorstyle>
Description: sytle for errorbars
Options: STANDARD - errorbar with top and bottom ticks
BAR - errorbar only, no ticks on top or bottom
Default: STANDARD

Argument: <errortype>
Description: type of errorbars
Options: BOTH - both positive and negative errorbars
NONE - no error bars
UP - positive errorbar only
{DOWN | DN} - negative errorbar only
Default: BOTH

Argument: <errortick_size_value>
Description: size of top and bottom errorbar ticks
Options: real numbers
Default: 3.0

Argument: <linestyle>
Description: style for lines
Options: SOLID, DOT, DASH, LONGDASH, DOTDASH, DOTLONGDASH,
DASHLONGDASH
Default: SOLID

Argument: {RELATIVE | REL}
Description: errors are relative to the data value
Default: RELATIVE


The command:

chips> [D #] [C #] ERRS [<coor>] {ABSOLUTE | RELATIVE}


affects all subsequent plots, not just the existing plot.

Figure is an illustration of the different errortype options. Figure is an illustration of the different errorstyle options.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> SPLIT 2
chips> D 1 CURVE data/exampleA.dat YUP 5 YDOWN 6
chips> D 1 CURVE data/exampleB.dat YUP 7 YDOWN 8
chips> D 2 CURVE data/exampleA.dat XUP 3 XDOWN 3
chips> D 2 CURVE data/exampleB.dat XUP 4 XDOWN 5
chips> D 2 C 1 ERRS X UP
chips> D 2 C 1 ERRS BAR


Two curves with Y error bars are plotted in drawing area number 1, and two curves are plotted in drawing area number 2 with X error bars. The error bars for curve 1 of drawing area 2 are then changed to be positive error bars only, having no tick marks on the tops or bottoms of the bars.

2. chips> D 1 C 1 ERRS Y UP
chips> D 1 C 1 ERRS BAR


Building on the previous example, the Y error bars plotted in drawing area 1 for curve 1 are modified.

3. chips> ERRS ABS
chips> D 1 CURVE data/exampleA.dat YUP 5 YDOWN 6
chips> ERRS REL
chips> D 1 CURVE data/exampleAa.dat YUP 5 YDOWN 6


The first CURVE command is preceded by the ERRS ABS command, which will set all errors to be plotted as absolute (instead of relative) to the data points. The second CURVE command is preceded by the ERRS REL command, which will set all errors to plotted as relative to the data.

# 2.17 EXIT | QUIT

Terminates the program. The command QUIT is equivalent.

chips> EXIT
chips> QUIT


Examples:

1. chips> EXIT
unix%


ChIPS has been closed, returning the user to the unix prompt.

# 2.18 FONT

Changes the default global font.

chips> FONT <font>


Argument: <font>
Description: font type designation
Options: {GREEK | GR} (Greek), {ITALIC | IT} (Italic),
{OLDENGLISH | OE} (Old English), {ROMAN | RM} (Roman),
{TINY | TI} (Tiny)
Default: ROMAN


This command affects all drawing areas.

The text argument of the commands LABEL, XLABEL, YLABEL, ZLABEL, and TITLE may contain TeX syntax for formatting text and creating mathematical expressions. This TeX syntax may include mixed font settings, as shown in one of the EXAMPLES.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> XLABEL "X-axis"
chips> YLABEL "Y-axis"
chips> TITLE "Title"
chips> LABEL 2.0 2.5 "Plot label"
chips> XLABEL SIZE 2.0
chips> YLABEL SIZE 2.0
chips> TITLE SIZE 2.0
chips> LABEL SIZE 2.0
chips> FONT GR
chips> FONT RM


After creating a plot and adding labels and a title, the global font is changed first to Greek. The final command changes the global font back to the default Roman. The following commands are equivalent when changing fonts:

chips> FONT GREEK
chips> FONT ROMAN


2. chips> D 1 LABEL 2.0 50.0 "\oe This \rm is \gr Greek"


This LABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

# 2.19 GRIDS

Adds grid lines to a drawing area and/or changes grid attributes.

chips> [D #] GRIDS [<gridtype>] <color>
chips> [D #] GRIDS [<gridtype>] [<coor>] <boolean>
chips> [D #] GRIDS [<gridtype>] <linestyle>


Argument: <boolean>
Description: drawing area grids on or off
Options: {ON | OFF}
Default: ON

Argument: <color>
Description: axes color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE, YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <gridtype>
Description: type of grid markings
Options: MAJ - grid lines along major tick marks
MIN - grid lines along minor tick marks
Default: both MAJ and MIN

Argument: <linestyle>
Description: style for lines
Options: SOLID, DOT, DASH, LONGDASH, DOTDASH, DOTLONGDASH,
DASHLONGDASH
Default: SOLID


CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> GRIDS ON


A curve is plotted, then the grid lines are turned on.

2. chips> GRIDS MAJ Y ON
chips> GRIDS MIN X ON


Grid lines along the major Y-axis tick marks are turned on, while the lines along the minor X-axis tick marks are turned on.

3. chips> GRIDS MAJ BLUE
chips> GRIDS MIN CYAN
chips> GRIDS LONGDASH


The major tick marks are changed to the color blue, and the minor tick marks are changed to the color cyan. Finally, all grid line styles are changed from a solid line to a long dash.

# 2.20 INFO

Prints summary information about the current plotting objects.

chips> INFO


Examples:

1. chips> CURVE data/example.dat
chips> GRIDS ON
chips> AXES YELLOW
chips> INFO

Drawing Area  #1  << CURRENT DRAWING AREA
(Location: 0.15 0.9 0.1 0.9)
(Limits  : -0.45 20.45 0.915761 3.99156)
(Axes    :  fouraxes   color: yellow  width: 1)
Curve #1  /data/example.dat
SYMBOL: defaultcolor  cross
CONNECTOR: noline << CURRENT CURVE


A plot is created and some of the attributes are modified. The plot summary is then printed with the INFO command.

# 2.21 L

Defines the current label.

chips> [D #] L {# [,#, ...] | #:# | ALL}


where # is an integer argument and #:# specifies an inclusive range of label numbers.

If a non-existent label is specified, ChIPS will act on the current label.

Examples:

1. chips> CURVE data/exampleA.dat
chips> CURVE data/exampleB.dat
chips> LABEL 5.0 40.0 "Curve 1"
chips> LABEL 5.0 5.0 "Curve 2"
chips> LABEL YELLOW


Two curves are plotted and labeled; The first label ("Curve 1") is label number 1 and the second label is number 2. Label number 2 is also the current label, since it was most recently created. The command LABEL YELLOW acts on the current label (2), changing the color to yellow.

2. chips> D 1 L 1
chips> LABEL BLUE


The command D 1 L 1 defines label number 1 as the current label, so that the command LABEL BLUE changes the color.

3. chips> L 2
chips> LABEL SIZE 2.4


Label 2 is defined as the current label, then the size is changed to 2.4.

# 2.22 LABEL

Adds a label to a drawing area and/or changes label attributes.

chips> [D #] LABEL <xcoor> <ycoor> "<text>"


To change label attributes:

chips> [D #] {L # | LABEL} "<text>"
chips> [D #] L # <xcoor> <ycoor>
chips> [D #] {L # | LABEL} ANGLE <rot_angle>
chips> [D #] {L # | LABEL} <color>
chips> [D #] {L # | LABEL} SIZE <size_value>


The LABEL command can take many arguments:

Argument: <color>
Description: label color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE, YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: L #
Description: label number designation
Options: integer numbers
Default: current label

Argument: <rot_angle>
Description: rotation angle in degrees
Options: real numbers
Default: 0.0

Argument: <size_value>
Description: label size
Options: real numbers
Default: 1.0

Argument: <text>
Description: the text for the label, which must be in quotes
(" ").  The <text> may contain TeX syntax
for formatting text, creating mathematical expressions,
and mixing font settings.
Options: quoted character string

Argument: <xcoor>
Description: X coordinate of start location for label
Options: real numbers

Argument: <ycoor>
Description: Y coordinate of start location for labels
Options: real numbers


If xcoor and ycoor are not included, the current label is replaced. These arguments must be included when adding the first label.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/exampleB.dat
chips> D 1 LABEL 5.0 1.2 "Label"


After a curve has been plotted, a label is added at position (5.0, 1.2).

2. chips> D 1 LABEL "NewLabel"


The text of the label created in the previous example is replaced with "NewLabel".

3. chips> D 1 LABEL 10.0 3.0 "x = \frac{y+z/2}{y^{2}+3}"


A mathematical label is added at position (10.0, 3.0) by using TeX syntax.

4. chips> D 1 LABEL 10.0 1.5 "\oe This \rm is \gr Greek"


This LABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

5. chips> CLEAR
chips> CURVE data/exampleB.dat
chips> D 1 LABEL 5.0 1.2 "Label"
chips> L 1
chips> LABEL ANGLE 45.0
chips> L 1 10.0 1.2
chips> LABEL SIZE 2.0


A curve is plotted and labeled. The angle of the label is changed to 45 degrees, then it is moved and increased in size.

6. chips> LABEL 5.0 3.0 "Label 3"
chips> LABEL 5.0 1.5 "Label 4"
chips> L 2,3 ANGLE 45.0
chips> L 1:3 SIZE 1.5


Two more labels are added to the plot from the previous example, then the command L 2,3 ANGLE 45.0 changes the angle of both of them to 45 degrees. The final command changes the size of labels numbered 1 through 3 (all labels in this case) to 1.5.

# 2.23 LEVELS

Sets the contour levels in a contour plot.

chips> [D #] [C #] LEVELS <lev1> <lev2> ... <levN>


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: C #
Description: curve number designation
Options: integer number
Default: current curve


Argument: <lev1> <lev2> ... <levN>
Description: numbers specifying Z axis values of each contour level
Options: real numbers


The lev1 value specifies the Z-axis data value of the first contour line, lev2 specifies the value of the second contour line, and so on. See the CONTOUR command for information on displaying contour plots.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CONTOUR data/example3D.sorted.dat 2 4 20
chips> LEVELS 3 5 20 100


The ASCII data file data/example3D.sorted.dat is plotted as a contour plot. The first contour line is drawn along Z-axis data values of 2, the second along values of 4, and the third along values of 20. The LEVELS command changes the contour levels to 3, 5, 20, and 100 for contour lines 1 thru 4, respectively.

# 2.24 LIMITS

Sets the ranges to be displayed in the axes.

chips> [D #] LIMITS [<coor>] {<min> | AUTO | *} {<max> | AUTO | *}
chips> [D #] LIMITS {<xmin> | AUTO | *} {<xmax> | AUTO | *} \
{<ymin> | AUTO | *} {<ymax> | AUTO | *} \
[{<zmin> | AUTO | *} {<zmax> | AUTO | *}]


Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: X

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <min>
Description: lower limit for axis range
Options: real numbers
Default: AUTO

Argument: <max>
Description: upper limit for axis range
Options: real numbers
Default: AUTO

Argument: <xmin>
Description: lower limit for X-axis range
Options: real numbers
Default: AUTO

Argument: <xmax>
Description: upper limit for X-axis range
Options: real numbers
Default: AUTO

Argument: <ymin>
Description: lower limit for Y-axis range
Options: real numbers
Default: AUTO

Argument: <ymax>
Description: upper limit for Y-axis range
Options: real numbers
Default: AUTO

Argument: <zmin>
Description: lower limit for Z-axis range
Options: real numbers
Default: AUTO

Argument: <zmax>
Description: upper limit for Z-axis range
Options: real numbers
Default: AUTO


The limit specifications come in pairs, with the first being the lower limit. A limit specification may be a number, an asterisk (*), or the argument AUTO. A '*' indicates no change in the current limit, while AUTO allows the underlying plotting package to select the limit value.

ChIPS converts double-precision numbers to floating-point values before plotting them, which can cause problems for values that are either too large or too small. The allowed range is approximately 1e-38 to 3e38 (for both positive and negative values).

The limits of the x and y axes in a contour plot cannot be modified in the current version of ChIPS.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> LIMITS X 5.0 15.0
chips> LIMITS Y 2.0 4.0
chips> LIMITS X AUTO AUTO
chips> LIMITS Y AUTO AUTO


The first two LIMITS commands change the displayed ranges of the X and Y axes, respectively. The final two commands instruct the plotting package to determine the X and Y limits. The two pairs of commands (4 lines) may be reduced to two lines:

chips> LIMITS 5.0 15.0 2.0 4.0
chips> LIMITS AUTO AUTO AUTO AUTO


2. chips> LIMITS * 15.0 * 4.5


This command preserves the minimum value of each axis, but changes the maximum of the X-axis to 15.0 and of the Y-axis to 4.5.

# 2.25 LINE

Adds a line to a drawing area and/or changes line attributes.

chips> [D #] LINE <x1> <y1> <x2> <y2>


To change line attributes:

chips> [D #] LN # <x1> <y1> <x2> <y2>
chips> [D #] {LN # | LINE} <color>
chips> [D #] {LN # | LINE} <linestyle>
chips> [D #] {LN # | LINE} WIDTH <width_value>


The LINE command can take many arguments:

Argument: <color>
Description: line color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE, YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <linestyle>
Description: style for line
Options: SOLID, DOT, DASH, LONGDASH, DOTDASH, DOTLONGDASH, DASHLONGDASH
Default: SOLID

Argument: LN #
Description: line number designation
Options: integer numbers

Argument: <width_value>
Description: line thickness
Options: real numbers
Default: 1.0

Argument: <x1>
Description: X coordinate of start location for line
Options: real numbers

Argument: <x2>
Description: X coordinate of end location for line
Options: real numbers

Argument: <y1>
Description: Y coordinate of start location for line
Options: real numbers

Argument: <y2>
Description: Y coordinate of end location for line
Options: real numbers


CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/exampleB.dat
chips> D 1 LINE 1.0 1.8 3.0 1.8


After a curve has been plotted, a line is added that begins at (5.0, 1.0) and ends at (10.0, 2.0).

2. chips> CURVE data/exampleB.dat
chips> D 1 LINE 1.0 1.8 3.0 1.8
chips> LINE BLUE
chips> LN 1 1.0 1.8 10.0 1.8
chips> LINE DOTDASH
chips> LINE WIDTH 5.0


A curve and line are plotted, and the color of the line is changed to blue. Then the LN command changes the endpoint of the line. The final two commands switch the line to a dot-dash style and increase the width to 5.0.

# 2.26 LINEAR

Changes one or more axes to linear scale.

chips> [D #] LINEAR [<coor>]


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y


The command LOG is used to return an axis to log scale.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> LOG X
chips> LOG
chips> LINEAR


The data is plotted, then the X-axis is changed to logarithmic scale. The second LOG command changes both the X and Y axes to logarithmic scale, and the LINEAR command returns both axes to linear scale.

# 2.27 LIST

Lists the contents of datafiles using the CIAO tool dmlist.

chips> LIST <filename> [<dm_list_parameter_specifications> [| <arg>]]


In addition to the filename, the input may specify the dmlist option parameter (dm_list_parameter_specifications) and any pipe-supporting Unix command (arg, e.g. less).

Examples:

1. chips> acisf01838N001_evt2.fits opt=blocks

--------------------------------------------------------------------------------
Dataset: acisf01838N001_evt2.fits
--------------------------------------------------------------------------------

Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null
Block    2: EVENTS                         Table        14 cols x 78208    rows
Block    3: GTI7                           Table         2 cols x 1        rows
Block    4: GTI0                           Table         2 cols x 1        rows
Block    5: GTI1                           Table         2 cols x 2        rows
Block    6: GTI2                           Table         2 cols x 1        rows
Block    7: GTI3                           Table         2 cols x 1        rows
Block    8: GTI6                           Table         2 cols x 1        rows


The blocks of the file acisf01838N001_evt2.fits are returned.

2. chips> LIST primary/acisf01838N001_evt2.fits cols | less

--------------------------------------------------------------------------------
Columns for Table Block EVENTS
--------------------------------------------------------------------------------

ColNo  Name                 Unit        Type             Range
1   time                 s            Real8          84244214.7546979934: 842
2   ccd_id                            Int2           0:9                  CCD
3   node_id                           Int2           0:3                  CCD
4   expno                             Int4           0:2147483647         Exp
5   chip(chipx,chipy)    pixel        Int2           1:1024               Chi
6   tdet(tdetx,tdety)    pixel        Int2           1:8192               ACI
(etc.)


The columns of the data file, which includes a pathname, are piped to "less" and printed to the screen.

# 2.28 LN

Defines the current line.

chips> [D #] LN {# [,#, ...] | #:# | ALL}


where # is an integer argument and #:# specifies an inclusive range of line numbers.

Note that if a non-existent line is specified, ChIPS will act on the current line.

Examples:

1. chips> CURVE data/example.dat X 1 Y 2
chips> LINE 2.0 1.0 2.0 4.0
chips> LINE 1.25 5.0 1.8 5.0
chips> LINE DASH


A curve is plotted and two lines are placed on the plot. The first line is designated line number 1 and the second is line number 2; Line 2 is also the current line, since it is the most recently created line. The command LINE DASH acts on the current line, changing it to a dashed line.

2. chips> D 1 LN 1
chips> LINE DASH


The command D 1 LN 1 defines line number 1 as the current line, then the LINE DASH command changes it to a dashed line.

3. chips> LN 2
chips> LINE WIDTH 4.0


Line 2 is defined as the current line. The LINE WIDTH 4.0 command acts on the line, changing it to a width of 4.0.

# 2.29 LOCATION

Specifies the location for an existing drawing area.

chips> LOCATION <x1> <x2> <y1> <y2>
chips> [D #] LOCATION <x1> <x2> <y1> <y2>


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <x1>
Description: X coordinate of lower left corner
Options: real numbers between 0.0 and 1.0
Default: 0.15

Argument: <x2>
Description: X coordinate of upper right corner
Options: real numbers between 0.0 and 1.0
Default: 0.9

Argument: <y1>
Description: Y coordinate of lower left corner
Options: real numbers between 0.0 and 1.0
Default: 0.1

Argument: <y2>
Description: Y coordinate of upper right corner
Options: real numbers between 0.0 and 1.0
Default: 0.9


The origin - (0,0) - is at the lower left corner.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> D 1 CURVE data/example.dat
chips> LOCATION 0.25 0.9 0.5 0.9


A curve is plotted, then the drawing area location is modified.

# 2.30 LOG

Changes one or more axes to logarithmic scale.

chips> [D #] LOG [<coor>]


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <coor>
Description: axis coordinates
Options: X, Y
Default: both X and Y


Note that a warning is returned when a LOG command is issued for data containing negative or zero values: "Warning: negative and zero values ignored in log scale".

The command LINEAR is used to return an axis to linear scale.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> LOG X
chips> LOG
chips> LINEAR


The data is plotted, then the X-axis is changed to logarithmic scale. The second LOG command changes both the X and Y axes to logarithmic scale, and the LINEAR command returns both axes to linear scale.

# 2.31 PACK

Renumbers plotting objects after a delete operation.

chips> PACK
chips> PACK {ON | OFF}
chips> PACK DRAWAREA
chips> [D #] PACK {CURVE | LABEL | LINE}


Plotting objects are assigned consecutive number designations, in the order in which they are created. By default, renumbering of plotting objects is turned on. This means that the objects are renumbered whenever one is removed.

Issuing this command with no arguments forces a renumbering of all plotting objects. If an argument is given, however, the specified plotting objects (drawing areas, curves, labels, and lines) are renumbered independently.

Examples:

1. chips> SPLIT 2
chips> D 1 CURVE data/exampleA.dat
chips> D 2 CURVE data/exampleB.dat
chips> D 1 DEL
Your new Current Draw Area number is: 1
chips> D 1 TWOAXES


The drawing area is split in two and a curve is plotted in each area. When drawing area number 1 is removed, drawing area number 2 becomes the current drawing area and is renumbered to be 1 (since renumbering is on by default). The command D 1 TWOAXES acts on the remaining drawing area.

2. chips> SPLIT 2
chips> D 1 CURVE data/exampleA.dat
chips> D 2 CURVE data/exampleB.dat
chips> PACK OFF
chips> D 1 DEL
Your new Current Draw Area number is: 2


Again, two curves are plotted, each in its own drawing area. The PACK OFF command causes plotting objects not to be renumbered, so drawing area number 2 becomes the current drawing area without changing number.

3. chips> D 1 CURVE data/exampleB.dat
chips> LABEL 5.0 1.5 "Label 1"
chips> LABEL 10.0 2.0 "Label 2"
chips> LABEL 15.0 3.0 "Label 3"
chips> LABEL 5.0 3.6 "Label 4"
chips> PACK OFF
chips> L 2 DEL
Your new Current Label number is: 3
chips> L 3 DEL
Your new Current Label number is: 4
chips> PACK LABEL
chips> L 1 ANGLE 45.0
chips> L 2 SIZE 2.0


A curve is plotted and four labels are added to the drawing area. The two DEL commands remove labels 2 and 3; since the command PACK OFF was issued, the remaining labels are not renumbered. The PACK LABELS command causes labels 1 and 4 to be renumbered to 1 and 2, which are then modified by the label attribute commands.

# 2.32 PAGESIZE

Sets the page dimensions for hardcopy plots.

chips> pagesize <width> <length> <unit>


In this context, "hardcopy" refers to both sending the plot directly to a printer and printing it to a postscript file.

Argument: <width>
Description: width of the hardcopy plot
Options: real numbers
Default: 8.0

Argument: <length>
Description: length of the hardcopy plot
Options:  real numbers
Default: 8.0

Argument: <unit>
Description: unit for <width> and <length>
Options: cm, inch, mm
Default: inch


The postscript drivers work well for plots no bigger than 8x8 inch or portrait plots up to about 8x10 inches. Any other setup causes problems due to inconsistant handling of margins that causes errors in calculating the bounding box. The result is that the output of "print postfile" may be clipped even if the pagesize is set correctly; this is most likely to affect plots oriented as "landscape" layout.

If creating a smaller plot is not an option, try one of these workarounds:

edit the bounding box by hand in PS file
delete the bounding box definition from the PS file
gv has the option to change or ignore the bounding box when viewing a PS file

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Unlike most other ChIPS commands, the "pagesize" command modifies the state object. This means that once the desired size has been set, the command does not need to be reissued. The current page size may also be determined by checking the state object, as shown in the EXAMPLES section.

Examples:

1. chips> rx = [1:10:0.1]
chips> ry = sin(rx)
chips> curve x rx y ry
chips> pagesize 4.0 4.0
chips> print postfile half.ps


First, a simple plot is created. The page size is set to 4x4 with the default unit of inches (note that it is not necessary to include the unit if it is unchanged). Finally, a postscript file is created.

2. chips> print(chips)
...
pagewidth        =  4
pagelen          =  4
unit             =  inch
...
chips> pagesize 15 15 cm
chips> print(chips)
...
pagewidth        =  15
pagelen          =  15
unit             =  cm
...


Building on the previous example, the height and width of the plot are modified, with the new dimensions given in cm. This also illustrates that changing the page size on the command line updates the ChIPS state object fields.

# 2.33 PICKPOINTS

Starts the interactive cursor mode, which reads out the cursor position.

chips> [D #] PICKPOINTS
chips> [D #] PICKPOINTS <value>


where value is an integer number of points to pick (defaults to 1 if not given).

The PICKPOINTS command puts the user into interactive cursor mode. Points may be selected by clicking with the left mouse button or using the spacebar; the coordinates of selected points will be printed to the screen. If the number of points to be selected is not specified with the value argument, then interactive mode will continue until the character q is entered or a right mouse click is given.

Examples:

1. chips> CURVE example.dat
chips> PICKPOINTS 3

Click LMB or tap spacebar to pick point.
Click RMB or type 'q' to quit picking points.

Point picked: (2.336950, 1.447520)
Point picked: (3.479965, 1.770423)
Point picked: (4.568552, 2.055780)
chips>


In this example, the PICKPOINTS 3 command allows the user to select three points. After the third click, the user is returned to the ChIPS command line.

2. chips> PICKPOINTS
Click LMB or tap spacebar to pick point.
Click RMB or type 'q' to quit picking points.

Point picked: (1.466081, 1.184691)
Point picked: (2.554667, 1.462538)
Point picked: (3.534395, 1.770423)
Point picked: (4.568552, 2.055780)
Point picked: (5.602708, 2.386193)
chips>


In this example, the PICKPOINTS command allows the user to select an indefinite number of points.

# 2.34 PLOT | CURVE

Plots a curve in a drawing area, or changes curve attributes.

See the CURVE command, for further information and examples.

# 2.35 PRINT

Creates a hardcopy of the current plot.

chips> PRINT {[<device>] | POSTFILE <filename>}


If no printer device is specified, the output will be sent to the default printer as specified in the user's environment. The "POSTFILE filename" argument creates a PostScript file in the current directory if no pathname is included.

There are two new commands in CIAO 3.0 that may be used to configure the look of the output: COLORSYS sets the color system (RGB, CMYK, grayscale) and PAGESIZE indicates the page dimensions of the hardcopy plot.

Note that the new COLORSYS command deprecates the former method of creating CMYK plots, namely:

  chips> PRINT "postfileCMYK <filename>"


The postscript drivers work well for plots no bigger than 8x8 inch or portrait plots up to about 8x10 inches. Any other setup causes problems due to inconsistant handling of margins that causes errors in calculating the bounding box. The result is that the output of "print postfile" may be clipped even if the pagesize is set correctly; this is most likely to affect plots oriented as "landscape" layout.

If creating a smaller plot is not an option, try one of these workarounds:

edit the bounding box by hand in PS file
delete the bounding box definition from the PS file
gv has the option to change or ignore the bounding box when viewing a PS file

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1.   chips> CURVE data/example.dat
chips> print(chips.colorsys)
rgb
chips> PRINT POSTFILE plot_rgb.ps
chips> COLORSYS CMYK
chips> PRINT POSTFILE plot_cmyk.ps


A curve is plotted and written out first as an RGB postscript file, then as a CMYK postscript file; see "ahelp colorsys" for an explanation of the syntax used.

2.   chips> CURVE example2.dat
chips> PRINT


A curve is plotted and a hardcopy is printed on the system's printer.

# 2.36 PRISM | BROWSE

Launches Prism .

See the BROWSE command, for further information and examples.

# 2.37 QUIT | EXIT

Terminates the ChIPS program.

See the EXIT command, for an example.

# 2.38 REDO

Redoes the most recently undone plotting command.

chips> REDO [#]


where # is an integer number of commands to be redone.

Examples:

1. chips> CURVE data/example.dat
chips> LIMITS X 5.0 15.0
chips> UNDO
chips> REDO


A curve is plotted and the limits of the X-axis are changed. The UNDO command restores the limit to their original defaults. The REDO command then redoes the most recently undone command, thus changing the X-axis limits once again.

2. chips> CURVE data/example.dat
chips> LIMITS X 5.0 15.0
chips> LIMITS Y 10.0 15.0
chips> AXES BLUE
chips> LIMITS Y 10.0 25.0
chips> UNDO 3
chips> REDO 1


A curve is plotted and the limits of both axes are changed. They are colored blue, then the Y-axis limits are changed again. The UNDO command backtracks through the previous three commands (in the order they are undone: LIMITS Y 10.0 25.0, AXES BLUE, LIMITS Y 10.0 15.0). The REDO command then redoes the most recently undone command (LIMITS Y 10.0 15.0), leaving the final plot with white axes and limits of x5:15, y10:15.

# 2.39 REDRAW

Redraws the plot or sets the redraw mode

chips> REDRAW
chips> REDRAW ON
chips> REDRAW OFF


When ChIPS is started the redraw mode is set to "on". This means that any command that changes the plot display - such as adding or deleting a curve or changing the plot title - will have an immediate effect. There are times when this behaviour is undesireable - such as plots of large datasets or when creating a plot from a script - and so it can be turned off by calling BATCH OFF. It can be restored by BATCH ON.

After the redraw mode is turned off, ChIPS commands will appear to have no affect on the current plot. The REDRAW command on its own will force the plot to be displayed with the current contents, or the ChIPS PRINT command can be used to create a postscript version of the current plot.

The default behaviour for Sherpa is to turn automatic redrawing off. This includes loading the Sherpa module into a S-Lang script.

Examples:

1. chips> CURVE data/example.dat
chips> REDRAW OFF
chips> SYMBOL UPTRI
chips> SYMBOL BLUE
chips> SYMBOL SIZE 5.0
chips> REDRAW


After the curve is plotted, automatic redrawing is turned off. Therefore, the effect of commands that follow are not displayed until the REDRAW command refreshes the plot.

2. chips> REDRAW ON
chips> SIMPLELINE


Building on the previous example, automatic redrawing is restored. When the SIMPLELINE command is issued, the plot is redrawn with the new curve linestyle.

# 2.40 RELATIVESIZE | RELSIZE

Alters the relative size of drawing areas. The command RELSIZE is equivalent.

chips> [D #] RELATIVESIZE [<column>] <size>


By default, size is 1.0.

The RELATIVESIZE command with no column argument will alter the relative sizes of drawing areas created with the SPLIT command. The command changes the size of the drawing area in relation to the other drawing areas.

The RELATIVESIZE command with a column argument will alter the width of a column of drawing areas.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> SPLIT 2
chips> D 1 CURVE data/exampleA.dat
chips> D 2 CURVE data/exampleB.dat
chips> RELATIVESIZE 2.1


The curves are first plotted in separate drawing areas. The RELATIVESIZE 2.1 command changes the relative size of the current drawing area (number 2), to be 2.1 times the size of drawing area number 1.

2. chips> RELATIVESIZE 1.0
chips> D 1 RELATIVESIZE 3.2


The relative sizes of the drawing areas from the previous example are returned to the default value of 1.0 (equal sizes). Drawing area 1 is then made 3.2 times the size of drawing area 2.

3. chips> clear
chips> split 2 4
chips> RELSIZE 1 0.5


The current plot is cleared, then split into two columns of four drawing areas. The RELSIZE command makes the width of column one 50% of the width of column two.

# 2.41 RESTORE

Restores a plot with all attributes.

chips> RESTORE <filename>


The filename is a file previously created with the ChIPS STORE command and may contain a directory path.

Examples:

1. chips> RESTORE myplot.chp


The plot saved in the myplot.chp is restored. See the STORE command for an example of how the plot was saved.

# 2.42 SKIP

Skips the designated number of lines from subsequent input files.

chips> SKIP <skip_value>


All files plotted after this command is issued will have the specified number of lines skipped.

Examples:

1. chips> SKIP 10
chips> CURVE data/exampleB.dat


The command SKIP 10 causes the first ten lines of the data file data/exampleB.dat to be skipped when it is read in and plotted.

# 2.43 SPLIT

Creates multiple drawing areas and/or arranges their locations.

chips> SPLIT <n>
chips> SPLIT <nx> <ny>
chips> SPLIT COLS <nc1> <nc2> ... <ncN>


where n, nx, ny, ncN must be integers greater than zero.

The commands create plots as follows:

SPLIT n - a single column containing n rows of drawing areas.

SPLIT nx ny - nx columns, each with ny rows of drawing areas. The command SPLIT 1 ny is equivalent to SPLIT n.

SPLIT COLS nc1 nc2 ...ncN - a column for each item in the list, with each value indicating how many rows to place in that column.

Drawing areas are numbered sequentially from the upper left corner, top to bottom and left to right.

To arrange drawing area locations:

chips> SPLIT MAJ <coor>
chips> SPLIT GAP [<coor>] <separation>
chips> SPLIT GAP <nc> <separation>
chips> SPLIT LOCATION <x1> <x2> <y1> <y2>


where:

Argument: <coor>
Description: axis on which the split or gap is created
Options: X, Y
Default: both X and Y

Argument: <nc>
Description: column or row number, depending on the current SPLIT MAJ <coor> setting
Options: integer numbers

Argument: <separation>
Description: gap spacing
Options: real numbers
Default: 0


SPLIT MAJ coor controls whether rows or columns are used when arranging drawing areas. The default setting is SPLIT MAJ X. When SPLIT MAJ Y has been set, the basic SPLIT commands operate using rows instead of columns. Note that this command affects the currently existing plot, as shown in the examples.

SPLIT GAP coor separation changes the gap spacing between drawing areas to the amount specified. If no coor is given, both row (Y axis) and column (X axis) gaps are changed. The coordinate system runs from 0 to 1, so a separation 0.1, is typically appropriate.

When SPLIT MAJ X is set (this is the default), the command SPLIT GAP nc separation changes the row spacing within column nc. If SPLIT MAJ Y is set, however, the command SPLIT GAP nc separation changes the column spacing within row nc.

The command SPLIT LOCATION x1 x2 y1 y2 is analogous to the LOCATION command for drawing areas.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> SPLIT 3


Three drawing area are created, arranged in a single column.

2. chips> SPLIT 3 2


Three columns are created, each with 2 rows of drawing areas. The following command is equivalent:

chips> SPLIT COLS 2 2 2


3. chips> SPLIT COLS 1 2 3


This command creates 3 columns. The first column contains one row of drawing areas, the second contains two rows, and the third column contains three rows.

4. chips> SPLIT COLS 4 1 2 3
chips> SPLIT MAJ Y


The first command creates four columns. The first column contains four rows of drawing areas, the second contains one, the third contains two, and the fourth contains three. The command SPLIT MAJ Y reverses the columns to rows, so that there are now four rows. The first row contains four columns, the second row contains one column, the third row contains 2 columns, and the fourth row contains three columns.

5. chips> SPLIT 3
chips> SPLIT GAP 0.15


Three drawing area rows are created, arranged in one column. The SPLIT GAP 0.15 command changes the gap spacing between the rows to 0.15. The following command is equivalent:

chips> SPLIT GAP Y 0.15


6. chips> SPLIT 3 2
chips> SPLIT GAP Y 0.12
chips> SPLIT GAP X 0.10
chips> SPLIT GAP 0.08


First, three columns of drawing areas are created, each containing 2 rows. The gap spacing between the rows is changed to 0.12, and the spacing between the columns is changed to 0.10. The final command changes all gap spacings to 0.08.

7. chips> SPLIT MAJ X
chips> SPLIT GAP 2 0.19


The row spacing in column 2 only is changed to 0.19.

8. chips> SPLIT 3 2
chips> SPLIT GAP 0.03
chips> SPLIT MAJ Y
chips> SPLIT GAP 1 0.2


First, three columns of drawing areas are created, each containing 2 rows. All gap spacings are then set to 0.03. The SPLIT MAJ Y command reverses the column and row precedences; this changes the drawing area to two columns with three rows. The final command changes the column spacing within row one to 0.2.

# 2.44 STORE

Saves a plot with all attributes.

chips> STORE <filename>


The STORE command creates an ASCII file which contains all the commands needed to re-create the current plot display. The filename is the name of the file to be created and may contain a directory path. This file can then be read into another ChIPS session using the RESTORE command.

This allows you to create a plot - perhaps in Sherpa - and save it so it can be re-created or modified at a later date.

When storing plots created using the ChIPS CURVE command, the store file will reference the data file by name - including the full path. If the plots were created without an associated data file - for instance a Sherpa plot or data plotted using the the S-Lang curve() function - then the plot data will be written to a FITS file called "filename.fits". The one exception to this is for contour plots, when the data for that plot is stored in the /tmp/ directory as an ASCII file.

Examples:

1. chips> cd /work
chips> SPLIT 2
chips> D 1 CURVE data/data.dat
chips> D 1 CURVE data/fit.dat
chips> D 2 CURVE data/residuals.dat
chips> D 1 C 2 SYMBOL NONE
chips> D 1 C 2 SIMPLELINE
chips> D 1,2 LIMITS 0.0 11.0
chips> D 2 SYMBOL CIRCLE
chips> D 2 SYMBOL SIZE 1
chips> D 1 LIMITS Y 1.0 4.5
chips> D 2 LIMITS Y 0.0 4.5
chips> XLABEL "Off-Axis (arcmin)"
chips> D 1,2 YLABEL "SNR"
chips> TITLE "HRC-I 100ks"
chips> TITLE CYAN
chips> XLABEL CYAN
chips> D 1,2 YLABEL CYAN
chips> SPLIT GAP y 0.04
chips> D 1 TICKVALS X OFF
chips> D 1,2 TICKVALS y "%1.1f"
chips> STORE myplot.chp


After plotting some data and customizing the look of the plot, it is stored to the file myplot.chp in the current directory. This is an ASCII file the references the plotted data using full path specifications; it may be restored from any location, as long as the data has not been moved.

chips> \$more myplot.chp
#This is a ChIPS state file.
#ChIPS_Version: 2.20

redraw off

##############################
# Start of a new drawing area.
##############################
drawarea 0.15 0.9 0.52 0.9

#######################
# Start of a new curve.
skip 0
curve "/work/data/data.dat"

#######################
# Start of a new curve.
skip 0
curve "/work/data/fit.dat"
symbol  none
symbol 0 0
simpleline

(etc.)


2. chips> x = [0:10:0.02]
chips> y = tan(x)
chips> chips.curvestyle = _chips->simpleline
chips> chips.symbolstyle = _chips->none
chips> () = curve(x,y)
chips> limits y -10 10
chips> store tanplot.chp


Here we use S-Lang commands to create and plot the curve ytan(x). As well as creating the file tanplot.chp, the STORE command also creates the file tanplot.chp.fits which contains the data that was plotted.

Note that the store file does not record the contents of the ChIPS State object. So, when the plot is re-created via a call to RESTORE, it will be drawn with no symbols and with a line connecting the points but the chips.curvestyle and chips.symbolstyle fields will not be set to _chips-simpleline and _chips-none respectively.

3. sherpa> READ DATA 1 data/example1.dat
sherpa> PARAMPROMPT OFF
Model parameter prompting is off
sherpa> POLY[modela]
sherpa> SOURCE 1 = modela
sherpa> THAW modela.2 modela.3
sherpa> FIT
sherpa> LPLOT FIT
sherpa> STORE myplotfromsherpa.chp
sherpa> ls myplotfromsherpa.chp*
myplotfromsherpa.chp
myplotfromsherpa.chp.fits


Here the STORE command is used from within Sherpa to save a plot generated using the Sherpa command LPLOT. Two files have been generated: the ASCII file with the plot commands and a FITS file that contains the data. The data for each curve is stored in a separate FITS extension:

chips> list myplotfromsherpa.chp.fits blocks

---------------------------------------------------------------------
Dataset: myplotfromsherpa.chp.fits
---------------------------------------------------------------------

Block Name                          Type         Dimensions
---------------------------------------------------------------------
Block    1: PRIMARY                        Null
Block    2: curve0                         Table         6 cols x 12
Block    3: curve1                         Table         2 cols x 12


The curve0 extension contains the input data and the curve1 extension contains the fit.

# 2.45 SURFACE

Adds a surface plot to a drawing area.

chips> [D #] SURFACE <filename>[<virtual_file_syntax>] <zmin> <zmax>


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <filename>
Description: name of datafile and path, if necessary.  If the file
contains tabulated data, it must be sorted with row
precedence (see below).  May be filtered data from a
FITS image file, as shown in the EXAMPLES.

Argument: <virtual_file_syntax>
Description: A filtering and/or binning command argument.  The
<virtual_file_syntax> must be surrounded by
quotes (" ").


Argument: <zmin>
Description: minimum Z-axis value
Options: real numbers

Argument: <zmax>
Description: maximum Z-axis value
Options: real numbers


Surface are considered variants of curves, and therefore the attributes of contours (color, linestyle, scale, width) may be changed in the same manner. However, the limits of the x and y axes in a surface plot cannot be modified.

The VIEWPOINT command has information on controlling the rotation angle of a surface plot.

SORTING THE INPUT DATA

The input data file must be sorted with row precedence. For example, the following data:

1 1 1
2 1 -4.97206e-24
3 1 2
4 1 1
5 1 2
1 2 -6.79138e-24
2 2 -2.23247e-23
3 2 1
4 2 -2.1879e-22
5 2 1


Would have to be re-ordered for use in ChIPS:

1 1 1
1 2 -6.79138e-24
2 1 -4.97206e-24
2 2 -2.23247e-23
3 1 2
3 2 1
4 1 1
4 2 -2.1879e-22
5 1 2
5 2 1


Examples:

1. chips> SURFACE data/example3D.sorted.dat 0.0 10.0


The ASCII data file data/example3D.sorted.dat is plotted as a surface, where the minimum Z-axis value is 0.0 and the maximum Z-axis value is 10.0.

2. chips> SURFACE data/exampleImage.fits[10:100,10:100] 0.0 10.0


A surface plot is created from the data in the FITS file which falls into the specified ranges. Again, the minimum Z-axis value is 0.0 and the maximum Z-axis value is 10.0.

3. chips> CLEAR
chips> SURFACE "data/example3D.sorted.fits[cols col1, col2, col3]"
0.0 10.0


The data in columns col1, col2, and col3 of data/example3D.sorted.fits are plotted as a surface plot.

4. chips> SURFACE s3_img.fits 20 30


A surface plot is created from the filtered data stored in "s3_img.fits".

# 2.46 SYMBOL

Specifies the appearance of symbols in a curve.

chips> [D #] [C #] SYMBOL <color>
chips> [D #] [C #] SYMBOL <symbolstyle>
chips> [D #] [C #] SYMBOL [SIZE] <size_value>


Argument: C #
Description: curve number designation
Options: integer numbers
Default: current curve


Argument: <color>
Description: axes color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <size_value>
Description: symbol size; affects all subsequent symbol styles.
Has no effect when the current symbol style is POINT.
Options: real numbers
Default: 3.0

Argument: <symbolstyle>
Description: style for symbols
Options: BLOCK, CIRCLE, CROSS, DIAMOND, SOLIDDIAMOND, DOWNTRI,
SOLIDDOWNTRI, UPTRI, SOLIDUPTRI, SQUARE, POINT, BIGPOINT,
NONE
Default: CROSS


Note the the "POINT" symbol is not scalable (it is always tiny). As an alternative, the "BIGPOINT" shape can be set to any size.

The Figure is an illustration of the different symbolstyle options.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/exampleA.dat
chips> CURVE data/exampleB.dat
chips> C 1 SYMBOL UPTRI
chips> C 2 SYMBOL DIAMOND


First, two curves are plotted into a single drawing area. Curve 1 is changed to UPTRI and curve 2 is changed to DIAMOND.

2. chips> C 1 SYMBOL CYAN
chips> C 2 SYMBOL RED


Curves 1 and 2 are changed to be cyan and red, respectively.

3. chips> C 1,2 SYMBOL SIZE 2.0


The symbol size for both curves is increased to 2.0.

4. chips> CLEAR
chips> CURVE data/exampleA.dat
chips> SYMBOL DIAMOND
chips> SYMBOL DOWNTRI
chips> SYMBOL SIZE 2.0
chips> SYMBOL DIAMOND


The first two SYMBOL commands illustrate the DIAMOND and DOWNTRI symbols at their default size of 3.0. The SYMBOL SIZE 2.0 command then changes the size of the current DOWNTRI symbols. The final SYMBOL DIAMOND command shows that changing the new style retains the last SYMBOL SIZE instruction.

# 2.47 TICKS

Specifies the spacing of tick marks.

chips> [D #] TICKS [<ticktype>] [<coor>] <interval>


Argument: <coor>
Description: axis
Options: X, Y
Default: both X and Y

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <interval>
Description: interval between tick marks
Options: real numbers
Default: automatically determined

Argument: <ticktype>
Description: type of grid markings
Options: MAJ - major tick marks only
MIN - minor tick marks only
Default: both MAJ and MIN


CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> SPLIT 2
chips> D 1 CURVE data/fit.dat
chips> D 2 CURVE data/residuals.dat
chips> D 1 TICKS 1.0


The curves are plotted in two drawing areas, then the tick spacing of drawing area 1 is changed to 1.0 for both axes.

2. chips> D 2 TICKS X 2.0
chips> D 2 TICKS Y 0.5


The first command changes the interval between tick marks on the X-axis of drawing area 2 to 2.0. The Y-axis tick marks are changed to have a spacing of 0.5.

3. chips> SPLIT GAP 0.05
chips> D 1 TICKS MIN X 0.5
chips> D 1 TICKS MAJ Y 0.5
chips> D 2 TICKS MAJ X 1.0
chips> D 2 TICKS MIN X 0.5


The drawing areas are first separated by a small amount (0.05). The command D 1 TICKS MIN X 0.5 adds minor tick marks with spacing 0.5, to the X-axis of drawing area 1. The interval between the Y-axis major tick marks of that area are then changed to 0.5. Similar commands are applied to drawing area 2.

# 2.48 TICKVALS

Controls the appearance of numerical tick mark labels.

chips> [D #] TICKVALS [<coor>] {AUTO | <format>}
chips> [D #] TICKVALS [<coor>] {ON | OFF}
chips> [D #] TICKVALS [SIZE] <size_value>


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <coor>
Description: axis
Options: X, Y
Default: both X and Y

Argument: <format>
Description: format of the numeric tick mark labels; must be contained
within quotes (" ").
Options: any standard FORTRAN or C format string

Argument: <size_value>
Description: tick size
Options: real numbers
Default: 1.0


CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> SPLIT 2
chips> D 1 CURVE data/fit.dat
chips> D 2 CURVE data/residuals.dat
chips> D 1 TICKVALS X OFF


After two curves are plotted, each within a separate drawing area, the tick mark labels are removed from the X-axis of drawing area number 1.

2. chips> D 1 TICKVALS SIZE 0.95
chips> D 2 TICKVALS SIZE 0.75


The size of the tick marks on drawing areas 1 and 2 are changed to 0.95 and 0.75, respectively.

3. chips> D 1 TICKVALS Y "%1.1f"
chips> D 2 TICKVALS "%1.1f"
chips> D 2 TICKVALS X AUTO


The format of the tick mark labels on the Y axis of drawing area 1, where "%1.1f" is a C formatting string. The second command applies the same format to both axes of drawing area 2. Finally, the tick mark labels on the X-axis of area 2 are restored to the default setting.

# 2.49 TITLE

Adds a title and/or changes the title attribute.

chips> TITLE <color>
chips> TITLE ["<title_text>"]
chips> TITLE SIZE ["<size_value>"]


Argument: <color>
Description: title color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <title_text>
Description: the text for the title, which must be in quotes
(" ").  The <text> may contain TeX syntax for
formatting text, creating mathematical expressions,
and mixing font settings.
Options: quoted character string


Argument: <size_value>
Description: title size
Options: real numbers
Default: 1.0


Issuing this command with no argument will delete the current title.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> D 1 CURVE data/example.dat X 1 Y 2
chips> TITLE "My Title"
chips> TITLE YELLOW


A data file is plotted and a title is added to a plot. The color of the title is then changed to yellow.

2. chips> TITLE "x = \frac{y+z/2}{y^{2}+3}"


A title that contains a mathematical expression is added to a plot by using TeX syntax.

3. chips> D 1 LABEL 2.0 50.0 "\oe This \rm is \gr Greek"


This LABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

# 2.50 TYPE

Reports the data that are associated with a curve.

chips> [D #] [C #] TYPE


where D # is a drawing area number designation and C # is a curve number designation.

Examples:

1. chips> D 1 CURVE data/exampleA.dat
chips> D 1 CURVE data/exampleB.dat
chips> D 1 C 1 TYPE
X              Y
1              1
2              5
3              8
4             17
5             24
6             37
7             48
8             65
chips>


Two curves are plotted in drawing area 1. The TYPE command reports the data that are associated with curve number 1.

# 2.51 UNDO

Undoes the most recently executed plotting command.

chips> UNDO
chips> UNDO n


The UNDO command undoes the previous ChIPS command or - if a number is supplied ("m" above) - undoes that number of commands. There is a limit of 10 commands that can be undone.

Examples:

1. chips> CURVE data/example.dat
chips> LIMITS X 5.0 15.0
chips> UNDO


A curve is plotted, then the limits of the X-axis are changed. The UNDO command restores the limit to their original defaults.

2. chips> CURVE data/example.dat
chips> LIMITS X 5.0 15.0
chips> LIMITS Y 10.0 15.0
chips> AXES BLUE
chips> LIMITS Y 10.0 25.0
chips> UNDO 3


A curve is plotted and the limits of both axes are changed. They are colored blue, then the Y-axis limits are changed again. The UNDO command backtracks through the previous three commands (in the order they are undone: LIMITS Y 10.0 25.0, AXES BLUE, LIMITS Y 10.0 15.0).

# 2.52 VERBOSE

Regulates reporting of error and informational messages.

chips> VERBOSE <integer>


where integer is 1 for maximum reporting and 0 for reduced reporting.

By default, maximum reporting is turned on.

Examples:

1. chips> VERBOSE 0


The verbosity is reduced for this session.

# 2.53 VIEWPOINT

Controls the rotation angle of a surface plot.

chips> [D #] [C #] VIEWPOINT <theta> <phi> <l>


Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: C #
Description: curve number designation
Options: integer number
Default: current curve


Argument: <l>
Description: angle l in degrees
Options: real numbers
Default: -1.0

Argument: <phi>
Description: angle phi in degrees
Options: real numbers
Default: -10.0

Argument: <theta>
Description: angle theta in degrees
Options: real numbers
Default: 30.0


The angles theta, phi, and l are defined in ChIPS the same way as they are defined in the SM engine: Surfaces are drawn from a direction (theta,phi), and projected onto a surface passing through the origin. The projection is from a point l away from the nearest corner of the cube containing the image. If l is:

positive - a perspective projection is used

zero (0) - the viewpoint is taken to be infinitely far from the surface

negative - an axonometric projection is used (i.e. the surface is projected from infinity onto the X-Z plane)

The coordinate system is right-handed and is oriented such that the Z-axis is theta 90 and (theta,phi)(0,0). Angles are taken to be in degrees, with theta lying in (-90,90) and phi lying in (-180,180). The nearest corner of the cube containing the surface is projected onto the point (0,0).

Examples:

1. chips> D 1 SURFACE data/example3D.sorted.dat 0.0 10.0
chips> VIEWPOINT 10.0 10.0 10.0


The data file data/example3D.sorted.dat is plotted as a surface plot. The VIEWPOINT command then changes the rotation angle and distance at which the surface plot is viewed.

# 2.54 XLABEL

Adds a label along the X-axis of a drawing area and/or changes X-axis label attributes.

chips> [D #] XLABEL ["<text>"]


To change X-axis label attributes:

chips> [D #] XLABEL <color>
chips> [D #] XLABEL [SIZE] <size_value>


The XLABEL command can take many arguments:

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <color>
Description: label color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <size_value>
Description: label size
Options: real numbers
Default: 1.0

Argument: <text>
Description: the text for the label, which must be in quotes
(" ").  The <text> may contain TeX syntax for
formatting text, creating mathematical expressions,
and mixing font settings.
Options: quoted character string


Issuing this command with no arguments will delete the current X-axis label.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> XLABEL "This is the X-axis"


After a curve has been plotted, a label is added to the X-axis.

2. chips> XLABEL " "
chips> XLABEL "\oe This \rm is \gr Greek"


The command XLABEL " " removes the previous X-axis label. The second XLABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

3. chips> XLABEL YELLOW
chips> XLABEL SIZE 1.5


An existing label is changed to the color yellow, then increased in size to 1.5.

# 2.55 YLABEL

Adds a label along the Y-axis of a drawing area and/or changes Y-axis label attributes.

chips> [D #] YLABEL ["<text>"]


To change Y-axis label attributes:

chips> [D #] YLABEL <color>
chips> [D #] YLABEL [SIZE] <size_value>


The YLABEL command can take many arguments:

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <color>
Description: label color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <size_value>
Description: label size
Options: real numbers
Default: 1.0

Argument: <text>
Description: the text for the label, which must be in quotes
(" ").  The <text> may contain TeX syntax for
formatting text, creating mathematical expressions,
and mixing font settings.
Options: quoted character string


Issuing this command with no arguments will delete the current Y-axis label.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> YLABEL "This is the Y-axis"


After a curve has been plotted, a label is added to the Y-axis.

2. chips> YLABEL " "
chips> YLABEL "\oe This \rm is \gr Greek"


The command YLABEL " " removes the previous Y-axis label. The second YLABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

3. chips> YLABEL YELLOW
chips> YLABEL SIZE 1.5


An existing label is changed to the color yellow, then increased in size to 1.5.

# 2.56 ZLABEL

Adds a label along the Z-axis of a drawing area and/or changes Z-axis label attributes.

chips> [D #] ZLABEL ["<text>"]


To change Z-axis label attributes:

chips> [D #] ZLABEL <color>
chips> [D #] ZLABEL [SIZE] <size_value>


The ZLABEL command can take many arguments:

Argument: D #
Description: drawing area number designation
Options: integer numbers
Default: current drawing area


Argument: <color>
Description: label color
Options: BLACK, BLUE, CYAN, DEFAULT, GREEN, MAGENTA, RED, WHITE,
YELLOW
Default: DEFAULT (appears in ChIPS window as white; prints as black)

Argument: <size_value>
Description: label size
Options: real numbers
Default: 1.0

Argument: <text>
Description: the text for the label, which must be in quotes
(" ").  The <text> may contain TeX syntax for
formatting text, creating mathematical expressions,
and mixing font settings.
Options: quoted character string


Issuing this command with no arguments will delete the current Z-axis label.

CIAO allows some plot attributes to be changed using the ChIPS state object and resource file. See "ahelp chips" for further details.

Examples:

1. chips> CURVE data/example.dat
chips> ZLABEL "This is the Z-axis"


After a curve has been plotted, a label is added to the Z-axis.

2. chips> ZLABEL " "
chips> ZLABEL "\oe This \rm is \gr Greek"


The command ZLABEL " " removes the previous Z-axis label. The second ZLABEL command utilizes TeX syntax in order to achieve mixed font settings in the same plot. The command produces a label where "This" is in Old English font, "is" is in Roman font, and "Greek" is in the Greek font.

3. chips> ZLABEL YELLOW
chips> ZLABEL SIZE 1.5


An existing label is changed to the color yellow, then increased in size to 1.5.