Introduction to ChIPS

Getting Started

The Starting ChIPS thread describes how to start ChIPS.

The data used in this thread is available in the chips_data.tar.gz file.

unix% ls -1 chips/intro/
curve_1.fits
curve_2.fits
example.state
hist.dat
hist_b.dat
lc.fits
spectrum.fits

Setting Preferences

After starting the ChIPS session, the following preferences were set to control the output size of the plots and hardcopies:

chips> set_preferences(["window.width", "500", "window.height", "500"])
chips> set_preferences(["export.pagewidth", "500", "export.pageheight", "500", "export.pageunits", "pixels"])

The Printing section of this thread explains how the figures in this thread were created.

Basic Plotting

The make_figure command creates a curve, contour, or histogram from the data provided. It is a convenient wrapper for the add_curve, add_histogram, add_contour, and supporting commands. Axis labels and units are drawn if the information is available in the input file. Plot titles are set to the value of the file keyword OBJECT or TITLE, or from the input filename.

Spectrum

In this example, a FITS file containing a spectrum is used as input to make_figure, which creates Figure 1:

chips> make_figure("spectrum.fits[cols channel,counts]")

[Version: full-size, postscript]

Figure 1: Spectrum plot created by make_figure

The channels and counts columns from spectrum.fits are plotted on the x and y axes respectively. The name and units of the axes were taken from the FITS file column information, and the plot title is set to the OBJECT header keyword value.

The same figure can be created using add_curve by saying:

chips> clear()
chips> add_curve("spectrum.fits[cols channel,counts]")
chips> set_plot_title("CAS A, CHIP S3")
chips> set_plot_xlabel("CHANNEL (channel)")
chips> set_plot_ylabel("COUNTS (count)")

The plot can be further customized with the set_curve command. The following change the range of the x-axis, the line color, and the symbol size. The result is shown in Figure 2.

chips> limits(X_AXIS, 0, 250)
chips> set_curve(["line.color","olive", "symbol.size", 2]) 

[Version: full-size, postscript]

Figure 2: Modified spectrum plot

The plot contents have been chamged from Figure 1: the line connecting the points of the curve is now drawn in olive, the symbol sizes are smaller, and the X-axis has been zoomed in to the range 0 to 250.

---

Lightcurve

A similar command can be used with a lightcurve file. Before plotting the lightcurve, clear the ChIPS window (or use add_window to create a new window), shown in Figure 3.

chips> clear()
chips> make_figure("lc.fits[cols time,count_rate,count_rate_err]","line.color=red err.style=cap err.color=plum")

[Version: full-size, postscript]

Figure 3: A lightcurve

The third column given to make_figure (count_rate_err) is used as symmetrical Y errors; see ahelp add_curve for more information on plotting errors. Also, several attributes are given in an attribute string, rather than as a list of values as used with the set_curve command above.

The same figure can be created using add_curve with the following:

chips> add_window()
chips> add_curve("lc.fits[cols time,count_rate,count_rate_err]","line.color=red err.style=cap err.color=plum")
chips> set_plot_title("47 TUC")
chips> set_plot_xlabel("TIME (s)")
chips> set_plot_ylabel("COUNT\_RATE (count/s)")

chips> add_window;
chips> add_curve("lc.fits[cols time,count_rate,count_rate_err]","line.color=red err.style=cap err.color=plum");
chips> set_plot_title("47 TUC");
chips> set_plot_xlabel("TIME (s)");
chips> set_plot_ylabel("COUNT\\_RATE (count/s)");

The underscore character in the y-axis label has been preceeded by a \ character to avoid it being interpreted as the LaTeX start subscript marker.

You can toggle the error-bar display - error up, error down, or both. The following command creates Figure 4.

chips> set_curve(["err.down", 0, "err.up", 0])

[Version: full-size, postscript]

Figure 4: Removing the error bars

Both the upper and lower error bars from Figure 3 have been turned off. The Y-axis retains the same range as before because the automatic-limits calculation does not take into account whether the error bars are hidden or not.

---

Histogram

ASCII data can also be used as input. The make_figure "figuretype" argument is set to "histogram" to force the figure to be drawn as a histogram.

chips> !less hist.dat 
      40560        36.3
      42438        34.7
      44316        26.3
      46194        22.9
      48071        22.1
      49949        13.1
      50888        14.4
...

chips> clear()
chips> make_figure("hist.dat","histogram")

The resulting plot is shown in Figure 5.

[Version: full-size, postscript]

Figure 5: A histogram

The bins widths have been automatically calculated from the first column, which is assumed to give the center of each bin.

The same figure can be created using add_histogram with the following:

