Introduction to ChIPS

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]")

Figure 1: Spectrum plot created by make_figure

[Version: full-size, PNG, postscript, PDF]

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

Figure 2: Modified spectrum plot

[Version: full-size, PNG, postscript, PDF]

Figure 2: Modified spectrum plot

The plot contents have been changed 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.

The ChIPS GUI makes it easy to modify the attributes of, and add annotations such as labels and lines to a, visualization. As described in the ChIPS GUI section of the 'Starting ChIPS' thread, the GUI can be displayed by

1. entering

   chips> show_gui()

   at the prompt,

2. or using the right-mouse-button menu in the ChIPS window and then selecting the Show GUI option.

The GUI can be closed down and re-started during a ChIPS session, or left running whilst you delete, create, and edit plots. For the plot shown in Figure 2, the ChIPS GUI looks like Figure 3.

Figure 3: ChIPS GUI

[Version: full-size]

Figure 3: ChIPS GUI

The curve has been selected in the GUI so that you can easily edit its attributes, such as line color or symbol style. Changes in the GUI are immediately made to the visualization, and any changes made from ChIPS are automatically updated in the GUI.

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

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

Figure 4: A lightcurve

[Version: full-size, PNG, postscript, PDF]

Figure 4: 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(r"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; this means that the string is preceeded by a r character to avoid it being interpreted as introducing a control character (see the Python documentation for String Literals for more information, noting that we use Python 2, not Python 3, in CIAO 4.8).

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

chips> set_curve(["err.*", False])

The above is a short-form, introduced in CIAO 4.2, which means the same:

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

Figure 5: Removing the error bars

[Version: full-size, PNG, postscript, PDF]

Figure 5: Removing the error bars

Both the upper and lower error bars from Figure 4 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 6.

Figure 6: A histogram

[Version: full-size, PNG, postscript, PDF]

Figure 6: 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.style", "solid", "fill.color","cornflower"])
chips> shuffle_histogram(chips_back)

which creates Figure 7. A range of fill patterns are available for histograms (and regions).

Figure 7: A filled histogram

[Version: full-size, PNG, postscript, PDF]

Figure 7: 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 and the opacity set to 0.5, as shown in Figure 8.

chips> add_histogram("hist_b.dat", ["dropline", True, "fill.style", "solid", "fill.color", "red", "fill.opacity", 0.5])
chips> shuffle_axis("ax1", chips_front)

Figure 8: Two filled histograms

[Version: full-size, PNG, postscript, PDF]

Figure 8: 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).

The patterns used for the histogram can be changed; here we change the solid fill to use diagonal lines for the two histograms, resulting in Figure 9.

chips> set_histogram("hist1", ["fill.style", "updiagonal"])
chips> set_histogram("hist2", ["fill.style", "downdiagonal"])

Figure 9: Two filled histograms (this time with lines)

[Version: full-size, PNG, postscript, PDF]

Figure 9: Two filled histograms (this time with lines)

The histograms have been filled with lines; the first histogram (blue) uses diagonal lines going from bottom left to top right (the updiagonal pattern) whereas the second histogram (red) is filled with lines from top left to bottom right (the downdiagonal pattern).

In CIAO 4.8 the PNG and JPEG outputs may swap the updiagonal and downdiagonal patterns (i.e. the PNG version of this plot uses the downdiagonal pattern for the first/blue histogram).

Image

In the following section we highlight some of the support for displaying image data in ChIPS.

chips> clear()
chips> make_figure("a4059_chandra.fits", "image")
chips> set_image(["depth", 50])
chips> add_colorbar(1.05, 0.5, ["orientation", "vertical"])
chips> set_plot(["rightmargin", 0.15, "topmargin", 0.15])

The resulting plot is shown in Figure 10.

The images are - by default - created with an axis pad value of 0 (other objects, such as curves, histograms and contours still use the axis.pad value). This means that the image may hide part of the axes, unless you change the limits or change the relative ordering of the image and axes, as we do above by lowering the depth of the image.

Figure 10: An image

[Version: full-size, PNG, postscript, PDF]

Figure 10: An image

The image is displayed using a linear scale, chosen to cover the full data range of the image. A colorbar has been added to the right-hand side of the plot to show the scaling of the pixel intensity values.

The right-hand margin of the plot is increased from the default value of 0.1 to 0.15 so that the colorbar labels do not fall off the edge of the display. Since the image is displayed with a fixed aspect ratio, we also change the top margin by the same amount so that the plot remains square.

The plot limits can be changed either from the ChIPS GUI or by interacting with the ChIPS window directly. For instance, the image can be scrolled around the plot by changing to the Pan mode and dragging around the image; alternatively the plot can be zoomed into using either the scroll wheel on your mouse (if one exists) or the + and - keys on your keyboard.

The same figure can be created using add_image with the following (note that we use the read_file command to read in the image since we will be accessing the pixel values below):

chips> clear()
chips> cr = read_file("a4059_chandra.fits")
chips> add_image(cr, ["depth", 50])
chips> add_colorbar(1.05, 0.5, ["orientation", "vertical"])
chips> set_plot(["rightmargin", 0.15, "topmargin", 0.15])
chips> set_plot_title("ABELL 4059")
chips> set_plot_xlabel("RA")
chips> set_plot_ylabel("DEC")

A number of colormaps are available, and can be selected by saying:

chips> set_image(["colormap", "heat"])

and the axes can be changed to display sexagesimal notation with

chips> set_xaxis(["tickformat", "ra"])
chips> set_yaxis(["tickformat", "dec"])

which creates Figure 11.

