3. S-lang in ChIPS

The S-Lang programming language can be used to manipulate or create data for plotting; see ``ahelp slang'' for more information on S-Lang. This chapter describes the S-lang functions that duplicate and extend the 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 .

Unlike ChIPS commands, S-lang IS case sensitive and must be written in lowercase.

3.1 chips_auto_redraw

Set the automatic redrawing mode.

Integer_Type chips_auto_redraw(flag)

This function sets (flag $=$ 1) or unsets (flag $=$ 0) the automatic redrawing mode of ChIPS. It returns the previous setting.

Use the "chips_redraw()" command to force the ChIPS display to be redrawn.

Table 3.1: Arguments for chips_auto_redraw

Name	Type	Options	Default	Comment
flag	Integer_Type	0 for off, 1 for on	1 (on)

Examples:

1.   chips> chips_auto_redraw(0)
     1
   

   Here we have turned off the automatic redraw mode. The return value shows that the previous setting had been on (i.e. 1).

2.   () = chips_auto_redraw(0);
   

   As the first example, but done in a S-Lang script. Here the return value is ignored.

3.2 chips_clear

Removes all plotting objects, creating a new blank drawing area.

chips_clear()

This is a S-Lang version of the ChIPS CLEAR command. It erases all curves, lines, labels, and resets the number of panes (i.e. drawing areas) to 1. Since it has no parameters, it can be called without the "()".

Examples:

1.   chips> chips_clear
   

   Clear ChIPS of all plotting objects.

2.   () = chips_clear;
   

   As the first example, but done in a S-Lang script.

3.3 chips_color_name

Converts a color number to a string.

String_Type chips_color_name([colorValue])

Returns the string equivalent of the symbolic color values in the "_chips" namespace. The values are described in the 'Attribute values' section of "ahelp chips". The "chips_color_value()" function can be used to convert the names of colors to their symbolic value.

Table 3.2: Arguments for chips_color_name

Name	Type	Options	Default	Comment
colorValue	Integer_Type	black, blue, cyan, default, green, magenta, red, white, yellow (see Example 3)	default	Optional

If colorValue is outside the range of supported colors, then the string "default" will be returned. If the color value is omitted the routine will return a string containing all the available colors, separated by a newline (i.e. ' $\backslash$n') character.

Examples:

1.   chips> chips_color_name( _chips->red )
     red
   

   Here we convert the value _chips-$>$red to the string "red". Since we have ignored the return value, ChIPS prints it out to the screen (see the 'Using ChIPS and Sherpa as a calculator' section of "ahelp tips").

2.   chips> variable colname = chips_color_name( chips.curvecolor );
     chips> print("The color of curves is " + colname );
   

   Here use use S-Lang code to find out the name of the color used to draw curves. If the ChIPS state object has not been changed, then these commands would produce the following output:

     The color of curves is default
   

3.   chips> chips_color_name()
     black
     blue
     cyan
     default
     green
     magenta
     red
     white
     yellow
   

   Since no value is given, the list of available colors is returned. This string may be stored in a variable:

     chips> hues = chips_color_name()
     chips> print(hues)   
     black
     blue
     cyan
     default
     green
     magenta
     red
     white
     yellow
   

   As the names are separated by the newline (' $\backslash$n') character, they can be easily separated using the S-Lang strchop() function:

     chips> colors = strchop( chips_color_name(), '\n', 0 )
     chips> print(colors[2])
     cyan
   

3.4 chips_color_value

Converts the name of a color to its numeric value.

Integer_Type chips_color_value(colorName)

Returns the symbolic value for the supplied color name. The color values are described in the 'Attribute values' section of "ahelp chips". The "chips_color_name()" function can be used to convert the symbolic value back to the name of a color.

Table 3.3: Arguments for chips_color_value

Name	Type	Default	Comment
colorName	String_Type	3	Case insensitive

The value of _chips-$>$default will be returned when an unknown color is specified.

Examples:

1.   chips> chips_color_value( "red" )
     6
     chips> _chips->red
     6
   

   Here we find the symbolic value for the color "red". Since we have ignored the return value ChIPS prints it out to the screen (see the 'Using ChIPS and Sherpa as a calculator' section of "ahelp tips").

