Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/chips/ahelp/add_plot.html
AHELP for CIAO 4.9 ChIPS v1

add_plot

Context: plots

Synopsis

Creates a plot.

Syntax

add_plot([id,] [attributes])
add_plot([id,] x1, y1, x2, y2 [,attributes])

The function is also available as add_plotarea().

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
x1, y1, x2, y2 The lower left (x1,y1) and upper right (x2,y2) corners of the plot in frame-normalized coordinates.
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_plot command creates a plot whose attributes are specified by user preferences or in an attribute list. The new plot becomes current by default; providing a ChipsId overrides the currency state.

The plot is the object which contains axes, curves, contours, and histograms.

The lower left and upper right corner of the plot area can be specified by the add_plot() argument values (x1, y1) and (x2, y2). Otherwise a plot area is created with margins between the plot border and the frame specified by the four margin attributes: leftmargin, rightmargin, topmargin and bottommargin.

Plot Borders

Plot borders have three styles: open, box, and closed.

  • open: a plot with no borders
  • box: a plot with four simple lines as borders
  • closed: a plot with four border lines and tick marks

The corners where two lines meet have four styles: miter, bevel, fill, and notch.

  • miter: the end of the axes meet at an angle to form the corner. The slope where the two faces join depends upon the thickness of the two lines
  • bevel: connect the outside corners of the two lines; miter the inside faces to the bevel
  • fill: outside corner with one line drawn over the other
  • notch: leave the corners open

Plot Titles

The plot title is currently not an attribute of the add_plot command. It is set with the set_plot_title command:

chips> set_plot_title("Figure 1")

The title is an alphanumeric string, and Latex formatting is allowed. There are many attributes to customize the title via the add_plot or set_plot commands: position, depth, horizontal and vertical alignment, angle, color, size, font and fontstyle.

Clipping

Axes, curves, lines, points and labels in data or plot normalized coordinates are clipped at the window boundaries. Only items in data coordinate systems and lines with the extend property turned on are clipped by the plot border.

Customizing the Plot

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

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

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

Example 1

chips> add_plot()

Simple add_plot using the ChIPS defaults for the attribute values.

Example 2

chips> add_plot(.2, .2, .7, .7)

The size and location of the plot are indicated by the two XY pairs in the argument list of add_plot().

Example 3

chips> plt = ChipsPlot()
chips> plt.corner.style = "bevel"
chips> plt.style = "box"
chips> plt.stem = "MyPlot"
chips> add_plot(plt)

Populate the "plt" structure with the attribute values, then add the plot. The plot has a simple border with beveled corners.

Example 4

chips> add_plot(["style", "closed", "corner.style", "miter"])

Add a plot with mitered corners, specifying the attribute values in a list.

Plot Preferences and Attributes

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

Attribute Description Options Default Set?
bottommargin The distance, in Frame Normalized coordinates, between the bottom plot border and the bottom border of the frame containing the plot Real values ranging from zero through one 0.15 Yes
corner.style border corner style miter|bevel|fill|notch; see "ahelp set_plot" for descriptions miter Yes
leftmargin The distance, in Frame Normalized coordinates, between the left plot border and the left border of the frame containing the plot Zero through one 0.15 Yes
rightmargin The distance, in Frame Normalized coordinates, between the right plot border and the right border of the frame containing the plot Real values ranging from zero through one 0.10 Yes
stem stem used for plot id An alpha-numeric character sequence that does not contain a space plt No
style border style open|box|closed; see "ahelp add_plot" for descriptions closed Yes
title.angle Angle, in degrees, at which the plot title is drawn -360.0 to 360.0 0.0 Yes
title.color Color of the plot title text string name or hex; see the Color section of "ahelp chipsopt" default Yes
title.depth Integer value indicating the depth of the plot title see the Depth section of "ahelp chipsopt" default Yes
title.font Plot title font helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" helvetica Yes
title.fontstyle Specific attributes of the text string independent of size or font normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" normal Yes
title.halign Horizontal location of the string reference point of the plot title auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
title.size Font size of the plot title 1 to 100 16 Yes
title.valign Vertical location of the string reference point of the plot title auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" auto Yes
title.xpos X position, in Plot Normalized coordinates, of the reference point of the plot title Real values ranging from zero through one 0.5 Yes
title.ypos Y position, in Plot Normalized coordinates, of the reference point of the plot title Real values. 1.05 Yes
topmargin The distance, in Frame Normalized coordinates, between the upper plot border and the upper border of the frame containing the plot Real values ranging from zero through one 0.10 Yes
aspect.ratio The default aspect ratio of the plot, where "" means no aspect ratio is set. See "ahelp aspectratio" for the meaning and syntax of this value. 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, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
limits
get_plot_range
plots
adjust_grid_gaps, adjust_grid_xrelsize, adjust_grid_xrelsizes, adjust_grid_yrelsize, adjust_grid_yrelsizes, clear_plot, current_plot, delete_plot, display_plot, get_plot, grid_objects, hide_plot, move_plot, reposition_plot, set_data_aspect_ratio, set_plot, set_plot_aspect_ratio, split, strip_chart, swap_object_positions

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.