4.8. Multiple Plots Per Image

This section contains information about producing more than one plot on an image.

Using PHPlot, you can produce more than one plot on a single image. These can be tiled plots - separate plots manually positioned within the image, or overlay plots. Tiled plots are used when you want to display more than one plot on a single image, for example side-by-side. Overlay plots are used when you want to show more than one type or range of data representation on a single plot. For example, an overlay plot could be used to show two data sets with different Y scales, or to overlay a bar chart with a line plot. You can also combine tiled and overlay plots in a single image.

An example of two tiled plots on an image can be found in Section 5.18, “Example - Two Plots on One Image”. An example of an overlay plot can be found in Section 5.34, “Example - Overlaying Plots”

4.8.1. Overview of Multiple Plots

When producing multiple plots on an image, a single PHPlot object is used. The overall steps to be followed are:

  1. Create a PHPlot or PHPlot_truecolor object (referred to here as $plot).

  2. Use $plot->SetPrintImage(False) to disable automatic output of the image after a plot is created.

  3. Prepare the first plot, including setting the data array, plot type, and any other applicable settings.

  4. Use $plot->DrawGraph() when complete. This creates the plot, but does not produce any output.

  5. Repeat the previous two steps to prepare each additional plot, completing it with $plot->DrawGraph().

  6. When all the plots are complete, use $plot->PrintImage() to output the completed image.

The sections which follow contain additional information you will need to produce multiple plots on a single image.

4.8.2. Plot Settings with Multiple Plots

In general, PHPlot applies settings made for one plot as defaults for the next plot, when using the same PHPlot class instance. There are some special cases, however, which are discussed in the sections below.

4.8.2.1. Global Settings

Certain plot elements apply to the image as a whole, not to individual plots. PHPlot will draw these at most once per image. (That is, the element will be drawn only the first time DrawGraph() is called after the element has been set up.)

For example, the first plot on an image that has a main title will result in the main title being drawn. If any subsequent plot (using the same PHPlot instance) also sets a main title, that will be ignored.

4.8.2.2. Data Scaling

Whether you use SetPlotAreaWorld to set the plot area data range, or you let PHPlot calculate the plot area data range, that range applies to all subsequent plots unless overridden. Even if you set a new data array, the calculated or pre-set data range from the previous plot applies. Without being told otherwise, PHPlot will not re-examine the data array to recalculate the data range. This allows you to re-use an automatically calculated data range, if you want.

Note

Nothing related to world coordinates and data scaling applies to pie charts, which have do not use world coordinates.

If instead you want PHPlot to automatically calculate the data range for additional plots, call SetPlotAreaWorld() (with no arguments), or SetPlotAreaWorld(NULL, NULL, NULL, NULL). Either of these forms causes PHPlot to forget about a specified or calculated data range, and it will compute a new range.

Of course, you can also use SetPlotAreaWorld with parameter values, to manually set all or part of the data range for each plot. Any parameters you do not set (or specify as NULL) will be calculated based on the data array for the current plot. That is, PHPlot will forget about the previous data range once you call SetPlotAreaWorld, regardless of how many non-NULL parameters you use.

When overlaying plots, you will often want all the plots to use the same data scale, so the values can be read off of the axis. Another option is to have two separate Y scales, with one represented on the left side and one on the right side. (See Section 5.34, “Example - Overlaying Plots” for an example of overlaying plots with two different Y scales.) In some cases it may make sense to overlay plots with different scales and no separate axis, for example when using data value labels, or when the important information is the trend or shape shown by the graph rather than the actual values.

4.8.2.3. Plot Area

You can specify a plot area (window) with SetPlotAreaPixels or SetMarginsPixels, or you can let PHPlot calculate a plot area. Whether you set the plot area yourself, or you let PHPlot calculate it, those settings apply to all subsequent plots unless overridden.

This means that if you are doing side-by-side (tiled) plots on an image, you must use SetPlotAreaPixels or SetMarginsPixels with each plot, to set the area of the image to be used for that plot. Remember that the plot area does not include the axis labels, tick marks, or titles, so you must leave enough room between and around plots for these.