2.   chips> chips_color_value( "green" )
     4
     chips> chips_color_value( "GREEN" )
     4
     chips> chips_color_value( "GrEEn" )
     4
   

   The case of the color name is unimportant, as shown here.

3.   chips> chips_color_value( "UnknownColor" )
     3
     chips> chips_color_value( "default" )
     3
   

   If a color is unknown, then the value for the default color is returned.

4.   chips> chips.curvecolor = chips_color_value( "red" );
   

   Here we set the curvecolor attribute of the ChIPS state object (see "ahelp chips") to be red. Since curvecolor must be specified using the symbolic value for the color red, we use chips_color_value() to do the conversion. The following line of code can also be used to set the curvecolor attribute to red:

     chips> chips.curvecolor = _chips->red;
   

3.5 chips_get_pane

Get the current pane/drawing area.

Integer_Type chips_get_pane()
Integer_Type chips_get_drawing_area()

Returns the number of the current pane/drawing area; the two commands are identical. The numbering scheme of the panes is described in "ahelp chips_split". Since there are no parameters, the functions can be called without the trailing "()".

Examples:

1.   chips> chips_split(2,3,4)
     6
     chips> chips_get_pane
     4
   

   Here we create 6 panes, arranged in a 2 by 3 grid, and move to the fourth one. We then check that this has happened with chips_get_pane().

2.   () = chips_split(2,3,4);
     variable pane = chips_get_pane;
     print("Current pane is " + string(pane))
   

   As the first example, but done in a S-Lang script. Here the pane number is stored in a S-Lang variable and output to the screen using the Varmm print() function.

3.6 chips_get_xrange

Get the upper and/or lower x-axis limits of the plot

Integer_Type chips_get_xrange()

Determines the limits of the plot's x-axis. On success, two float values will be returned. Two NULLs are returned on error (e.g. if there is no drawing area). Note that the limits returned are those used internally by ChIPS to draw the plot axes, so they may not match the numeric limits of the plotted data.

To return either the minimum or the maximum value, the syntax

  (xmin,) = chips_get_xrange()
  (,xmax) = chips_get_xrange()

can be used.

The limits may be adjusted with chips_set_xrange.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> (xmin,xmax) = chips_get_xrange()
     chips> vmessage("xmin = %f, xmax = %f",xmin,xmax)
     xmin = 751.849976, xmax = 887.150024
   

   A data file is read in and plotted, then the minimum and maximum values of the x-axis are printed out.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> (,rmax) = chips_get_xrange()
     chips> print(rmax)
     72.45
   

   Here only the upper (maximum) x-axis limit was desired.

3.7 chips_get_xscale

Get the x-axis scale

Integer_Type chips_get_xscale()

Gets the scale of the plot's x-axis. The function returns "1" for linear and "0" for log. Non-existent drawing areas are assumed to have a default scale of linear.

The current scale may be changed with chips_set_xscale.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_get_xscale()    
     1
   

   The dataset is read in and plotted with a linear x-axis, as returned by the "chips_get_xscale" command.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_xscale(0)
     Warning: negative and zero values ignored in log scale
     0
     chips> chips_get_xscale()
     0
   

   The x-axis is changed to log scale with the "chips_set_xscale" command, then the change is confirmed. Note the the first command returns "0" for success, while the second returns "0" to indicate log scale.

3.8 chips_get_yrange

Get the upper and/or lower y-axis limits of the plot

Integer_Type chips_get_yrange()

Determines the limits of the plot's y-axis. On success, two float values will be returned. Two NULLs are returned on error (e.g. if there is no drawing area). Note that the limits returned are those used internally by ChIPS to draw the plot axes, so they may not match the numeric limits of the plotted data.

To return either the minimum or the maximum value, the syntax

  (ymin,) = chips_get_yrange()
  (,ymax) = chips_get_yrange()

can be used.

The limits may be adjusted with chips_set_yrange.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> (ymin,ymax) = chips_get_yrange()
     chips> vmessage("ymin = %f, ymax = %f",ymin,ymax)
     ymin = -6.300000, ymax = 132.300003
   

   A data file is read in and plotted, then the minimum and maximum values of the y-axis are printed out.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> (,rmax) = chips_get_yrange()
     chips> print(rmax)
     36.75
   

   Here only the upper (maximum) y-axis limit was desired.

