Last modified: December 2014

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

add_axis

Context: axes

Synopsis

Creates an axis or axes.

Syntax

add_axis([id,] dimension, position, min, max, [,attributes])
add_axis([id,] dimension, position, xmin, xmax, ymin, ymax, [transform,
attributes])

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
dimension One of X_AXIS, Y_AXIS, or XY_AXIS to specify the X axis, Y axis, or both.
position The location of the axis in the appropriate dimension (e.g. X for a Y axis and vice versa). The plot-normalized coordinate system is used unless the "coordsys" attribute is given as part of the attributes setting.
min, max The axis range; this can be changed by later calls to limits() or automatically when data is added to the plot.
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_axis command creates an axis for the requested dimension or dimensions. Since the length of the axis spans the plot area, a single position element is needed to specify the location of the axis. The axis position defaults to the plot-normalized coordinate system - in which 0 is the bottom or left of the plot and 1 is the top or right - but you can use a data coordinate system by setting the "coordsys" attribute to DATA.

The new axis (or axes if dimension is XY_AXIS) becomes current by default; providing a ChipsId overrides the currency state.

Coordinate systems

A coordinate system is defined by an X axis and a Y axis within a given plot. If a plot does not exist when an axis is added, it is automatically created. If X and Y axes are added in a single call, that axis pair defines a new coordinate system. If an X axis is added to a plot which contains a pair of Y axes, two new coordinate systems are defined - one for each X,Y pair.

WCS axes

There is explicit support for axes representing a WCS Tangent-plane projection. In most cases these will be created automatically - e.g. by make_figure(), add_contour() or add_image() - but they can also be created manually as discussed in the "Projections" section below.

Customizing the Axis

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

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

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


Examples

Example 1

chips> clear()
chips> add_axis(XY_AXIS, 0, 10, 20)

Creates a plot with axes at the bottom and left edges (a plot-normalized coordinate of 0). The limits of the axes go from 10 to 20; with the default axis.pad value of 0.05 they will end up displaying the range 9.5 to 20.5.

Since the default values for the axis automin and automax settings are both True, any data added to the plot via an add_curve, add_histogram, add_image, or add_contour call will end up changing these limits. For instance, after

chips> add_curve([1,2,3], [50,60,70])

the limits will change to x=0.9 to 3.1 and y=49 to 71 (when axis.pad is 0.05).

Example 2

chips> clear()
chips> add_axis(XY_AXIS, 0.5, 10, 20, -2000, -1000)

Here we place the axes in the center of the plot by using a position of 0.5, rather than 0 in the previous example. The x axis range is 10 to 20 and the Y axis is -2000 to -1000.

Example 3

chips> clear()
chips> add_axis(XY_AXIS, 0, 10, 20, ["pad", 0, "automin", False,
"automax", False])
chips> add_curve([5,10,15,19,25], [12,12,22,16,18])
chips> print(get_plot_yrange())
[10.0, 20.0]

In this plot, the axes both go from 10 to 20 since the pad attribute has been set to 0. Since both the automin and automax attributes are set to False, any new data added to the plot will not change the limits, which is wht the Y axis range remains as 10 to 20 after the add_curve call. Compare the above plot to

chips> clear()
chips> add_axis(XY_AXIS, 0, 10, 20, ["pad", 0])
chips> add_curve([5,10,15,19,25], [12,12,22,16,18])
chips> print(get_plot_yrange())
[12.0, 22.0]

Example 4

