Last modified: December 2013

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

split

Context: plots

Synopsis

Creates a grid of plot areas

Syntax

split([id,] [rows,] [cols,] [ygap,] [xgap])

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
rows The number of rows (defaults to 2).
cols The number of columns (defaults to 1).
ygap The spacing between the rows, as a fraction of the available plot height (the region defined by the default plot margins).
xgap The spacing between the columns, as a fraction of the available plot width (the region defined by the default plot margins).

The split command creates a grid of "rows" x "cols" plot areas. The plot areas are numbered sequentially from the upper left corner, left to right and top to bottom.

If no argument is given, a 2 x 1 grid is created. If only the number of rows is specified, an N x 1 grid is created.

Customizing the Grid

To modify the gap spacing after the grid has been created, use the adjust_grid_gaps, adjust_grid_xgap, and adjust_grid_xgap commands ("ahelp adjust_grid_gaps"). The row widths and column heights can be changed with the following commands, each of which has a help file: adjust_grid_xrelsize, adjust_grid_xrelsizes, adjust_grid_xrelsize, and adjust_grid_xrelsizes.

The strip_chart command has functionality similar to split; see the strip_chart ahelp page for information on how to create a strip chart containing multiple plots.


Examples

Example 1

chips> split()

Create a grid with two plots, one above the other.

Example 2

chips> split(3, 2, 0, 0.05)

Create a grid with three rows and 2 columns. There is a horizontal gap between the two columns but no gap between the rows.

Example 3

chips> split("win1", 4, 1, 0.01)

Create 4 plots arranged vertically in the window with id "win1". Set the vertical gap between each plot to 0.05.

Example 4

chips> x = np.arange(10, 20, 2)
chips> y1 = x
chips> y2 = x**2
chips> y3 = np.sin(x) * np.cos(x)
chips> add_curve(x, y1)
chips> split()
chips> add_curve(x, y2)
chips> split(3)
chips> add_curve(x, y3)
chips> adjust_grid_ygap(0.05)
chips> adjust_grid_yrelsize(3, 1.5)

We start by creating a single plot of y=x. The split call, with no arguments, makes a second plot below the first, and makes this new plot the current one. This means that the y=x^2 curve appears in this new plot. The second split call makes a column of three plots, and again makes this new plot the current one. After plotting the final dataset in this plot, the grid spacing is increased and the third row (so bottom plot), is made to be fifty percent taller than the other plots. The info output after these commands looks like:

chips> print(info())
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.71)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]
    Plot [plot2]   (0.15,0.48)  .. (0.90,0.66)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]
    Plot [plot3]   (0.15,0.15)  .. (0.90,0.43)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]


Currency and the split command

The currency rules still apply when using the split command. This may be confusing when issuing multiple split commands or deleting a plot area after a split command. For instance:

chips> split(3,2)

chips> print(info_current())
Window [win1]
  Frame [frm1]
    Plot [plot1]
    Coord Sys [Plot Normalized]

chips> delete_plot("plot3")
chips> print(info_current())
Window [win1]
  Frame [frm1]
    Plot [plot6]
    Coord Sys [Plot Normalized]

The first plot area (plot1) is current after the split command. After deleting one of the plot areas, plot6 is current. This follows the currency rule that when an object is deleted, the last object of that type that was created becomes current (not the one that was most recently current).

Use the info_current command to find out which plot area is current at any point in the session.

A comparison between split and strip_chart

Grids

The strip chart is needed if you wish to make a grid of plots; i.e. more than one column or row. In this case the bind_axes command can be used to bind together any axes that should have the same range and scale.

Existing plots

The strip_chart command always creates a new frame whereas the split command will re-use existing plots, only creating plots when needed. This is shown in the following two cases:

chips> clear()
chips> add_curve([1,2,3], [1,2,3])
chips> split(2)

which creates two vertically-aligned plots; the top plot containing the curve and the second plot is now current:

chips> print(info())
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.52)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.52)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]

chips> print(info_current())
Window [win1]
  Frame [frm1]
    Plot [plot2]
    Coord Sys [Plot Normalized]

chips> clear()
chips> add_curve([1,2,3], [1,2,3])
chips> strip_chart(2)

In this case it appears that the curve has been deleted, but it has in fact been covered by a new frame, and the first plot of this new frame is visible.

chips> print(info())
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]
  Frame [frm2]
    Plot [plot1]   (0.15,0.52)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.52)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]

chips> print(info_current())
Window [win1]
  Frame [frm2]
    Plot [plot1]
      X Axis [ax1]
      Y Axis [ay1]
    Coord Sys [Data]
    Coord Sys ID [ds5.7.17.53]

The grid_objects, col_grid_objects and row_grid_objects commands provide a lower-level interface for creating rows and grids of plots. The adjust_grid_gaps, adjust_grid_xgap, and adjust_grid_ygap commands allow you to change the spacing between the plots. The adjust_grid_xrelsize, adjust_grid_yrelsize, adjust_grid_xrelsizes, and adjust_grid_yrelsizes commands allow you to change the relative sizes (widths or heights) of the plots. The swap_object_positions command allows you to swap the positions of two plots in a grid.


Bugs

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

See Also

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, strip_chart, swap_object_positions