/ chips4.11 / ahelp / grid_objects.html

Jump to: Description · Examples · Bugs · See Also

AHELP for CIAO 4.11 ChIPS v1

grid_objects

Context: plots

Synopsis

Rearrange plots into a grid.

Syntax

grid_objects([id,] cols, rows, xgap, ygap [,usage [,plots]])

Description

The function arguments.

Argument	Description
cols	The number of columns for the grid.
rows	The number of rows for the grid.
xgap, ygap	The horizontal and vertical spacing between the plots as a fraction of the default plot width and height, respectively.
usage	How are existing plots used? It is an integer between 0 and 4 inclusive, described below. The default value is 0.
plots	A list of the plot names to include or exclude (when usage is 3 or 4).
id	A ChipsId structure identifying the item.

The grid_objects command creates a grid of NxM (rows x cols) plot areas. The plot areas are numbered sequentially from the upper left corner, left to right and top to bottom. With the default usage value (of 0), the plots must already exist.

Usage Options

The usage parameter determines what plots are used in the grid. There are five allowed values:

The usage argument

Value	Description
0	Only use existing plots. The command does not error out if there are not enough existing plots, so it is possible to create a partially-filled grid. The optional plots array lists the plot ids to use.
1	Use existing plots but create new ones as necessary, so this always creates a filled grid. The optional plots array lists the plot ids to use.
2	Only use new plots, ignoring existing plots. The plots array is not used in this case.
3	Only use existing plots, ignoring those plots listed in the plots argument. As with usage=0, it is possible to use less plots than will fill the grid. The plots array must be given, and not empty, otherwise no plots will be used.
4	Create new plots as needed, excluding those plots listed in the plots argument. If the plots array is not given or empty than all existing plots are excluded.

In all cases, existing plots not included in the grid are hidden, not deleted. The plots may be redisplayed with another grid_objects call that include the plot, or by changing the plot location with the reposition_plot command. Hidden plots may still be modified or deleted.

Creating a row or column of plots

There are also individual commands for creating a row or a column of plots:

row_grid_objects([id,] cols_array, xgap, ygap [,usage [,plots]])
col_grid_objects([id,] rows_array, xgap, ygap [,usage [,plots]])

The cols_array is the number of columns of plots for each row; the number of elements in the array indicates the total number of rows. The rows_array is the number of rows of plots to use for each column; the number of elements in the array indicates the total number of columns. All other parameters are the same as for grid_objects.

If more than one frame is current, the gridding is applied to all the current frames.

The xgap and ygap values are given as a fraction of the plot area, as defined by the plot margins in the preferences file.

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.

Examples

Example 1

chips> grid_objects(2, 2, 0, 0.1, 1)

Create a grid of four plots arranged in two rows of two columns with spacing between the rows. Existing plots are used, with new plots added as needed, since the usage argument was set to 1.

Example 2

chips> add_plot(['id', 'xplot'])
chips> add_plot(['id', 'yplot'])
chips> add_plot(['id', 'zplot'])
chips> grid_objects(2, 2, 0.05, 0.05)

Three plots are creted and then arranged into a two-by-two grid. Since the default usage value is used the fourth plot area is left empty, as shown in the info output:

chips> print(info())
Window [win1]
  Frame [frm1]
    Plot [xplot]   (0.15,0.55)  .. (0.50,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
    Plot [yplot]   (0.55,0.55)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
    Plot [zplot]   (0.15,0.15)  .. (0.50,0.50)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]

Example 3

chips> plots = ['plot2','plot4','plot1']
chips> grid_objects(1, 3, 0, 0, 0, plots)

Stack three existing plots - plot1, plot2, and plot4 (top to bottom) - in a column. All other existing plots are hidden.

Example 4

chips> grid_objects(3, 3, 0.05, 0.05, 2)

Creates a 3 x 3 grid of new plots with uniform horizontal and vertical spacing. Any existing plots become hidden.

Example 5

chips> add_plot(.1,.1,.9,.9,'id=plot1')
chips> add_contour('contour.fits')
chips> add_plot(.2,.65,.4,.85,'id=inlay1')
chips> add_curve('curve.fits')
chips> add_plot(.6,.65,.8,.85,'id=inlay2')
chips> add_curve('curve_2.fits')
chips> grid_objects(2,2,0,0,3,['plot1'])

Create a contour plot with two inlaid curve plots. The grid_objects command creates a 2x2 grid which includes the inlay plots, but excludes the contour plot (usage is set to "3").

Example 6

chips> col_grid_objects([1,2,3,4],0.02,0.02,2)

Create four columns with a total of 10 new plots. The number of plots per column (moving from left to right) run sequentially from 1 to 4. Any existing plots become hidden.

Example 7

chips> pnames = ['plot2','plot1','plot4']
chips> col_grid_objects([1,2], 0, 0, 0, pnames)

Arrange three plots so that a tall single plot occupies the left half of the frame and a stacked pair of plots occupies the right. 'plot2' is on the left; 'plot1' and 'plot4' fill the second column from top to bottom. All other existing plots are hidden.

Example 8

chips> row_grid_objects([1,1,2,1],0.05,0.05,2)

Create four rows with a total of 5 new plots; the third row contains two plots. Any existing plots become hidden.

Example 9

chips> plots = ['plot2','plot1','plot4']
chips> row_grid_objects([1,2], 0, 0, 0, plots)

Arraneg three plots so that a wide, single plot is stacked above a pair of plots. 'plot2' is on the top; 'plot1' and 'plot4' fill the second row from left to right. All other existing plots are hidden.

Bugs

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