4.5. Tuning Parameters
Prev | Chapter 4. PHPlot Advanced Topics | Next

## 4.5. 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.5.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.5.2. 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 in pixels of the candlestick body or OHLC tick mark. The default is 8.

`ohlc_min_width`

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

`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.5.3. 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.)

### 4.5.4. Label Tuning

These variables affect the display 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 if unset 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 if unset is 5 pixels.

### 4.5.5. 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.

Prev | Up | Next
4.4. Custom Data Color Selection | Home | 4.6. Multiple Plots Per Image