chips> add_window()
chips> add_histogram("hist.dat")
chips> set_plot_title("hist.dat")
chips> set_plot_xlabel("col1")
chips> set_plot_ylabel("col2")

To fill the bins with the color "cornflower blue", say:

chips> set_histogram(["fill.visible", 1,"fill.color","cornflower"])
chips> shuffle_histogram(chips_back)

which creates Figure 6.

[Version: full-size, postscript]

Figure 6: A filled histogram

The histogram is now filled by a light-blue color. The shuffle_histogram command is used to make sure that the tick marks on the X axis are not obscured by the histogram (it makes sure that the histogram is drawn before the X axis).

The following commands add a second histogram with vertical lines drawn at the edge of each bin. In this histogram the fill color is set to red, as shown in Figure 7.

chips> add_histogram("hist_b.dat",["dropline", 1, "fill.visible", 1,"fill.color","red"])
chips> shuffle_axis("ax1", chips_front)

[Version: full-size, postscript]

Figure 7: Two filled histograms

The second histogram has been added to the plot. Since it also is drawn with a solid fill we change the order that the objects are drawn with the shuffle_axis command; rather than shift the order of the histograms, we move the X axis so that it is drawn last, so preserving the relative order of the two histograms (i.e. we want to keep the red histogram drawn on top of the blue one).

Note that, in CIAO 4.0, the hardcopy versions of filled histograms can contain artifacts. These artifacts are visible in the postscript versions of both Figure 6 and Figure 7.

For more information on the use of curves and histograms see the threads:

• drawing lines between sets of (x,y) points
• using symbols to draw sets of (x,y) points
• displaying histogram data

Customizing the Figure

ChIPS allows users to control the appearance and behavior of objects - such as windows, curves, lines, contours, and axes - via configurable attribute settings. For instance, labels have font, color, font size, font style, angle, and alignment attributes. The attribute value can be set when the object is created or modified afterwards with a "set" command.

A set command exists for every ChIPS object:

• set_axis (there are also set_xaxis and set_yaxis commands)
• set_contour
• set_current
• set_curve
• set_frame
• set_histogram
• set_label
• set_line
• set_plot
• set_point
• set_preferences
• set_preference
• set_region
• set_window

As an example, if you have a curve and wish to change it to be drawn with red circles, connected by a green dottted line, you can say:

chips> set_curve(["symbol.color","red","symbol.style","circle","line.color","green","line.style","dot"])

The undo() and redo() routines allow you to easily recover from accidental or unwanted changes when changing attributes.

There are a few values that cannot be accessed via a set_<object> command. The most frequently-used of these are:

• set_plot_title: add a title to the plot
• set_plot_xlabel: label the x-axis
• set_plot_ylabel: label the y-axis

The characteristics of the labels and title may be modified by set_plot and set_axis:

chips> set_plot(["title.font", "courier", "title.fontstyle", "bold"])
chips> set_axis(["label.fontstyle", "italic", "label.size", 20])

The set_axis command operates on both axes by default. An axis id can be specified to modify the x or y-axis, or use the set_xaxis and set_yaxis commands instead.

The ChIPS Concept pages have more information on how to set attributes and allowed attribute values.

Overplotting Two Datasets

One limiting feature of make_figure is that it clears the current plot area before creating the figure; this means the make_figure cannot be used to add extra curves or histograms to an existing plot. It can be used to create the first curve, but then add_curve (or another add command) much be used to include additional curves.

To display two datasets in the same drawing area, simply use two add_curve commands. An attribute list is used to change the color and style of the lines, to tell them apart easily.

chips> clear()
chips> add_curve("curve_1.fits[cols time,count_rate]","line.color=red")
chips> add_curve("curve_2.fits[cols time,count_rate]","line.color=purple line.style=longdash")

When the second curve is added, the y-axis is adjusted automatically to accomodate the full range of data, as shown in Figure 8.

[Version: full-size, postscript]

Figure 8: Two curves in the same plot

The second curve - drawn using the purple, dashed, line - has been added to the same plot as the first curve.

We now add some descriptive text to the plot:

chips> set_plot_title("Lightcurves of a Variable Source")
chips> set_plot_xlabel("Time (s)")
chips> set_plot_ylabel("Count Rate (s^{-1})")

We finish off by changing the angle and alignment of the tick labels on the X-axis. The axis-label offset is also adjusted so that the numeric tick labels do not overlap the axis label. Since this moves the axis label close to the bottom of the window, we increase the size of the bottom margin of the plot. The result is shown in Figure 9.

chips> set_xaxis(["ticklabel.angle","315","ticklabel.halign","left"])
chips> set_xaxis(["offset.parallel",-0.1,"offset.perpendicular",65])
chips> set_plot(["bottommargin",0.2])

[Version: full-size, postscript]