chips> clear()
chips> add_axis(X_AXIS, 0, -4, 4)
chips> add_axis(Y_AXIS, 0.5, 0, 1)
chips> x = np.linspace(-4, 4, 100)
chips> y = np.exp(-0.5 * x * x)
chips> add_curve(x, y, ['symbol.style', 'none']
chips> set_plot(['style', 'open'])
chips> set_axis(['pad', 0])
chips> set_yaxis(['tickstyle', 'centered'])
chips> set_plot_title(r'Gaussian with \mu = 0 \sigma = 1')

Here we create an X axis at the bottom of the plot and a Y axis half-way along the plot. To this we add a plot of a Gaussian - over the range -4 to 4 - and then remove the plot borders by changing the plot style to 'open'. After changing the 'pad' value of both axes, the tick marks on the Y axis are drawn on both sides of the axis (the default value for 'tickstyle' is inside). Finally a title is added to describe the plot.

Example 5

chips> clear()
chips> x = np.linspace(-4, 4, 100)
chips> yg = np.exp(-0.5 * x * x)
chips> yn = yg / yg.sum()
chips> yc = np.cumsum(yn)
chips> add_curve(x, yn, ['symbol.style', 'none'])
chips> set_plot_ylabel('Normalised value')
chips> add_axis(Y_AXIS, 1, 0, 1, ['y.label.text', 'Cumulative value'])
chips> add_curve(x, yc, ['symbol.style', 'none', 'line.color', 'green'])
chips> set_plot(['rightmargin', 0.15])

Here we plot up a normalized Gaussian, and then add a Y axis to the right of the plot and display the cumulative distribution in green. Labels are added to both Y axies, with the right-hand margin increased to 0.15 to provide space for the second label.

Note that the axis label text for the second Y axis is given as 'y.label.text' in the add_axis call, even though we have already specified that this is for the Y axis by the first argument (Y_AXIS).

Example 6

chips> clear()
chips> add_curve([1,2,3], [50,60,70])
chips> add_axis(Y_AXIS, 1, 1, 2)
chips> bind_axes("ay1", "ay2")
chips> limits (Y_AXIS, 40, 80)
chips> set_plot(["rightmargin", 0.15])

The add_axis call creates a second Y axis at the right-hand side of the plot (at a plot-normalized location of 1). The initial limits are set to 1 to 2, but as we want them to match the original Y axis, we then call bind_axes so that the two Y axes are mirrored (the bind_axes call makes the axis "ay2", which is the one we just created, mirror the "ay1" axis, which is the original Y axis). After this call, changes to one Y axis affects both of them, as shown by the limits call.

Since the second axis was placed in plot-normalized coordinates, it moves as the plot area changes; in this case the right-hand margin is changed to 0.15 so the new Y axis moves with the plot.

Example 7

chips> clear()
chips> add_curve([1,2,3,4,5], [2,-5,3,-8,10])
chips> add_axis(X_AXIS, 0, 0, 1, ["coordsys", DATA, "id", "zero"])
chips> bind_axes("ax1", "zero")
chips> limits(X_AXIS, 0, 6)
chips> limits(Y_AXIS, -10, 11)

The add_axis call creates a second X axis, placed at y=0, since the coordinate system is set to DATA rather than the default PLOT_NORM. The id of this new axis is set to "zero" (with the default ChIPS settings it would normally have been called "ax2"). The bind_axes command is used to make sure that new axis mirrors the original X axis (called "ax1").

This mirroring can be seen in the limits call when the X axis is changed to 0 to 6; both axes are updated automatically. Note that since the second axis was placed using data coordinates, it moves as the Y axis is changed in the second limits call.

Example 8

chips> x = np.arange(-5, 5, 0.1)
chips> y1 = np.sin(x) * 10
chips> y2 = np.cos(x) * 5 + 20
chips> copts = ['symbol.style', 'none']
chips> clear()
chips> add_curve(x, y1, copts)
chips> limits(X_AXIS, -5, 5)
chips> add_axis(Y_AXIS, 0.8, 0, 1)
chips> add_curve(x, y2, copts)
chips> set_plot(["style", "open"])
chips> set_curve(["line.color", "red"])
chips> set_axis("ay2", ["*.color", "red"])
chips> add_label(4, 24, "y2", ["size", 16, "color", "red"])
chips> current_axis("ay1")
chips> add_label(0, -10, "y1", ["size", 16])

In this example we show how to plot data sets using two different coordinate systems in the same plot. In this case we wish to plot both

y1 = 10 * sin(x)

and

y2 = 5 * cos(x) + 20

for the domain -5 to 5. Both data sets will be plotted as lines, with the second set (y2) in red.

We start by plotting the first data set (x,y1), and then add a second Y axis positioned at x=0.8 in plot-normalized coordinates (which is x=3 in data coordinates since the plot goes from -5 to 5). After the add_axis call has been made, there are now two data coordinate systems: these can be seen using the info_coordinate command. If we called info_coordinate and info_current at this time (prior to the second add_curve call) we would see:

chips> info_coordinate()

Window [win1]
  Frame [frm1]
    Plot [plot1]
        Coord Sys ID [ds0.0.0.3]
        X Axis [ax1]
        Y Axis [ay1]
        Coord Sys ID [ds0.0.0.4]
        X Axis [ax1]
        Y Axis [ay2]

chips> info_current()

Window [win1]
  Frame [frm1]
    Plot [plot1]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay2]
    Coord Sys [Data]
    Coord Sys ID [ds0.0.0.4]

