4.7. Tuning Parameters

This section documents some PHPlot class member variables that can be used to adjust the appearance of plots. You should rarely find it necessary to change these, and PHPlot does not provide "Set" functions for them.

The class member variables listed in Section 10.1, “List of Member Variables” are generally reserved for use only by the class implementation itself. But there are some adjustments you can make to the appearance of a plot only by changing member variables. This section documents some PHPlot class member variables that alter a plot appearance, but which do not have any defined class functions for you to use to set the values.

For example, if you want PHPlot to draw the X/Y grid above (after) the plot, rather than behind it, you would do the following:

$plot = new PHPlot(800, 600);
...
$plot->grid_at_foreground = TRUE; // Draw grid after plot

4.7.1. Tuning Bar Charts

These variables affect plot types bars and stackedbars. They are used to control the width of the bars. (For horizontal plots, the "width" of the bars is actually the height.)

bar_extra_space

Controls the amount of extra space within each group of bars. Default is 0.5, meaning 1/2 of the width of one bar is left as a gap, within the space allocated to the group (see group_frac_width). Increasing this makes each group of bars shrink together. Decreasing this makes the group of bars expand within the allocated space.

group_frac_width

Controls the amount of available space used by each bar group. Default is 0.7, meaning the group of bars fills 70% of the available space (but that includes the empty space due to bar_extra_space). Increasing this makes the group of bars wider.

bar_width_adjust

Controls the width of each bar. Default is 1.0. Decreasing this makes individual bars narrower, leaving gaps between the bars in a group. This must be greater than 0. If it is greater than 1, the bars will overlap.

If bar_extra_space=0, group_frac_width=1, and bar_width_adjust=1 then all the bars touch (within each group, and adjacent groups).

4.7.2. Tuning Box Plots

These variables affect plot type boxes. (Box Plots were added in PHPlot-6.1.0.)

boxes_max_width

This is one half the maximum width of the boxes. The default is 8 pixels.

boxes_min_width

This is one half the minimum width of the boxes. The default is 2 pixels.

boxes_frac_width

This is the fractional amount of the available space (plot width area divided by number of points) to use for half the width of the boxes. The default is 0.3. This needs to be less than 0.5 or there will be overlap between adjacent boxes.

boxes_t_width

This is the ratio of the width of the 'T' ends of the whiskers to the width of the boxes. The default is 0.6, meaning the 'T' ends are 60% of the width of the boxes.

PHPlot calculates the width of the boxes in a box plot in the same way as it does for OHLC and candlestick plots (see Section 4.7.4, “Tuning OHLC Charts”). Half of the width of each box is:

half_width = max(boxes_min_width, min(boxes_max_width, boxes_frac_width * avail_area))
Where avail_area = plot_area_width / number_data_points

4.7.3. Tuning Bubble Plots

These two variables set the range of bubble size in bubbles plots.

bubbles_min_size

Minimum bubble diameter in pixels.

bubbles_max_size

Maximum bubble diameter in pixels.

The point with the smallest Z value will be drawn as a bubble with a diameter of bubbles_min_size, and the point with the largest Z value will be drawn as a bubble with a diameter of bubbles_max_size. That is, PHPlot linearly maps the range of Z values in the plot to the range of bubble sizes.

By default, the minimum bubble size is 6 pixels, and the maximum bubble size is 1/12 times the smaller of the plot area width and plot area height. For example, if the plot area is 800x600, the default maximum bubble size will be 50 pixels (600 / 12).

4.7.4. Tuning OHLC Charts

These variables affect plot types ohlc, candlesticks, and candlesticks2, For candlesticks plots, they adjust the calculation of the width of the candlestick body. For basic OHLC plots, they adjust the calculation of the length of the tick marks which represent opening and closing prices. (All of these were added in PHPlot-5.3.0.)

ohlc_max_width

This is one half the maximum width of the candlestick body, or the maximum length of an OHLC tick mark. The default is 8 pixels.

ohlc_min_width

This is one half the minimum width of the candlestick body, or the minimum length of an OHLC tick mark. The default is 2 pixels.

ohlc_frac_width

This is the fractional amount of the available space (plot width area divided by number of points) to use for half the width of the candlestick bodies or OHLC tick marks. The default is 0.3. This needs to be less than 0.5 or there will be overlap between adjacent candlesticks.