If you are doing overlay plots, you can let PHPlot calculate the plot area for the first plot, or you can specify the area with SetPlotAreaPixels or SetMarginsPixels. You need not use these for subsequent plots; PHPlot will continue to use the same window, overlaying the additional plots.

However, if you allow PHPlot to calculate the plot area, it will only use information in the first plot to determine the margins. This will not work well if subsequent plots require more margin space. For example, if the first plot has a Y axis title and tick labels only on the left side, and the second overlay plot has a Y axis title and tick labels on the right side, automatic plot area calculation will only leave enough margin space on the left side. As a result, the right side Y axis title and tick labels may fall off the image edge. To avoid this, use either SetPlotAreaPixels or SetMarginsPixels to specify large enough margins.

4.8.2.4. Tick Increment

Tick increments are recalculated for each plot, based on the data range, unless set with SetXTickIncrement or SetYTickIncrement. 'Data range' here refers to that set with SetPlotAreaWorld, or automatically calculated. This differs from the way PHPlot handles the data range, which is not recalculated by default after the first plot.

For overlay plots, if you want to use the same tick increments, you should either set the desired tick increment (doing this for the first plot is sufficient), or make sure the data ranges match.

4.8.2.5. Grid Lines

PHPlot defaults to drawing the dependent variable grid (usually Y), and the grid lines will be drawn at tick positions. As stated above, the tick positions by default will be recalculated for each plot, using the calculated or explicitly set data range.

For overlay plots, you generally do not want to have more than one set of grid lines in each of X and Y, or the results will be confusing. Even if your plot overlays have the same tick increments, avoid having the grid lines drawn more than once. Otherwise, the grid lines for the second plot will overlay the plotted data from the first plot. You can turn off the grid lines with SetDrawXGrid(False) and SetDrawYGrid(False).

4.8.2.6. Legend Positioning

Legend position with multiple plots works differently depending on whether the position is defaulted or set, and if set what method was used.

  • If the legend position is defaulted, a legend will be drawn at the upper right corner of each plot. The same legend will be drawn in each position, unless the contents are changed with SetLegend.

  • If the legend position is specified using device coordinates with SetLegendPixels, or by using SetLegendPosition (PHPlot-5.4.0 or later) with mode 'image' or 'title', then the legend position is relative to the image. The legend will be drawn at the specified position on the image, once per plot, at the same location. This repeated over-drawing is usually harmless, but if you want to have it drawn only once, either use SetLegend only before the last plot, or use either SetLegend(NULL) or SetLegend(array()) to cancel the legend after the first plot.

  • If the legend position is specified using world coordinates with SetLegendWorld, or by using SetLegendPosition (PHPlot-5.4.0 or later) with mode 'world' or 'plot', then the legend position is relative to the plot or the data within the plot. The legend will be drawn at the calculated position on each plot. If using SetLegendWorld, or SetLegendPosition with mode 'world', this assumes the specified world coordinates are within the plot area for each plot. As with the default positioning case, the same legend will be drawn for each plot, unless the contents are changed with SetLegend().

4.8.2.7. Plot Area Background

If you set a plot area background color with SetPlotBgColor and SetDrawPlotAreaBackground, or if you set a plot area background image with SetPlotAreaBgImage, this will be applied to each plot until disabled. This works well for side-by-side (tiled) plots, as each will get the same background by default.

If you are overlaying multiple plots on an image, setting a plot area background color or image for one plot will result in that background hiding previous plots. Therefore, you need to set up the background for the first plot, then turn it off it for the second plot. If you previously set a plot area background image, you can disable it for subsequent plots with SetPlotAreaBgImage(NULL). If you previously set and enabled a plot area background color, you can disable it for subsequent plots with SetDrawPlotAreaBackground(FALSE).

4.8.2.8. Axis Positioning

You can position the X and Y axis manually with SetXAxisPosition and SetYAxisPosition, or you can let PHPlot calculate the axis positions for you. Whether you set the positions yourself, or let PHPlot calculate them for you, those positions apply to subsequent plots unless overridden. Even if you set a new data array, PHPlot will not recalculate the axis positions unless told to.

