Subversion Repositories cheapmusic

Rev

Blame | Last modification | View Log | RSS feed 

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>4.7. Tuning Parameters</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="advanced.html" title="Chapter 4. PHPlot Advanced Topics" /><link rel="prev" href="adv-autorange.html" title="4.6. Plot Range and Tick Increment Calculations" /><link rel="next" href="adv-multiplot.html" title="4.8. Multiple Plots Per Image" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.7. Tuning Parameters</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adv-autorange.html">Prev</a> </td><th width="60%" align="center">Chapter 4. PHPlot Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="adv-multiplot.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adv-tuning"></a>4.7. Tuning Parameters</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
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.
  </p></div><p>
The class member variables listed in <a class="xref" href="dev-vars.html#dev-vars-list" title="10.1. List of Member Variables">Section 10.1, &#8220;List of Member Variables&#8221;</a> 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.
</p><p>
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:
  </p><pre class="programlisting">$plot = new PHPlot(800, 600);
...
$plot-&gt;grid_at_foreground = TRUE; // Draw grid after plot
</pre><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-bars"></a>4.7.1. Tuning Bar Charts</h3></div></div></div><p>
These variables affect plot types <a class="link" href="conc-plottypes.html#plottype-bars" title="3.4.2. Plot Type: bars (Bar Plot)">bars</a>
and <a class="link" href="conc-plottypes.html#plottype-stackedbars" title="3.4.15. Plot Type: stackedbars (Stacked Bar Plot)">stackedbars</a>.
They are used to control the width of the bars.
(For horizontal plots, the "width" of the bars is actually the height.)
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">bar_extra_space</code></span></dt><dd><p>
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 <code class="varname">group_frac_width</code>).
Increasing this makes each group of bars shrink together.
Decreasing this makes the group of bars expand within the allocated space.
        </p></dd><dt><span class="term"><code class="varname">group_frac_width</code></span></dt><dd><p>
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 <code class="varname">bar_extra_space</code>).
Increasing this makes the group of bars wider.
        </p></dd><dt><span class="term"><code class="varname">bar_width_adjust</code></span></dt><dd><p>
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.
        </p></dd></dl></div><p>
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).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-boxes"></a>4.7.2. Tuning Box Plots</h3></div></div></div><p>
These variables affect plot type <a class="link" href="conc-plottypes.html#plottype-boxes" title="3.4.3. Plot Type: boxes (Box Plot)">boxes</a>.
(Box Plots were added in PHPlot-6.1.0.)
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">boxes_max_width</code></span></dt><dd><p>
This is one half the maximum width of the boxes. The default is 8 pixels.
        </p></dd><dt><span class="term"><code class="varname">boxes_min_width</code></span></dt><dd><p>
This is one half the minimum width of the boxes. The default is 2 pixels.
        </p></dd><dt><span class="term"><code class="varname">boxes_frac_width</code></span></dt><dd><p>
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.
        </p></dd><dt><span class="term"><code class="varname">boxes_t_width</code></span></dt><dd><p>
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.
        </p></dd></dl></div><p>
</p><p>
PHPlot calculates the width of the boxes in a box plot in the same way as
it does for OHLC and candlestick plots (see <a class="xref" href="adv-tuning.html#adv-tuning-ohlc" title="4.7.4. Tuning OHLC Charts">Section 4.7.4, &#8220;Tuning OHLC Charts&#8221;</a>).
Half of the width of each box is:
</p><pre class="programlisting">half_width = max(boxes_min_width, min(boxes_max_width, boxes_frac_width * avail_area))
Where avail_area = plot_area_width / number_data_points
</pre><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-bubbles"></a>4.7.3. Tuning Bubble Plots</h3></div></div></div><p>
These two variables set the range of bubble size in
<a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a> plots.
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">bubbles_min_size</code></span></dt><dd><p>
Minimum bubble diameter in pixels.
        </p></dd><dt><span class="term"><code class="varname">bubbles_max_size</code></span></dt><dd><p>
Maximum bubble diameter in pixels.
        </p></dd></dl></div><p>
</p><p>
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.
</p><p>
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).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-ohlc"></a>4.7.4. Tuning OHLC Charts</h3></div></div></div><p>
These variables affect plot types <a class="link" href="conc-plottypes.html#plottype-ohlc" title="3.4.9. Plot Type: ohlc (Basic OHLC Plot)">ohlc</a>,
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>,
and <a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>,
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.)
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">ohlc_max_width</code></span></dt><dd><p>
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.
        </p></dd><dt><span class="term"><code class="varname">ohlc_min_width</code></span></dt><dd><p>
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.
        </p></dd><dt><span class="term"><code class="varname">ohlc_frac_width</code></span></dt><dd><p>
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.
        </p></dd></dl></div><p>
