grid_objects

Context: plots

Syntax

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

Description

id - an optional ChipsId structure containing values to modify the currency state for the command
cols - the number of columns of plots
rows - the number of rows of plots
xgap - spacing between the columns of plots as percentage of the frame width
ygap - spacing between the rows of plots as percentage of the frame width
usage - the behavior with regards to plots: 0 = use only existing plots (default); 1 = use existing plots, add new ones as needed; 2 = always create new plots; 3 = use only existing plots, excluding those listed; 4 = exclude the listed plots, add new ones as needed.
plots - an optional list plot ids to include or exclude from the grid.

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.

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 percentage of the plot area, as defined by the plot margins in the preferences file.

Usage Options

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

0 = use only existing plots (default). Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, the remaining sections of the grid are empty. An optional list of plot ids to use in the grid may be supplied in the "plots" parameter.
1 = use existing plots, add new ones as needed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, new plot areas are created to fille the remaining sections of the grid. An optional list of plot ids to use in the grid may be supplied in the "plots" parameter.
2 = always create new plots. All new plots are created to fill the NxM grid.
3 = use only existing plots, excluding those listed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, the remaining sections of the grid are empty. A list of plot ids to be excluded from the grid is supplied in the "plots" parameter. If "plots" is empty, all existing plots are excluded from the grid.
4 = exclude the listed plots, add new ones as needed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, new plot areas are created to fille the remaining sections of the grid. A list of plot ids to be excluded from the grid is supplied in the "plots" parameter. If "plots" is empty, all existing plots are excluded from the grid.

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 reposition_plot ("ahelp reposition_plot") . Hidden plots may still be modified or deleted.

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.

Example 1

chips> grid_objects(2,2,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.

Example 2

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

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

Example 3

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 4

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 5

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 6

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

The col_grid_objects command is called to arrange 3 plots so that a tall single plot occupies the left half of the frame's available plot area, and a stacked pair of plots occupies the right. The plots are ordered with 'plot2' on the left, 'plot1' and 'plot4' fill the second column from top to bottom. All other existing plots are hidden.

Example 7

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

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> row_grid_objects([1,2],0,0,0,['plot2','plot1','plot4'])

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.