PHPlot calculates a value to use for one half the width of the candlestick bodies, or for the OHLC open/close tick mark lengths, as follows:

half_width = max(ohlc_min_width, min(ohlc_max_width, ohlc_frac_width * avail_area))
Where avail_area = plot_area_width / number_data_points

4.7.5. Tuning Pie Charts

These variables adjusts the appearance of pie charts.

pie_diam_factor

Diameter factor for shaded pie charts. This is the ratio of the height to the width of the pie. The default value is 0.5, meaning the pie chart will be drawn as an ellipse with height equal to half of its width. This variable is ignored for unshaded plots (see SetShading), which are always circular (diameter factor of 1.0).

pie_min_size_factor

The minimum size of the pie in a pie chart, relative to the plot area size. When pie chart autosizing is on (see SetPieAutoSize), and pie labels are located outside the pie chart (as they are by default), PHPlot will shrink the pie so the labels will fit inside the plot area. To prevent an overly long label from making the pie too small, PHPlot uses pie_min_size_factor to limit how small the pie will become. The default value is 0.5, meaning the pie chart will be no smaller than half the width or height of the plot area, even if that makes the labels fall partly off the image.

Setting this smaller allows the pie to be a smaller portion of the plot area, if long labels require the space. Setting this larger prevents the pie from becoming smaller in that case. Setting this to 1.0 is approximately equivalent to using SetPieAutoSize(False). (The difference is that the later still leaves a small gap between the pie and the plot area boundary.)

4.7.6. Tuning the Legend

This variable adjusts the appearance of the legend.

legend_colorbox_width

This is an adjustment factor for the width of the color boxes in the legend. With the default value 1.0, the color boxes are as wide as one character in the font used in the legend (width of "E" for TrueType fonts). A value of 2.0 makes the color boxes twice as wide, and 0.5 makes them half the character width. (This was added in PHPlot-5.3.0.)

If point shapes are used in the legend instead of color boxes (see SetLegendUseShapes - for points plots and similar), then legend_colorbox_width still adjusts the horizontal space allocated for the point shape. The point shape itself is not scaled, but is always drawn at the same size as in the plot itself. If the plot area has a color background, the width adjustment will stretch the box in that color which is drawn behind the point shape.

If line markers are used in the legend of instead of color boxes (see SetLegendUseShapes - with line plots and similar), then legend_colorbox_width scales the horizontal space allocated for the line marker, but there is an additional factor of 4 applied by PHPlot. This leaves enough room to draw a line segment that can be identified visually by color and width.

4.7.7. Tuning Labels

These variables affect the appearance of labels.

data_value_label_angle

This sets the angle, in degrees, for the position of data value labels near the data points they label. Together with data_value_label_distance, it determines the position of the reference point for the label. (This does not apply to data value labels for bars or stackedbars plots, as the label position is fixed for these plot types.) The default is 90 degrees, which places the label above the data point. PHPlot automatically selects which text alignment to use, based on the angle. For example, with the default 90 degree angle, the label will be horizontally centered, vertically bottom aligned. If the angle is 0 degrees, the alignment is horizontally left, vertically centered.

data_value_label_distance

This sets the distance, in pixels, for the position of data value labels near the data points they label. Together with data_value_label_angle, it determines the position of the reference point for the label. (This does not apply to data value labels for bars or stackedbars plots, as the label position is fixed for these plot types.) The default is 5 pixels.

4.7.8. Miscellaneous Tuning

These variables affect other aspects of the appearance of a plot.

grid_at_foreground

Controls the order in which certain plot elements are drawn. The default is FALSE, meaning the X axis, Y axis, and grid lines are drawn before the main part of the plot. If TRUE, the X axis, Y axis, and grid lines are drawn after the main part of the plot, which results in the grid lines overlaying the plotted data.

locale_override

Set this to TRUE (or any non-empty value) to prevent PHPlot from loading information about the locale from the operating system. You must do this if you want to override the locale using setlocale() from your PHP code, perhaps because your platform does not allow setting the locale from environment variables. See SetNumberFormat for more information.

safe_margin

This is the amount of space that PHPlot leaves between elements that should not touch. The default is 5 pixels. Changing this is not recommended. The effect is similar to changing the cellpadding on an HTML table.

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.