add_axis

Synopsis

Creates an axis or axes.

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

Description

• ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
• dimension - add axis in X dimension (X_AXIS), Y dimension (Y_AXIS), or both (XY_AXIS)
• position - the location of the axis in the appropriate dimension (in X for Y axes and in Y for X axes); unless explicitly specified, the plot-normalized system is used.
• min, max - the minimum and maximum values to use for the initial range of the axis.
• transform - a Crates transform object used to indicate that the axis pair forms a WCS-TAN projection system.
• attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

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.

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, ys, ['symbol.style', 'none'])
chips> add_axis(Y_AXIS, 1, 0, 1)
chips> set_plot_ylabel('Normalised value')
chips> add_curve(x, yc, ['symbol.style', 'none', 'line.color', 'green])
chips> set_plot_ylabel('Cumulative value')
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.

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 (see "ahelp info_coordinate"). 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

Due to the way that the POLYGONs are stored in the FOV files, the ra and dec values may contain extra values at the end of the array which need to be filtered out. Please see the add_fov_region command - part of the chips_contrib.regions module - if you wish to display Chandra FOV regions in ChIPS.

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")

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.

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