Figure 11: Changing the colormap of an image

[Version: full-size, PNG, postscript, PDF]

Figure 11: Changing the colormap of an image

The "heat" colormap is used to display the image; the colorbar scale has automatically changed to use it (from the grayscale used in Figure 10). The axis labels have been changed to display in sexagesimal, rather than decimal, notation.

We can change several attributes that control how the image is displayed; first we change from the default nearest-neighbor interpolation scheme to the bi-linear system:

chips> set_image(["interpolation", "bilinear"])

We also wish to change the display range of the image, so we extract the pixel image values from the crate object cr and then use several NumPy routines to check the distribution of the pixel values.

chips> ivals = copy_piximgvals(cr)
chips> ivals.min()
       0
chips> ivals.max()
       2517
chips> ivals.mean()
       162.261538462
chips> np.median(ivals)
       117.0

We can now change the threshold attribute of the image to change the display range; here we chose the values 100 to 2000.

chips> set_image(["threshold", [100, 2000]])

The result of these changes is shown in Figure 12.

Figure 12: Changing the interpolation and display range

[Version: full-size, PNG, postscript, PDF]

Figure 12: Changing the interpolation and display range

The display has been changed to use the "bilinear" interpolation scheme (the default is "neighbor", a nearest-neighbor scheme) and to restrict the display range to 100 to 2000.

Send straight to the printer

To print the current window to the default printer use the print_window call with no arguments (this assumes that the export.printdialog preference setting is false, which is the default value):

chips> print_window()

If the export.printdialog preference setting is set to true then this call will create a GUI which can be used to control the output.

Save as a file (PS, EPS, PDF, PNG, JPEG formats)

To save the current window as a postscript file, PNG file, and a JPG image (fig1.ps, fig1.png and fig1.jpg respectively):

chips> print_window("fig1")
chips> print_window("fig1.png")
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.

As when sending the plot straight to the printer, a GUI will be created if the printdialog preference is set to true.

Using a GUI to control the print output

If the export.printdialog preference setting is set to true (the default is false) then calling print_window will create a GUI which can be used to select the plot options. So

chips> print_window("fig1", ["printdialog", True])

will create Figure 20.

This dialog window can also be called up directly from the ChIPS window, via the right-mouse-button menu, or from the Print options in the ChIPS GUI, as discussed in the Starting ChIPS thread.

Figure 20: GUI for print_window

Figure 20: GUI for print_window

The GUI can be used to change the print options - such as output format, page size (for ps and PDF formats), margins, location of the output file, and more.

How are on-screen colors changed on print out?

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 19 shows the PNG output created by the call

chips> print_window("multiplot-final.png)

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

What else can be changed?

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.

These options can also be explored by using the GUI when calling print_window.

Using the make_script() command

The make_script command creates a Python script which can be used to re-create the current set of ChIPS plots. The commands are not guaranteed to be the same as those used to create the plots, unlike the binary format.

chips> make_script("intro.py")

The script can be read, and edited; the start of the file for this particular case looks like:

from pycrates import *     # import crates i/o routines
from pychips.all import *  # import chips hlui and advanced commands

### Data Templates
# The template variables below are used to specify the data needed for
# objects such as curves. The values may be substituted with other file
# names or data arrays as appropriate. It is the user's responsibility to
# ensure that data arrays are all the correct length, that provided column
# names exist, and that if files are provided, they contain the appropriate
# columns in the correct order. Note that the variables are provided in two
# flavors- as filenames and as data structures: the former makes use of the
# simpler file interface while the latter offers more flexibility.
class DataObj(): pass

MyCrate_1 = TABLECrate("intro.py.Data1_curve.fits")
MyData_1 = DataObj()  # data- intro.py.Data1_curve.fits
MyData_1.xx    = MyCrate_1.get_column("xx").get_values() 
MyData_1.yy    = MyCrate_1.get_column("yy").get_values() 

MyCrate_2 = TABLECrate("intro.py.Data2_curve.fits")
MyData_2 = DataObj()  # data- intro.py.Data2_curve.fits
MyData_2.xx    = MyCrate_2.get_column("xx").get_values() 
MyData_2.yy    = MyCrate_2.get_column("yy").get_values() 



open_undo_block()          # treat script as single command
clear()                    # remove all existing chips objects


# This script assumes that the user's default preferences were used
# to generate the output and were not changed- so the following 
# load_preferences() command is unnecessary. To guarantee that this
# script uses the correct settings to replicate the saved state, 
# uncomment out the following line.
# load_preferences("intro.py.prefs")

add_plot(0.15,0.55,0.90,0.90," title.halign=0.5 title.valign=0.5 title.label=\"Lightcurves of a Variable Source\"")
add_curve(MyData_1.xx, MyData_1.yy,'line.color=red symbol.style=circle id=crv1')
add_label(69607700, 0.095, "Curve 1", "id=lbl1")
...

This file can be used when starting ChIPS:

unix% chips intro.py

or from within a ChIPS session:

chips> execfile("intro.py")

Using the save_state() routine

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

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.

Note that load_state will delete any existing plots in the current ChIPS session and that the pre-existing visualization can not be restored using undo.

State files from recent CIAO releases can be loaded into CIAO 4.8, but files created in CIAO 4.8 may not be read back into earlier versions. If this is the case then the following error message will be raised:

chips> load_state("example.state")
chips ERROR: Unable to load incompatible state file (unsupported major version)

Using the File/Save As menu item of the GUI

The ChIPS GUI allows you to create either a Python file (output of make_script) or a binary state file (output of save_state) by using the File/Save As menu item.