If you want PHPlot to automatically re-calculate the X axis position for a subsequent plot, use SetXAxisPosition() (with no arguments), or SetXAxisPosition(''). To restore automatic Y axis position calculation, use SetYAxisPosition() or SetYAxisPosition('').

4.8.3. Summary - Tiled Multiple Plots

Here are some guidelines for tiling multiple plots:

  • Unless all plots will use the same X and Y data ranges, use SetPlotAreaWorld with each plot. Call the function with no arguments to have PHPlot automatically calculate the data range for the plot, or supply arguments to explicitly set a data range.

  • Use SetPlotAreaPixels to set the area within the image for each plot. Remember to leave room for axis labels and titles.

  • If you want a legend for each plot, use SetLegendPixels, SetLegendWorld, or SetLegendPosition to position it. Or let the position default to the upper right corner of each plot. If instead you want a single legend, for example outside all the plot areas, either set it up for the last plot, or set it up for any plot and cancel it for the next plot. Position the single legend with SetLegendPixels, or with SetLegendPosition using any mode except 'world'.

  • You can only have one main title for the entire image.

4.8.4. Summary - Overlay Multiple Plots

Here are some guidelines for overlaying multiple plots:

  • All plots will use the same data scaling by default, whether automatically calculated by PHPlot or set with SetPlotAreaWorld. Use SetPlotAreaWorld if you want different data scaling for subsequent plots.

  • You can let PHPlot calculate the plot window by default, but it will not account for additional margin space needed by plots after the first. Instead, you can use SetPlotAreaPixels or SetMarginsPixels to set a specific plot area to use for all plots.

  • Set the tick increments you want for each plot, especially if the data ranges differ. You can have two sets of tick marks and labels if you position them on the opposite sides of the plot area.

  • Draw grid lines, if you want them, only for the first plot, and turn them off for the second plot.

  • If you want a single legend, either set it up for the last plot, or set it up for any plot and cancel it for the next plot. If you want multiple legends, one per overlay, position them manually with SetLegendWorld, SetLegendPixels, or SetLegendPosition.

  • If you want a plot area background, you must set it for the first plot and cancel it for the second plot, or it will hide the plots.

4.8.5. Multiple Plots - History

A number of fixes were made in PHPlot-5.3.1 that affect multiple plots per image. If you are creating multiple plot images using PHPlot-5.3.0 or earlier, you should upgrade to the latest release. If you are unable to upgrade, you may need to work around the following issues:

  • Color allocation: In PHPlot-5.2.0 and PHPlot-5.3.0, the data color array (whether defaulted or set with SetDataColors) was truncated to the number of colors required for a plot. This means that the additional colors were not available for subsequent plots, so the data colors would repeat. For example, if plot #1 used 3 colors for 3 data sets, and plot #2 had 5 data sets, only 3 colors were available and the first two colors would be reused for the 4th and 5th data sets. To work around this, you can reload the data colors before each subsequent plot. To reload the default data colors, use $plot->SetDataColors(False). Another work-around is to define a custom data color callback, which turns off the color slot optimization.

  • Legend positioning using SetLegendWorld was not correctly applied to subsequent plots in an image through PHPlot-5.3.0. If you have multiple side-by-side plots and you want the legend in the same world coordinate position in each plot, you still need to use SetLegendWorld(..., ...) when creating each plot.

  • Through PHPlot-5.3.0, there was no way to reset the X axis position or Y axis position to the default of automatic positioning. That is, SetXAxisPosition(), SetXAxisPosition(''), SetYAxisPosition(), and SetYAxisPosition('') did not work. There is no work-around to get automatic positioning of the axis lines.

  • Through PHPlot-5.3.0, several functions had more restricted usage when resetting to defaults.

    • Use SetLegendPixels(NULL, NULL) rather than SetLegendPixels().

    • Use SetNumXTicks('') and SetNumYTicks('') rather than SetNumXTicks() and SetNumYTicks().

    • Use SetLegend(array()) rather than SetLegend(NULL).

SourceForge.net Logo

This version of the manual was produced for the PHPlot Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the PHPlot project downloads area.