Figure 9: Customising the plot

The X-axis has been adjusted so that the tickmark labels are visible by rotating them, moving the axis label further from the axis, and re-sizing the plot by increasing the size of the bottom margin.

Plotting Two Datasets Side-by-Side

It is also possible to create multiple plotting areas within a ChIPS window, if you want the curves to be side-by-side instead of overlaid. This is done with the split command.

Note that split is only one method of creating multiple plotting areas in ChIPS. Another is the strip_chart command, which can create an arrangement of plotting areas with different sizes and synchronized axes. It is also possible to create and arrange multiple plotting areas with the add_plot and move_plot commands, but using split or split_chart is much simpler. Further examples of these techniques are available in the creating and using multiple plots thread.

If no argument is given, a 2 x 1 grid is created with no gap between the plotting areas. For this example, we create a 2 x 1 grid with a small gap:

chips> clear()
chips> split(2, 1, 0.05)

[Version: full-size, postscript]

Figure 10: Two empty plot areas

There are now two plot areas (or "plots") that can be used for displaying curves, histograms, or contours. The output of the info command, shown below, shows that the top plot - which has coordinates of (0.15,0.55) to (0.90,0.90) - is called plot1, whilst the bottom plot is called plot2. The coordinate system used for plot positions has (0,0) at the bottom-left and (1,1) at the top right of the frame.

There are now two plots, as shown in Figure 10; the plot named "plot1" is current:

chips> print info()
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.55)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.50)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]

chips> print info_current()
Window [win1]
  Frame [frm1]
    Plot [plot1]
    Coord Sys [Plot Normalized]

In the commands below, the first curve is put in the current plot (plot1, the upper plot). It is then necessary to specify where the second curve should go, which we do by using the current_plot command:

chips> add_curve("curve_1.fits[cols time,count_rate]")

chips> current_plot("plot2")
chips> add_curve("curve_2.fits[cols time,count_rate]")

The result is shown in Figure 11.

[Version: full-size, postscript]

Figure 11: Adding curves to the plots

The top plot contains the data from the file curve_1.fits and the bottom plot the file curve_2.fits.

Various modifications are now made to the plots. Note that multiple objects can be modified at once by setting the currency to "all".

chips> current_plot("all")
chips> set_curve(["line.color","red","symbol.style","circle"])

chips> set_plot_ylabel("Count Rate (cts/s)")
chips> set_plot_title("plot1","Lightcurves of a Variable Source")
chips> set_plot_xlabel("plot2", "Time (s)")

chips> current_plot("plot1")
chips> add_label(6.96077e+07, 0.095, "Curve 1")
chips> current_plot("plot2")
chips> add_label(6.96077e+07, 0.08, "Curve 2")

The result is shown in Figure 12.

[Version: full-size, PNG, postscript]

Figure 12: Annotating the plots

Customisations can be made to each plot individually, such as adding the labels Curve 1 and Curve 2, or to both at the same time, such as the Y-axis label or changing the attributes of the curves.

Printing

The print_window command prints the contents of the window to a file (if a filename is specified) or to the printer. Available formats are PS (the default setting), EPS, PDF, PNG, and JPG.

Print the current window to the default printer:

chips> print_window()

Save the current window as a postscript file and a JPG image (fig1.ps and fig1.jpg respectively):

chips> print_window("fig1")
chips> print_window("fig1", ["format","jpg"])

The first print_window command uses the default format value. This is "ps", unless the user has changed it with a set_preference command.

The default color value for most items is set to default, which means that it will appear in white on screen, but be in black in hardcopy form (i.e. any format created by the print_window form). In this thread, the figures show the screen output (and so have a black background with white lines), and the postscript versions of the plot have the reverse of this (black lines on a white background). The "PNG" link in Figure 12 shows the PNG output created by the call

chips> print_window("multiplot-final",["format","png"])

and so has a white background with lines drawn in black (other than the curve line, which was explicitly changed to red).

There are a number of attributes to the print_window command which control the appearance of the output plot: page size, margins, color system, etc. Refer to the help file for a list.

Saving and Restoring the Session

The save_state command saves the current ChIPS session into a platform-independent state file.

chips> save_state("intro.state")

chips> save_state("intro.state");

The saved session can be restored with the load_state command:

chips> load_state("intro.state")

The state file is in binary format - and so is not human readable - and includes the data needed to re-create the visualization, as well as a record of the history buffer, so you can use undo() and redo() even if the state file has been loaded into a new ChIPS session, even on a different machine.

The chips_data.tar.gz data file contains the example.state file which will re-create Figure 12 if loaded into ChIPS using:

chips> load_state("example.state")

Note that this will delete any existing plots in the current ChIPS session.