The first curve uses the "ax1" and "ay1" axes - with an internal label of "ds0.0.0.3" - which covers x=-5 to 5 and y=-11 to 11), and the second curve will use the "ax1" and "ay2" axes (with the internal label of "ds.0.0.0.4").

After the second curve has been added, the plot style is changed to "open", which hides the border along the top of the plot, and the second curve and Y axis are both set to red to distinguish themselves.

Finally, two labels are added to the graph: the first "y2" is placed using the data coordinate system of the second curve (since it is current at this time). The current_axis call is used to change the current y axis to "ay1", which makes the first coordinate current again - namely axes "ax1" and "ay1" - and so the second label ("y1") is placed using the data coordinate system of the first curve.

Example 9

chips> ax = ChipsAxis()
chips> ax.color = "blue"
chips> ax.thickness = 0.5
chips> ax.mode = "interval"
chips> add_axis(X_AXIS, 0, 0, 100, ax)

Populate the "ax" structure with the attribute values, then add an X axis with limits from 0 to 1000.

Example 10

chips> add_plot(["plot.style", "open"])
chips> add_axis(XY_AXIS, .5, 1, 10, ["ticklabel.angle", "45",
"majorgrid.visible", True])

Create axes at the center of the plot, with major grids visible, specifying the attribute values in a list.

Example 11

chips> cr = read_file("fov.8552.fits[ccd_id=3]")
chips> ra = copy_colvals(cr, "ra")
chips> dec = copy_colvals(cr, "dec")
chips> tr = cr.get_transform("EQPOS")
chips> xmin = ra.min()
chips> xmax = ra.max()
chips> ymin = dec.min()
chips> ymax = dec.max()
chips> add_axis(XY_AXIS, 0, xmin, xmax, ymin, tmax, tr)
chips> set_data_aspect_ratio("1:1")
chips> add_line(ra, dec)

In this example we read in the RA and DEC columns from a Chandra FOV file (in this case for ObsId 8552, part of the COSMOS observations), restricting the data to that for ACIS-I3 only. The WCS transform for this column is also extracted from the crate, using the get_transform() method, since this is needed to provide the transform information to create a pair of tangent-plane projection axes in the add_axis call.

In order to display the correct area of the sky we manually set the limits to the coordinate range (since a line is an annotation and so does not cause any "AUTO" axis limits to change when it is added); the set_data_aspect_ratio() call is to make sure that the correct aspect ratio is displayed; this may well change the limits to ensure the correct aspect ratio is displayed. Finally we use a line to draw the edges of the polygon used to represent the FOV of this chip.

Although we give the X-axis limits in ascending order, they are displayed in descending order since the system has recognized that this is a RA axis. The reverse_axes() command can be used to revert back to ascending order if so desired.