3.9 chips_get_yscale

Get the y-axis scale

Integer_Type chips_get_yscale()

Gets the scale of the plot's y-axis. The function returns "1" for linear and "0" for log. Non-existent drawing areas are assumed to have a default scale of linear.

The current scale may be changed with chips_set_yscale.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_get_yscale()    
     1
   

   The dataset is read in and plotted with a linear y-axis, as returned by the "chips_get_yscale" command.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_yscale(0)
     Warning: negative and zero values ignored in log scale
     0
     chips> chips_get_yscale()
     0
   

   The y-axis is changed to log scale with the "chips_set_yscale" command, then the change is confirmed. Note the the first command returns "0" for success, while the second returns "0" to indicate log scale.

3.10 chips_get_zrange

Get the upper and/or lower z-axis limits of the plot

Integer_Type chips_get_zrange()

Determines the limits of the plot's z-axis. On success, two float values will be returned. Two NULLs are returned on error (e.g. if there is no drawing area). Note that the limits returned are those used internally by ChIPS to draw the plot axes, so they may not match the numeric limits of the plotted data.

To return either the minimum or the maximum value, the syntax

  (zmin,) = chips_get_zrange()
  (,zmax) = chips_get_zrange()

can be used.

The limits may be adjusted with chips_set_zrange.

Examples:

1.   chips> surface tabbed.data 0 150
     chips> (zmin,zmax) = chips_get_zrange()
     chips> vmessage("zmin = %f, zmax = %f",zmin,zmax)
     zmin = 0.000000, zmax = 150.000000
   

   The minimum and maximum values of the z-axis for a surface plot are printed out.

2.   chips> surface tabbed.data 0 100
     chips> (,rmax) = chips_get_zrange()
     chips> print(rmax)                 
     100
   

   Here only the upper (maximum) z-axis limit was desired.

3.11 chips_get_zscale

Get the z-axis scale

Integer_Type chips_get_zscale()

Gets the scale of the plot's z-axis. The function returns "1" for linear and "0" for log. Non-existent drawing areas are assumed to have a default scale of linear.

The current scale may be changed with chips_set_zscale.

Examples:

1.   chips> surface tabbed.data 0 150
     chips> chips_get_zscale()
     1
   

   The surface is plotted with a linear z-axis, as returned by the "chips_get_zscale" command.

3.12 chips_label

Adds a label to a drawing area.

Integer_Type chips_label(x,y,text)
Integer_Type chips_label(x,y,text,color)
Integer_Type chips_label(x,y,text,color,size)
Integer_Type chips_label(x,y,text,color,size,rotationAngle)

This is a S-Lang version of the ChIPS LABEL command. It adds the text to the current pane at the specified location (x,y), and the optional parameters control the color, size, and rotation angle of the label.

Table 3.4: Arguments for chips_label

Name	Type	Default	Comment
x	Numeric		location of bottom left of text
y	Numeric		location of bottom left of text
text	String_Type		may contain TeX syntax
color	Integer_Type	_chips-$>$ defcolor
size	Numeric	1.0
rotationAngle	Numeric	0	degrees

The rotationAngle parameter specifies the counter-clockwise rotation of the text from the horizontal. The rotation occurs about the point specified by the x and y parameters.

The function returns a 0 on success and -1 on failure. If used with the wrong number of arguments, it prints a usage message:

  chips> chips_label(1)
  Usage: chips_label(x,y,text[,color[,rotationAngle,[size]]])
  chips_label(1);

3.12.1 Quoting the text

Since the backslash character (' $\backslash$') is used in S-Lang as a delimiter (as do printf and related functions in the C/C$+$$+$ stdio library), remember to use a double backslash for embedded Tex commands or font specifications. For example,

  chips> chips_label(0.5,0.5,"\\it {HELLO}")

will draw the label "HELLO" in italic when SM is the underlying plot engine. Similarly, the command

  chips> chips_label(0.2,0.2,"\"myLabel\"")

