add_curve

Context: curves

Synopsis

Creates a curve (a set of two-dimensional points optionally marked by points or connected by lines)

Syntax

add_curve([ChipsId,] filename [, transform [, attributes]])
add_curve([ChipsId,] TABLECrate [, transform [, attributes]])
add_curve([ChipsId,] x, y [, transform [, attributes]])
add_curve([ChipsId,] x, y, error_list|None [, transform [, attributes]])
add_curve([ChipsId,] x, y, error_list|None, limits_list|None [,
transform [, attributes]])

Description

ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
TABLECrate/filename - input data, specified as a filename or a TABLECrate ("ahelp crates")
x - array of x data points
y - array of y data points
error_list - optional list of up to four error arrays. One array = symmetrical y errors. Two arrays = ydown and yup errors. Three arrays = ydown, yup, and xdown errors. Four arrays = ydown, yup, xdown, and xup errors.
limits_list - optional list of upper and/or lower limits. The list may be empty, y limits, or y and x limits.
transform - a Crates transform object used to convert the input (x,y) values into the display values.
attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

The add_curve command creates a curve whose attributes are specified by user preferences or in an attribute list. The new curve becomes current by default; providing a ChipsId overrides the currency state. A curve needs a minimum of a pair of numeric data arrays of the same length to plot.

If an existing plot is current, the curve is added to that plot. If there is no current plot, one is created and the curve is placed in it. To overplot curves, simply add them all to the same plot.

Up to six additional data columns may be provided as error and limits information. The error and limits information is interpreted based on how many columns are supplied to the command, as described above. On account of this, an entry for the error_list array must be provided in order to include limits data. If no error_list is needed, the value "None" may be used.

Customizing the Curve

There are several attributes that control the curve characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_curve command, or values from the user's preference file.

The attributes may also be modified with the set_curve command at any time; see "ahelp set_curve" and "ahelp setget" for more information.

Please see the section "Curve Preferences and Attributes" below the examples for a list of the curve preferences.

Example 1

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

Plot the time versus count_rate columns from the FITS file "lc.fits". The Data Model virtual filter syntax "[cols time, count_rate]" is used to select the X and Y columns from the file.

Example 2

chips> add_curve("lc.fits[cols time, count_rate]", ["line.color","red"])

Plot the time versus count_rate columns from the FITS file "lc.fits", and draw the lines between the points in red.

Example 3

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

Plot the time versus count_rate columns, and use the stat_err column as symmetric Y errors.

Example 4

chips> add_curve("lc.fits[cols time, count_rate,
stat_err]",["line.color", "red", "err.color", "coral", "symbol.style",
"circle", "symbol.size", 6])

Repeat the previous example, this time overriding several of the preference settings for curves.

Example 5

chips> dat = read_file("lc.fits[cols time, rate, error]")
chips> add_curve(dat)

Read in the time, rate, and error columns from a file using the Crates routine read_file, then plot the data.

Example 6

chips> x = np.arange(11)
chips> add_curve(x, x*x)

Plot the curve y = x^2 for the integer values 0 to 10.

Example 7

chips> z = np.arange(10)
chips> add_curve(z, z-4, [z*0.2, z*0.1])

Create a curve with assymetric Y error bars.

Example 8

chips> x = np.arange(0,10,0.1)
chips> set_preference("curve.symbol.style", "none")
chips> add_curve(x, np.sin(x), ["line.color", "plum"])
chips> add_curve(x, np.cos(x), ["line.color", 0xf04539, "line.style",
"dot"])

Set the symbol.style preference to "none" before adding the curves. Overplot the cosine curve on top of the sine curve, specifying attributes in a list.

Example 9

chips> cr = read_file("data.fits")
chips> x = get_colvals(cr, "X")
chips> y = get_colvals(cr, "Y")
chips> add_curve(x, y)
chips> vals = ChipsCurve()
chips> vals.line.style = "none"
chips> vals.symbol.fill = False
chips> vals.symbol.size = 5
chips> vals.symbol.color = "sienna"
chips> set_curve(vals)

Create a curve of the X and Y columns from data.fits. Populate the "vals" structure, then set the curve attributes.

Example 10

chips> add_image("img.fits")
chips> cr = read_file("fov1.fits[ccd_id=3]")
chips> x = copy_colvals(cr, "x")
chips> y = copy_colvals(cr, "y")
chips> tr = get_transform(cr, "EQPOS")
chips> add_curve(x, y, tr, ["symbol.style", "none"])

Here we overplot the polygon from a Chandra Field-Of-View file (fov1.fits), representing the edges of ACIS-I3, onto an image. We here take advantage of the transform support and read in the SKY column for the polygon (namely X and Y) and the transform data needed to convert this into the (Ra,Dec) system used to display the image (although we could have used the support for virtual columns to read in the RA and Dec columns directly from the FOV file).

Curve Preferences and Attributes

The attributes associated with curves are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_curve() command. To change the curve preference settings prepend "curve." to the attribute name.

Attribute	Description	Options	Default	Set?
baddata	How to handle NaNs and +/-infs in data	omit, ignore: omit means to discard bad data point and leave gap, ignore means discard bad points, connecting the surrounding points	omit	Yes
depth	Depth of the curve	see the Depth section of "ahelp chipsopt"	default	Yes
err.caplength	Length of the cap drawn on error bars (when err.style is cap).	1 to 100, inclusive.	10	Yes
err.color	Color of the curve err bars	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
err.down	Plot y down errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
err.left	Plot x down errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
err.right	Plot x up errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
err.style	Specifies the error bar style	bar\|line\|cap (bar and line are identical)	line	Yes
err.thickness	Specifies the thickness of error bars	0.5 to 10.0; see the Thickness section of "ahelp chipsopt"	1	Yes
err.up	Plot y up errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
limitlength	Length of the bars for upper and lower limits	0 to 1 in plot normalized coordinates	0.05	Yes
limitoverride	Should both the limit and the error bar be drawn on a point?	true = hide the errors, false = show the errors; see the Booleans section of "ahelp chipsopt"	true	Yes
line.color	Color of the curve line	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
line.style	the pattern used for the curve line style	see the Line Style section of "ahelp chipsopt"	solid	Yes
line.thickness	Thickness of the curve line	0.5 to 10.0; see the Thickness section of "ahelp chipsopt"	1	Yes
stem	Stem used for curve id	An alpha-numeric character sequence that does not contain a space	crv	No
symbol.angle	The angle, in degrees, of rotation for the curve symbols	-360.0 to 360.0	0.0	Yes
symbol.color	Color of the curve symbols	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
symbol.fill	Should the curve symbols be filled or not	see the Booleans section of "ahelp chipsopt"	true	Yes
symbol.size	Size of the curve symbols	1 to 100	2	Yes
symbol.style	The shape of the glyph used as the curve symbols	see the Symbol Styles section of "ahelp chipsopt"	cross	Yes

Changes in CIAO 4.5

Curves with only one vertex

It is now possible to create a curve for a single-element array, such as

chips> add_curve([100.23], [-1234.87])

In CIAO 4.4 the call would succeed but the point would not be displayed.

Improved support for 'small numbers'

Support has been improved for curves containing "small" y values (such as values smaller than 1e-14).

Bugs

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