A note on FOV files

The add_fov_region command from the chips_contrib.region module can also be used to display Chandra FOV regions.


Projections

The ability to supply a transform object when creating a pair of axes allows users to create axes that describe Tangent-plane projections for use with images, contours or in fact any other object that can be displayed in a data coordinate system.

The easiest way to create a transform object is to read it from a crate using the get_transform() method. For instance, if img.fits is an image of a Chandra ACIS observation, then the following will create a pair of axes in the middle of the plot and then draw the image underneath it.

chips> cr = read_file("img.fits")
chips> eqpos = cr.get_transform('EQPOS')
chips> add_axis(XY_AXIS, 0.5, 0, 1, 0, 1, eqpos)
chips> set_plot(["style", "open"])
chips> add_image(cr, ["depth", 50])
chips> set_xaxis(["tickformat", "%ra"])
chips> set_yaxis(["tickformat", "%dec"])
chips> set_data_aspect_ratio("1:1")

Unsupported WCS projections

If the WCS projection is not a tangent-plane projection - such as a SIN projection - then the add_axis command will fall back to a logical system with the following warning:

chips> add_axis(XY_AXIS, 0.5, 0, 1, 0, 1, eqpos)
chips WARNING: The transform type provided (RA---SIN, DEC--SIN) is
unsupported - proceeding with logical coordinates.

Axis Preferences and Attributes

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