ensures that the label will be enclosed by double quotes. Make sure that both sets of quotes are closed at the end.

Examples:

1.   chips> clear
     chips> chips_label(0.5,0.5,"A label")
     0
   

   Here we mix ChIPS and S-Lang commands. The CLEAR command is used to remove any previous plots and set the axis limits to 0 and 1. Then we use the S-Lang command to add a label to the plot at (0.5,0.5).

2.   chips> chips_label(0.7,0.7,"A label",_chips->red,2,180)
     0
   

   This time the label is placed upside-down (i.e. rotated by 180), written in red, and has a size of 2.

3.   chips_clear();
     () = chips_label(0.2,0.5, "x = \\frac{y+z/2}{y^{2}+3}");
   

   This part of a S-lang script would clear the screen and then add the label to it. Note the use of a double backslash, as discussed in the "Quoting the text" section, above.

4.   chips> () = chips_label(0.2,0.2,"\\oe This \\rm is \\gr Greek");
   

   Here we use more TeX syntax in order to achieve mixed fonts in the same label. This command produces a label where the "This" text is in Old English font, the "is" text is in Roman font, and the "Greek" text is in the Greek font. See the ChIPS FONT command for more information on the available fonts.

3.13 chips_line

Adds a line to a drawing area.

Integer_Type chips_line(x1,y1,x2,y2)
Integer_Type chips_line(x1,y1,x2,y2,color)
Integer_Type chips_line(x1,y1,x2,y2,color,width)
Integer_Type chips_line(x1,y1,x2,y2,color,width,style)

This is a S-Lang version of the ChIPS LINE command. It draws a line from (x1,y1) to (x2,y2) in the current pane, and the optional parameters control the color, width, and linestyle. If a parameter is not specified, the value from the ChIPS state object is used instead.

The function returns a 0 on success and -1 on failure.

Table 3.5: Arguments for chips_line

Name	Type	Default	Comment
x1	Numeric		start of line
y1	Numeric		start of line
x2	Numeric		end of line
y2	Numeric		end of line
color	Integer_Type	chips.linecolor
width	Numeric	chips.linewidth
style	Numeric	chips.linestyle

The routine prints a usage message if used with the wrong number of arguments:

  chips> chips_line(1)
  Usage: chips_line(x1,y1,x2,y2[,color[,width[,style]]])
  chips_line(1);

Examples:

1.   chips> clear
     chips> set_state_defaults("chips")
     chips> chips_line(0,0,2,1)
     0
   

   Here we mix ChIPS and S-Lang commands. The CLEAR command is used to remove any previous plots and set the axis limits to 0 and 1. Then we use S-Lang commands to reset the values in the ChIPS state object and then to draw a line between (0,0) and (2,1).

2.   chips> clear
     chips> chips_line(0.1,0.1,0.9,0.1,_chips->red,1,_chips->dotdash)
     0
   

   This draws a horizontal red line, using the DOTDASH style and with a width of 1, between (0.1,0.1) and (0.9,0.1).

3.   chips_clear();
     chips.linecolor = _chips->red;
     chips.linewidth = 1;
     chips.linestyle = _chips->dotdash;
     () = chips_line(0.1,0.1,0.9,0.1);
   

   This part of a S-lang script has the same result as the previous example. This time the ChIPS state object is used to set the line parameters, rather than supplying them as optional parameters to the "chips_line()" function. Note that any following lines will also be drawn in red using the DOTDASH style until the ChIPS state object is changed, or the attributes are explicitly specified in the chips_line() call.

3.14 chips_pickpoints

Read 1 or more cursor positions from ChIPS.

Float_Type chips_pickpoints( [numpoints] )

This is the S-Lang version of the PICKPOINTS command. It allows a user to select 1 or more positions on a plot and returns the values in an array. The number of points is determined by the optional parameter numpoints; if not supplied it defaults to 1, otherwise it must be an integer with value greater than 0. On error, the routine returns NULL.

The return value is a one-dimensional array of floats where the selected points are stored in $(x_i,y_i)$ order. The routines reshape() and _reshape() from the S-Lang Run-Time Library can be used to change the format of the data as shown in the examples below; see "ahelp reshape" and "ahelp _reshape" for more information.