</p><p>
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:
</p><pre class="programlisting">half_width = max(ohlc_min_width, min(ohlc_max_width, ohlc_frac_width * avail_area))
Where avail_area = plot_area_width / number_data_points
</pre><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-pie"></a>4.7.5. Tuning Pie Charts</h3></div></div></div><p>
These variables adjusts the appearance of
<a class="link" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">pie charts</a>.
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">pie_diam_factor</code></span></dt><dd><p>
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 <a class="xref" href="SetShading.html" title="SetShading"><span class="refentrytitle">SetShading</span></a>),
which are always circular (diameter factor of 1.0).
        </p></dd><dt><span class="term"><code class="varname">pie_min_size_factor</code></span></dt><dd><p>
The minimum size of the pie in a pie chart, relative to the plot area size.
When pie chart autosizing is on (see <a class="xref" href="SetPieAutoSize.html" title="SetPieAutoSize"><span class="refentrytitle">SetPieAutoSize</span></a>),
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 <code class="varname">pie_min_size_factor</code> 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.
        </p><p>
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
<code class="literal">SetPieAutoSize(False)</code>. (The difference is that the
later still leaves a small gap between the pie and the plot area boundary.)
        </p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-legend"></a>4.7.6. Tuning the Legend</h3></div></div></div><p>
This variable adjusts the appearance of the legend.
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">legend_colorbox_width</code></span></dt><dd><p>
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.)
        </p><p>
If point shapes are used in the legend instead of color boxes
(see <a class="xref" href="SetLegendUseShapes.html" title="SetLegendUseShapes"><span class="refentrytitle">SetLegendUseShapes</span></a> - for points plots and similar),
then <code class="literal">legend_colorbox_width</code> 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.
        </p><p>
If line markers are used in the legend of instead of color boxes (see
<a class="xref" href="SetLegendUseShapes.html" title="SetLegendUseShapes"><span class="refentrytitle">SetLegendUseShapes</span></a> - with line plots and similar),
then <code class="literal">legend_colorbox_width</code> 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.
        </p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-labels"></a>4.7.7. Tuning Labels</h3></div></div></div><p>
These variables affect the appearance of labels.
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">data_value_label_angle</code></span></dt><dd><p>
This sets the angle, in degrees, for the position of data value labels near
the data points they label.
Together with <code class="varname">data_value_label_distance</code>,
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.
        </p></dd><dt><span class="term"><code class="varname">data_value_label_distance</code></span></dt><dd><p>
This sets the distance, in pixels, for the position of data value labels near
the data points they label.
Together with <code class="varname">data_value_label_angle</code>,
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.
        </p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-tuning-misc"></a>4.7.8. Miscellaneous Tuning</h3></div></div></div><p>
These variables affect other aspects of the appearance of a plot.
</p><p>
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">grid_at_foreground</code></span></dt><dd><p>
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.
        </p></dd><dt><span class="term"><code class="varname">locale_override</code></span></dt><dd><p>
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
<code class="function">setlocale()</code> from your PHP code, perhaps because your
platform does not allow setting the locale from environment variables.
See <a class="xref" href="SetNumberFormat.html" title="SetNumberFormat"><span class="refentrytitle">SetNumberFormat</span></a> for more information.
        </p></dd><dt><span class="term"><code class="varname">safe_margin</code></span></dt><dd><p>
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.
        </p></dd></dl></div><p>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adv-autorange.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adv-multiplot.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.6. Plot Range and Tick Increment Calculations </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.8. Multiple Plots Per Image</td></tr></table></div></body></html>