Attribute Description Options Default Set?
automin Should the axis automatically reset its minimum when a curve, histogram, image, or contour is added? see the Booleans section of "ahelp chipsopt" true Yes
automax Should the axis automatically reset its maximum when a curve, histogram, image, or contour is added? see the Booleans section of "ahelp chipsopt" true Yes
color Color of the axis base line segment name or hex; see the Color section of "ahelp chipsopt" default Yes
coordsys coordinate system for the axis PIXEL, WINDOW_NORM, FRAME_NORM, PLOT_NORM, DATA see "ahelp coordsys" No
depth Integer value indicating axis depth see the Depth section of "ahelp chipsopt" default Yes
label.color Color of the axis label name or hex; see the Color section of "ahelp chipsopt" default Yes
label.font font for the axis label text helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" helvetica Yes
label.fontstyle style of the axis label text normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" normal Yes
label.halign Horizontal location of the string reference point of the axis label auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
label.size Font size of the axis label 1 to 100 14 Yes
label.valign Vertical location of the string reference point of the axis label auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
majorgrid.color Color of the axis major grids name or hex; see the Color section of "ahelp chipsopt" default Yes
majorgrid.style stipple pattern used to draw the axis major grids see the Line Style section of "ahelp chipsopt" shortdash Yes
majorgrid.thickness Thickness of the axis major grids 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
majorgrid.visible Should major grids be visible see the Booleans section of "ahelp chipsopt" false Yes
majortick.color The color to use for major ticks name or hex; see the Color section of "ahelp chipsopt" default Yes
majortick.count Default number of ticks to display when major mode is count Non-negative integer 4 Yes
majortick.interval Spacing to use between ticks when major mode is interval Non-negative value 10 Yes
majortick.length length of major ticks Non-negative integer 1 Yes
majortick.mode Mode of the axis tickmark positioning arbitrary|count|interval|limits|nice; see the Tick Mode section of "ahelp chipsopt" limits Yes
majortick.style Style of the axis tickmarks inside|outside|centered; see the Tick Style section of "ahelp chipsopt" inside Yes
majortick.thickness Thickness of major ticks 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
majortick.visible Are major ticks visible or hidden see the Booleans section of "ahelp chipsopt" true Yes
minorgrid.color Color of the axis minor grids name or hex; see the Color section of "ahelp chipsopt" default Yes
minorgrid.style stipple pattern used to draw the axis minor grids see the Line Style section of "ahelp chipsopt" dot Yes
minorgrid.thickness Thickness of the axis minor grids 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
minorgrid.visible Should minor grids be visible see the Booleans section of "ahelp chipsopt" false Yes
minortick.color The color to use for minor ticks name or hex; see the Color section of "ahelp chipsopt" default Yes
minortick.count Default number of ticks to display when minor mode is count Non-negative integer 4 Yes
minortick.interval Spacing to use between ticks when minor mode is interval Non-negative value 10 Yes
minortick.length length of minor ticks Non-negative integer 1 Yes
minortick.mode Mode of the axis tickmark positioning arbitrary|count|interval|limits|nice; see the Tick Mode section of "ahelp chipsopt" nice Yes
minortick.style Style of the axis tickmarks inside|outside|centered; see the Tick Style section of "ahelp chipsopt" inside Yes
minortick.thickness Thickness of minor ticks 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
minortick.visible Are minor ticks visible or hidden see the Booleans section of "ahelp chipsopt" true Yes
offset.parallel axis label offset from axis start (-.5) to axis end (.5) -0.5 to 0.5 inclusive; 0 is the center and -0.5/+0.5 refer to the edges 0 Yes
offset.perpendicular axis label offset from axis baseline in pixels -100 to 100, inclusive 40 Yes
pad The percentage of padding to add to an axis in arbitrary limits or interval modes Non-negative value 0.05 Yes
thickness Thickness of the axis 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
tickformat print format for axis ticklabels alphanumeric; see the Tick Format section of "ahelp chipsopt" %g Yes
ticklabel.angle angle, in degrees, of the axis ticklabel -360.0 to 360.0 0 Yes
ticklabel.color Color of the axis ticklabels name or hex; see the Color section of "ahelp chipsopt" default Yes
ticklabel.font font for the axis ticklabel text helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" helvetica Yes
ticklabel.fontstyle style of the axis ticklabel text normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" normal Yes
ticklabel.halign Horizontal location of the string reference point of the axis ticklabel auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
ticklabel.offset Offset of ticklabels to axis base (in pixels) Non-negative value 6 Yes
ticklabel.size Font size of the axis ticklabel 1 to 100 12 Yes
ticklabel.style Style of the axis ticklabels inside, outside outside Yes
ticklabel.valign Vertical location of the string reference point of the axis ticklabel auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" center Yes
ticklabel.visible Should ticklabels be visible see the Booleans section of "ahelp chipsopt" true No
x.label.text The text used for the X axis label A text label with limited support for LaTeX commands; see the Text Formatting section of "ahelp chipsopt". Yes
x.label.angle The angle used for the X axis label 0 is horizontal, 90 is vertical with text reading from bottom to top, and 270 is vertical with text reading from top to bottom. 0 Yes
x.stem stem used for x axis id An alpha-numeric character sequence that does not contain a space ax No
y.label.text The text used for the Y axis label A text label with limited support for LaTeX commands; see the Text Formatting section of "ahelp chipsopt". Yes
y.label.angle The angle used for the Y axis label 0 is horizontal, 90 is vertical with text reading from bottom to top, and 270 is vertical with text reading from top to bottom. 90 Yes
y.stem stem used for y axis id An alpha-numeric character sequence that does not contain a space ay No

The label.angle field

The label.angle field was removed in CIAO 4.6; the x.label.angle and y.label angle fields should be used instead.


Bugs

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

See Also

axes
bind_axes, current_axis, delete_axis, display_axis, display_major_ticks, display_minor_ticks, get_axis, get_xaxis, get_yaxis, hide_axis, hide_major_ticks, hide_minor_ticks, lin_scale, log_scale, move_axis, reverse_axes, set_arbitrary_tick_positions, set_axis, set_xaxis, set_yaxis, shuffle_axis, unbind_axes
chips
chips, chipsgui, chipsrc, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
limits
get_plot_range
plots
add_plot, 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