Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/chips/ahelp/add_curve.html
AHELP for CIAO 4.11 ChIPS v1

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([id,] filename [, transform [, attributes]])
add_curve([id,] TABLECrate [, transform [, attributes]])
add_curve([id,] x, y [, transform [, attributes]])
add_curve([id,] x, y, error_list|None [, transform [, attributes]])
add_curve([id,] x, y, error_list|None, limits_list|None [, transform [,
attributes]])

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
filename The name of the file containing the columns 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.
TABLECrate A table crate, returned either by a read_file call or a call to the TABLECrate constructor (see "ahelp crate").
x, y One dimensional NumPy arrays or Python lists which have the same number of elements.
error_list An optional list of up to four error arrays (which take the same form as used for the x and y arguments). If there is a single array, or a list with one element then, then this refers to symmetrical y errors. If the list contains two elements, these are taken to be the ydown and yup error values. Three elements is ydown, yup, and xdown errors, with four elements being ydown, yup, xdown, and xup errors. The error values are relative and should be positive (even for the x/ydown values).
limits_list An optional list of upper and/or lower limits. The list may be empty, y limits, or y and x limits.
transform A pytransform object that determines the mapping between the logical coordinate system, where (1,1) refers to the center of the bottom-left pixel, and the display system. At present this should either be a LINEAR2DTransform or WCSTransform object that contains a tangent-plane projection.
attributes Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

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 "Curve Preferences and Attributes" section below the examples for a list of the curve preferences.


Examples

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> !cat src.dat
23.4 42.3
12.9 87.2
48.8 63.2
109.4 -2.3
chips> clear()
chips> add_curve("src.dat", ['line.style', 'noline'])

Here we plot up the only two columns in the ASCII file src.dat as points.

Example 4

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 5

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 6

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 7

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 8

chips> z = np.arange(10)
chips> add_curve(z, z-4, z*0.15)

Create a curve with symetric Y error bars (15% of the value). To plot asymetric bars, try:

chips> add_curve(z, z-4, [z*0.2, z*0.1])

Example 9

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 10

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 11

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. An alternative would have been to say

chips> ra = copy_colvals(cr, "ra")
chips> dec = copy_colvals(cr, "dec")
chips> add_curve(ra, dec, ['symbol.style', 'none', 'line.color', 'red'])

and use the virtual columns RA and Dec from the FOV file directly.


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

Bugs

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

See Also

chips
chips, chipsgui, chipsrc, make_figure, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
curves
current_curve, delete_curve, display_curve, get_curve, hide_curve, set_curve, shuffle_curve