Examples:

1. chips> clear
   chips> limits 0 10 0 5
   chips> pnts = chips_pickpoints
   
   Click LMB or tap spacebar to pick point.
   Click RMB or type 'q' to quit picking points.
   
   Point picked: (5.656155, 4.306668)
   chips> print(pnts)
   5.65615
   4.30667
   chips> print(pnts[0])
   5.65615
   chips> print(pnts[1])
   4.30667
   chips> typeof(pnts)
   Array_Type
   chips> _typeof(pnts)
   Float_Type
   

   Here we create a plot with limits 0-10 and 0-5 on the X and Y axes and then call the S-Lang version of PICKPOINTS. Since we only wanted to select one point, we did not supply an argument - or "()"'s - to the chips_pickpoints() call.

   The screen output and behaviour is the same as if PICKPOINTS had been used. The difference is that the selected values are returned as a one-dimensional array; the variable pnts is used to store the data.

2. chips> clear
   chips> limits 0 10 0 5
   chips> pnts = chips_pickpoints(3)
   
   Click LMB or tap spacebar to pick point.
   Click RMB or type 'q' to quit picking points.
   
   Point picked: (8.651068, 4.245632)
   Point picked: (5.343642, 2.890631)
   Point picked: (5.031129, 2.133974)
   chips> print(pnts)
   8.65107
   4.24563
   5.34364
   2.89063
   5.03113
   2.13397
   chips> vmessage("Point 1 = %f,%f",pnts[0],pnts[1])
   Point 1 = 8.651068,4.245632
   chips> vmessage("Point 2 = %f,%f",pnts[2],pnts[3])
   Point 2 = 5.343642,2.890631
   chips> vmessage("Point 3 = %f,%f",pnts[4],pnts[5])
   Point 3 = 5.031129,2.133974
   

   Here we ask for three points rather than 1 (and so need to use "()" around the argument). Note that the output array is still one-dimensional, with the values stored in $(x_i,y_i)$ order.

3. chips> clear
   chips> limits 100 120 200 300
   chips> pnts = chips_pickpoints(4)
   
   Click LMB or tap spacebar to pick point.
   Click RMB or type 'q' to quit picking points.
   
   Point picked: (106.052490, 277.100006)
   Point picked: (105.739983, 227.054245)
   Point picked: (115.010376, 237.796600)
   Point picked: (110.426857, 209.720001)
   chips> reshape(pnts,[4,2])
   chips> print(pnts)
   106.052 277.1
   105.74 227.054
   115.01 237.797
   110.427 209.72
   chips> xpnts = pnts[*,0]
   chips> print(xpnts)
   106.052
   105.74
   115.01
   110.427
   chips> ypnts = pnts[*,1]
   chips> print(ypnts)
   277.1
   227.054
   237.797
   209.72
   

   Here we use the reshape() routine to change the format of the returned array from one-dimensional - with eight elements - to a two-dimensional array with 4x2 elements.

   We then use the array-indexing capabilities of S-Lang to take a "slice" of this array to extract just the x (xpnts) and y (ypnts) values.

   Alternatively we could have used

   $$pos1 = pnts[0,*]$$ (3.1)

   
   

   to create a two-element array pos1 which contains the x and y coordinates of the first point in the list.

4. chips> clear
   chips> limits 0 10 0.01 10
   chips> log y
   chips> lpnts = chips_pickpoints(2)
   
   Click LMB or tap spacebar to pick point.
   Click RMB or type 'q' to quit picking points.
   
   Point picked: (2.192879, -1.239185)
   Point picked: (9.458393, -0.487297)
   chips> print(lpnts)
   2.19288
   -1.23919
   9.45839
   -0.487297
   chips> i=[1,3]
   chips> writeascii(stdout,lpnts[i],10^lpnts[i])
   -1.23919 0.0576521
   -0.487297 0.325614
   

   Here we use a plot in which one of the axes (the Y axis) has log spacing. The return values for that axis are still in logarithmic units (which is why they are both less than 0). The writeascii() call writes out the y values of the selected points in the first column, and the corresponding linear values in the second column. We take advantage of S-Lang's array-indexing mechanism to restrict the output to just use the second and fourth elements (ie "$[$1,3$]$") of the lpnts array.

