make_figure

Context: chips

Synopsis

Create a basic plot of a curve, contour, image, or histogram (includes axis labels and a plot title).

Syntax

make_figure([id,] filename|Crate [,figuretype] [,attributes])

Description

The function arguments.

Argument	Description
id	A ChipsId structure identifying the item.
filename	The name of the file containing the data to display. This can include CIAO DataModel filters, such as "evt2.fits[energy=500:7000][cols sky]", to automatically filter the table before displaying it, or "evt2.fits[bin sky=::8]" for binning a table to an image.
Crate	A crate, returned either by read_file or a call to the TABLECrate or IMAGECrate constructor (see "ahelp crate").
figuretype	A string that identifies the type of figure to create. It should be one of "curve", "contour", "image", or "histogram". Wnen not specified it is set to "curve", "histogram", or "contour" based on the data. This means that "image" must always be specified if you want an image display.
attributes	Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The make_figure command creates a curve, contour, image, or histogram from the data provided. If an existing plot is current, it is cleared and the figure is drawn in that plot. If there is no current plot, one is created and the figure is placed in it.

Choice of figure type

By default, table data is used to create a curve and image data is used to create a contour. Specifying a figuretype overrides this behavior, e.g. to create an image or a histogram. When creating a histogram, the two columns are used as the bin center and the counts.

Axis labels

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 (without the path and virtual filter specfications).

Changing attribute values

The attributes option can be used to control figure characteristics. The attributes can be set to the ChIPS defaults, values provided in the make_figure command, or values from the user's preference file. Refer to the individual help files - "ahelp set_curve", "ahelp set_contour", "ahelp set_image", and "ahelp set_histogram" - for information on the attributes of each object.

Examples

Example 1

chips> make_figure("source.dat")

If the file "source.dat" contains

unix% cat source.dat
# alpha beta error
1 2 0.7
4 9 2.2
9 15 3.4

then the make_figure call will plot this as a curve with symmetrical y errors, since there are three columns in the input file. As the file contains a header line, the axis labels are set to "alpha" and "beta".

Example 2

chips> make_figure("flare.fits[cols time_bin,count_rate]")

Create a curve of the time_bin and count_rate columns from the file "flare.fits". The plot title is set to the value of the OBJECT keyword in "flare.fits" (if it exists).

Example 3

chips> make_figure("img.fits", "color=green thickness=2")

Create contours from the file "img.fits". Set the contour color to green and the thickness to 2.

If the image contains WCS information, then it will be used for the X and Y axes; in this case you may wish to change the tick label format to use sexagesimal notation by saying:

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

Example 4

chips> make_figure("img.fits", "image", "colormap=hsv")
chips> set_xaxis(["tickformat", "ra"])
chips> set_yaxis(["tickformat", "dec"])
chips> add_colorbar(1.05, 0.5, ["orientation", "vertical"])

Display the contents of img.fits as an image, using the hsv colormap to color the pixels. A vertical colorbar is added to the right of the image.

Example 5

chips> make_figure("peak.fits[cols energy,counts]", "histogram",
"line.style=shortdash line.color=yellow")

Create a histogram from the file "peak.fits" with a short-dashed yellow line.

Example 6

chips> cr = read_file("flare.fits[cols time_bin,count_rate]")
chips> make_figure(cr)

Read the columns time_bin and count_rate into the crate (cr) using the Crates' read_file() command, and then use this to create a plot of the data. In this case, since the data is tabular then the data will be plotted as a curve.

Example 7

chips> cr = read_file("img.fits")
chips> make_figure(cr, "image", "colormap=hsv")
chips> set_xaxis(["tickformat", "ra"])
chips> set_yaxis(["tickformat", "dec"])
chips> add_colorbar(1.05, 0.5, ["orientation", "vertical"])

Here we read the image "img.fits" via the Crates read_file command, and send the return value (a crate) to make_figure.

Supported World Coordinate Systems

WCS-TAN support

At present the only supported World Coordinate System for displaying data in ChIPS is the tangent-plane projection; namely WCS-TAN. Using an unsupported system will result in a warning message and the data will be displayed using the physical or - if it does not exist, logical - system.

Bugs

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.