5. The previous examples have shown chips_pickpoints() being used from the ChIPS prompt. It can also be used from a S-Lang script, as the following example shows.

     unix% cat pick.sl
     % load the ChIPS functions
     require("chips");
   
     % turn off redrawing until the plot is finished
     () = chips_auto_redraw(0);
   
     % set the limits
     () = chips_set_xrange(0,10);
     () = chips_set_yrange(10,20);
   
     % plot some data
     variable x = [1:9];
     variable y = x + 10;
     chips.symbolstyle = _chips->none;
     chips.linestyle   = _chips->simpleline;
     () = curve(x,y);
     () = chips_auto_redraw(1);
   
     % call pickpoints
     variable out = chips_pickpoints(3);
     if ( andelse { out == NULL }
                  { length(out) != 6 } )
       error( "Did not select 3 points from the plot" );
   
     print("\nYou selected the following values:");
     variable i;
     foreach ( [1:3] ) {
       i = ();
       () = printf( "  point %d  x = %4.2f  y = %5.2f\n",
                    i, out[2*(i-1)], out[2*(i-1)+1] );
     }
     % end of script
   

   which, when run using slsh, will create output something like (depending on the actual points selected):

     unix% slsh pick.sl
   
     Click LMB or tap spacebar to pick point.
     Click RMB or type 'q' to quit picking points.
   
     Point picked: (3.468972, 15.146487)
     Point picked: (6.880163, 14.975967)
     Point picked: (9.093795, 18.173878)
   
     You selected the following values:
       point 1  x = 3.47  y = 15.15
       point 2  x = 6.88  y = 14.98
       point 3  x = 9.09  y = 18.17
   

3.15 chips_redraw

Redraws all plotting objects.

chips_redraw()

This is a S-Lang version of the ChIPS REDRAW command. Since it has no parameters, it can be called without the "()".

Use the chips_auto_redraw() command to set/unset the automatic redrawing of plots.

Examples:

1.   chips> chips_redraw
   

   Redraws everything in the plotting window.

2.   chips_redraw;
   

   As the first example, but done in a S-Lang script.

3.16 chips_set_pane

Set the current pane/drawing area.

Integer_Type chips_set_pane(which)
Integer_Type chips_set_drawing_area(which)

This is a S-Lang version of the ChIPS D command. It sets the current pane/drawing area; the two commands are identical. The numbering scheme of the panes is described in "ahelp chips_split".

The function returns a 0 on success and -1 on failure.

Table 3.6: Arguments for chips_set_pane

Name	Type	Comment
which	Integer_Type	number of the pane

If "which" exceeds the number of panes, the function returns a -1 and the current pane is unchanged.

Examples:

1.   chips> chips_split(2,3)
     6
     chips> chips_set_pane(2)
     0
   

   Here we create 6 panes, arranged in a 2 by 3 grid, and set the current pane to be the second one. This example could also be done using the optional whichPane parameter of chips_split():

     chips> chips_split(2,3,2)
     0
   

2.   () = chips_split(2,3);
     () = chips_set_pane(2);
   

   As the first example, but done in a S-Lang script. Here the return values are ignored.

3.17 chips_set_xrange

Set the upper and/or lower x-axis limits of the plot

Integer_Type chips_set_xrange(range)

Sets the limits of the plot's x-axis.

Table 3.7: Arguments for chips_set_xrange

Name	Type	Options	Default
range	Numeric	a pair of numeric values, "auto", or "*" (see below)	auto

If a pair of values is used for the "range", it may either be two comma-separated values (minimum and maximum), or a single array whose first two elements will be used as minimum and maximum. The "*" character indicates no change in the current limit, while "auto" allows the underlying plotting package to select the limit value; both of these options must be quoted to work properly.

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 function returns a 0 on success and -1 on failure.

The current limits may be found with chips_get_xrange.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_set_xrange(749,890)    
     0
   

   A data file is read in and plotted, then the minimum and maximum values of the x-axis are changed.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_xrange(20,"*")
     0
     chips> chips_set_xrange("auto","auto")
     0
   

   First, the lower limit of the plot is changed to 20, while the original upper limit is retained. The second "chips_set_xrange" command has the plotting package determine the best limits for the plot.

3.18 chips_set_xscale

Set the x-axis scale

Integer_Type chips_set_xscale(scale)

Sets the scale of the plot's x-axis.

Table 3.8: Arguments for chips_set_xscale

Name	Type	Options	Comment
scale	Numeric	0, 1, "linear", "log", _chips-$>$log, _chips-$>$linear	logarithm is base 10

When invoked with no argument, the function will reset the scale to linear.

The function returns a 0 on success and -1 on failure.

The current scale may be found with chips_get_xscale.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_set_xscale("log")    
     0
   

   A data file is read in and plotted, then the x-axis is changed to log scale. Equivalent commands are:

     chips> chips_set_xscale(0)
     chips> chips_set_xscale(_chips->log)
   

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_xscale(0)
     Warning: negative and zero values ignored in log scale
     0
     chips> chips_set_xscale(_chips->linear)
     0
   

   First, the x-axis is set to logarithmic scale. The second "chips_set_xscale" command changes it back to a linear scale; equivalent commands are:

     chips> chips_set_xscale(1)
     chips> chips_set_xscale("linear")
     chips> chips_set_xscale()
   

3.19 chips_set_yrange

Set the upper and/or lower y-axis limits of the plot

Integer_Type chips_set_yrange(range)

Sets the limits of the plot's y-axis.

Table 3.9: Arguments for chips_set_yrange

Name	Type	Options	Default
range	Numeric	a pair of numeric values, "auto", or "*" (see below)	auto

If a pair of values is used for the "range", it may either be two comma-separated values (minimum and maximum), or a single array whose first two elements will be used as minimum and maximum. The "*" character indicates no change in the current limit, while "auto" allows the underlying plotting package to select the limit value; both of these options must be quoted to work properly.

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 function returns a 0 on success and -1 on failure.

The current limits may be found with chips_get_yrange.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_set_yrange(-10,150)
     0
   

   A data file is read in and plotted, then the minimum and maximum values of the y-axis are changed.

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_yrange(10,"*")
     0
     chips> chips_set_yrange("auto","auto")
     0
   

   First, the lower limit of the plot is changed to 10, while the original upper limit is retained. The second "chips_set_yrange" command has the plotting package determine the best limits for the plot.

3.20 chips_set_yscale

Set the y-axis scale

Integer_Type chips_set_yscale(scale)

Sets the scale of the plot's y-axis.

Table 3.10: Arguments for chips_set_yscale

Name	Type	Options	Comment
scale	Numeric	0, 1, "linear", "log", _chips-$>$log, _chips-$>$linear	logarithm is base 10

When invoked with no argument, the function will reset the scale to linear.

The function returns a 0 on success and -1 on failure.

The current scale may be found with chips_get_yscale.

Examples:

1.   chips> input=readfile("/data/chips/phas.fits")
     chips> curve x input.x y input.y
     chips> chips_set_yscale("log")    
     0
   

   A data file is read in and plotted, then the y-axis is changed to log scale. Equivalent commands are:

     chips> chips_set_yscale(0)
     chips> chips_set_yscale(_chips->log)
   

2.   chips> spec=readfile("/data/threads/Chips/data1.pha")
     chips> curve x spec.channels y spec.counts                     
     chips> chips_set_yscale(0)
     Warning: negative and zero values ignored in log scale
     0
     chips> chips_set_yscale(_chips->linear)
     0
   

   First, the y-axis is set to logarithmic scale. The second "chips_set_yscale" command changes it back to a linear scale; equivalent commands are:

     chips> chips_set_yscale(1)
     chips> chips_set_yscale("linear")
     chips> chips_set_yscale()
   

3.21 chips_set_zrange

Set the upper and/or lower z-axis limits of the plot

Integer_Type chips_set_zrange(range)

Sets the limits of the plot's z-axis.

Table 3.11: Arguments for chips_set_zrange

Name	Type	Options	Default
range	Numeric	a pair of numeric values, "auto", or "*" (see below)	auto

If a pair of values is used for the "range", it may either be two comma-separated values (minimum and maximum), or a single array whose first two elements will be used as minimum and maximum. The "*" character indicates no change in the current limit, while "auto" allows the underlying plotting package to select the limit value; both of these options must be quoted to work properly.

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 function returns a 0 on success and -1 on failure.

The current limits may be found with chips_get_zrange.

Examples:

1.   chips> surface tabbed.data 0 150
     chips> chips_set_zrange(-10,140)
     0
   

   The minimum and maximum values of the z-axis for a surface plot are changed.

2.   chips> surface tabbed.data 0 100
     chips> chips_set_zrange(-25,"*")
     0
     chips> chips_set_zrange("auto","auto")
     0
   

   First, the lower limit of the plot is changed to -25, while the original upper limit is retained. The second "chips_set_yrange" command has the plotting package determine the best limits for the plot.

3.22 chips_set_zscale

Set the z-axis scale

Integer_Type chips_set_zscale(scale)

Sets the scale of the plot's z-axis.

Table 3.12: Arguments for chips_set_zscale

Name	Type	Options	Comment
scale	Numeric	0, 1, "linear", "log", _chips-$>$log, _chips-$>$linear	logarithm is base 10

When invoked with no argument, the function will reset the scale to linear.

The function returns a 0 on success and -1 on failure.

The current scale may be found with chips_get_zscale.

Examples:

1.   chips> chips_set_zscale("log")    
     0
   

   The z-axis for a plot is changed to log scale. Equivalent commands are:

     chips> chips_set_zscale(0)
     chips> chips_set_zscale(_chips->log)
   

2.   chips> chips_set_zscale(0)
     0
     chips> chips_set_zscale(_chips->linear)
     0
   

   First, the z-axis is set to logarithmic scale. The second "chips_set_zscale" command changes it back to a linear scale; equivalent commands are:

     chips> chips_set_zscale(1)
     chips> chips_set_zscale("linear")
     chips> chips_set_zscale()
   

3.23 chips_split

Creates multiple drawing areas.

Integer_Type chips_split(numXpanes,numYpanes[,whichPane])

This is a S-Lang version of the ChIPS SPLIT command. It creates multiple drawing areas (also called panes), optionally selecting which one is to be the "current" one ("whichPane"). The command splits the display up into "numXpanes" by "numYpanes" drawing areas. These areas (or panes) are numbered sequentially from the upper-left, going down the rows, so

  chips> chips_split( 2, 3, 3 )
  6
  chips> chips_line( 0, 0, 1, 1 )
  0

splits the display into 2 columns of three rows and sets the current pane to be the bottom-left one (number 3). A line is then drawn in this pane.

The function returns the number of panes actually created.

Table 3.13: Arguments for chips_split

Name	Type	Default	Comment
numXpanes	Integer_Type		number of columns
numYpanes	Integer_Type		number of rows
whichPane	Integer_Type	1

The routine prints a usage message if used with the wrong number of arguments:

  chips> chips_split(1)
  Usage: chips_split(nx,ny[,drawing_area_selected])
  chips_split(1);

Examples:

1.   chips> chips_split(1,2)
     2
     chips> split gap 0.1
   

   Here we mix ChIPS and S-Lang commands. The chips_split() call creates two drawing areas, stacked vertically. We then use a ChIPS SPLIT command to add a gap between the two panes.

2.   () = chips_split(1,2);
     () = chips_eval( "split gap 0.1" );
   

   This is a S-Lang version of the previous example.

3.   chips_clear;
     () = chips_split(2,2,3);
     () = chips_label(0.5,0.5,"Pane: 3");
   

   This set of commands will clear the screen, create 4 drawing areas (ina 2 by 2 grid) and add the text "Pane: 3" to the third (top right) one.

3.24 chips_version

Report the version of ChIPS as a number or string.

Ingteger_Type _chips_version
String_Type _chips_version_string

The ChIPS version number is accessible using either the "_chips_version" or "_chips_version_string" variables. This allows scripts to cleanly check for version conflicts. The variables are read-only.

Examples:

1.   chips> _chips_version
     30000
     chips> _chips_version_string
     3.0
   

   The version number can be accessed as either an integer or a string.