Subversion Repositories cheapmusic

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
98 - 1
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
2
<!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>
3
This section documents some PHPlot class member variables that can be used
4
to adjust the appearance of plots.
5
You should rarely find it necessary to change these, and PHPlot does not
6
provide "Set" functions for them.
7
  </p></div><p>
8
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
9
generally reserved for use only by the class implementation itself. But
10
there are some adjustments you can make to the appearance of a plot only
11
by changing member variables.
12
This section documents some PHPlot class member variables that alter a plot
13
appearance, but which do not have any defined class functions for you to
14
use to set the values.
15
</p><p>
16
For example, if you want PHPlot to draw the X/Y grid above (after) the plot,
17
rather than behind it, you would do the following:
18
  </p><pre class="programlisting">$plot = new PHPlot(800, 600);
19
...
20
$plot-&gt;grid_at_foreground = TRUE; // Draw grid after plot
21
</pre><p>
22
</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>
23
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>
24
and <a class="link" href="conc-plottypes.html#plottype-stackedbars" title="3.4.15. Plot Type: stackedbars (Stacked Bar Plot)">stackedbars</a>.
25
They are used to control the width of the bars.
26
(For horizontal plots, the "width" of the bars is actually the height.)
27
</p><p>
28
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">bar_extra_space</code></span></dt><dd><p>
29
Controls the amount of extra space within each group of bars. Default is 0.5,
30
meaning 1/2 of the width of one bar is left as a gap, within the space
31
allocated to the group (see <code class="varname">group_frac_width</code>).
32
Increasing this makes each group of bars shrink together.
33
Decreasing this makes the group of bars expand within the allocated space.
34
        </p></dd><dt><span class="term"><code class="varname">group_frac_width</code></span></dt><dd><p>
35
Controls the amount of available space used by each bar group. Default is 0.7,
36
meaning the group of bars fills 70% of the available space (but that includes
37
the empty space due to <code class="varname">bar_extra_space</code>).
38
Increasing this makes the group of bars wider.
39
        </p></dd><dt><span class="term"><code class="varname">bar_width_adjust</code></span></dt><dd><p>
40
Controls the width of each bar. Default is 1.0.
41
Decreasing this makes individual bars narrower, leaving gaps between the
42
bars in a group. This must be greater than 0. If it is greater than 1, the
43
bars will overlap.
44
        </p></dd></dl></div><p>
45
If bar_extra_space=0, group_frac_width=1, and bar_width_adjust=1
46
then all the bars touch (within each group, and adjacent groups).
47
</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>
48
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>.
49
(Box Plots were added in PHPlot-6.1.0.)
50
</p><p>
51
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">boxes_max_width</code></span></dt><dd><p>
52
This is one half the maximum width of the boxes. The default is 8 pixels.
53
        </p></dd><dt><span class="term"><code class="varname">boxes_min_width</code></span></dt><dd><p>
54
This is one half the minimum width of the boxes. The default is 2 pixels.
55
        </p></dd><dt><span class="term"><code class="varname">boxes_frac_width</code></span></dt><dd><p>
56
This is the fractional amount of the available space (plot width area
57
divided by number of points) to use for half the width of the boxes.
58
The default is 0.3. This needs to be less than 0.5 or there will be
59
overlap between adjacent boxes.
60
        </p></dd><dt><span class="term"><code class="varname">boxes_t_width</code></span></dt><dd><p>
61
This is the ratio of the width of the 'T' ends of the whiskers to the
62
width of the boxes.  The default is 0.6, meaning the 'T' ends are 60%
63
of the width of the boxes.
64
        </p></dd></dl></div><p>
65
</p><p>
66
PHPlot calculates the width of the boxes in a box plot in the same way as
67
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>).
68
Half of the width of each box is:
69
</p><pre class="programlisting">half_width = max(boxes_min_width, min(boxes_max_width, boxes_frac_width * avail_area))
70
Where avail_area = plot_area_width / number_data_points
71
</pre><p>
72
</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>
73
These two variables set the range of bubble size in
74
<a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a> plots.
75
</p><p>
76
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">bubbles_min_size</code></span></dt><dd><p>
77
Minimum bubble diameter in pixels.
78
        </p></dd><dt><span class="term"><code class="varname">bubbles_max_size</code></span></dt><dd><p>
79
Maximum bubble diameter in pixels.
80
        </p></dd></dl></div><p>
81
</p><p>
82
The point with the smallest Z value will be drawn as a bubble with a diameter
83
of bubbles_min_size, and the point with the largest Z value will be drawn as
84
a bubble with a diameter of bubbles_max_size. That is, PHPlot linearly maps
85
the range of Z values in the plot to the range of bubble sizes.
86
</p><p>
87
By default, the minimum bubble size is 6 pixels, and the maximum bubble
88
size is 1/12 times the smaller of the plot area width and plot area height.
89
For example, if the plot area is 800x600, the default maximum bubble size
90
will be 50 pixels (600 / 12).
91
</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>
92
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>,
93
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>,
94
and <a class="link" href="conc-plottypes.html#plottype-candlesticks2" title="3.4.6. Plot Type: candlesticks2 (OHLC Filled Candlesticks Plot)">candlesticks2</a>,
95
For candlesticks plots, they adjust the calculation of the width of the
96
candlestick body.
97
For basic OHLC plots, they adjust the calculation of the length of the tick
98
marks which represent opening and closing prices.
99
(All of these were added in PHPlot-5.3.0.)
100
</p><p>
101
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">ohlc_max_width</code></span></dt><dd><p>
102
This is one half the maximum width of the candlestick body, or
103
the maximum length of an OHLC tick mark. The default is 8 pixels.
104
        </p></dd><dt><span class="term"><code class="varname">ohlc_min_width</code></span></dt><dd><p>
105
This is one half the minimum width of the candlestick body, or
106
the minimum length of an OHLC tick mark. The default is 2 pixels.
107
        </p></dd><dt><span class="term"><code class="varname">ohlc_frac_width</code></span></dt><dd><p>
108
This is the fractional amount of the available space (plot width area
109
divided by number of points) to use for half the width of the candlestick
110
bodies or OHLC tick marks. The default is 0.3. This needs to be less than
111
0.5 or there will be overlap between adjacent candlesticks.
112
        </p></dd></dl></div><p>
113
</p><p>
114
PHPlot calculates a value to use for one half the width of the candlestick
115
bodies, or for the OHLC open/close tick mark lengths, as follows:
116
</p><pre class="programlisting">half_width = max(ohlc_min_width, min(ohlc_max_width, ohlc_frac_width * avail_area))
117
Where avail_area = plot_area_width / number_data_points
118
</pre><p>
119
</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>
120
These variables adjusts the appearance of
121
<a class="link" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">pie charts</a>.
122
</p><p>
123
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">pie_diam_factor</code></span></dt><dd><p>
124
Diameter factor for shaded pie charts. This is the ratio of the height to
125
the width of the pie. The default value is 0.5, meaning the pie chart will be
126
drawn as an ellipse with height equal to half of its width.
127
This variable is ignored for unshaded plots (see <a class="xref" href="SetShading.html" title="SetShading"><span class="refentrytitle">SetShading</span></a>),
128
which are always circular (diameter factor of 1.0).
129
        </p></dd><dt><span class="term"><code class="varname">pie_min_size_factor</code></span></dt><dd><p>
130
The minimum size of the pie in a pie chart, relative to the plot area size.
131
When pie chart autosizing is on (see <a class="xref" href="SetPieAutoSize.html" title="SetPieAutoSize"><span class="refentrytitle">SetPieAutoSize</span></a>),
132
and pie labels are located outside the pie chart (as they are by default),
133
PHPlot will shrink the pie so the labels will fit inside the plot area.
134
To prevent an overly long label from making the pie too small,
135
PHPlot uses <code class="varname">pie_min_size_factor</code> to limit
136
how small the pie will become.
137
The default value is 0.5, meaning the pie chart will be no smaller than
138
half the width or height of the plot area, even if that makes the labels
139
fall partly off the image.
140
        </p><p>
141
Setting this smaller allows the pie to be a smaller portion of the plot
142
area, if long labels require the space. Setting this larger prevents the
143
pie from becoming smaller in that case.
144
Setting this to 1.0 is approximately equivalent to using
145
<code class="literal">SetPieAutoSize(False)</code>. (The difference is that the
146
later still leaves a small gap between the pie and the plot area boundary.)
147
        </p></dd></dl></div><p>
148
</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>
149
This variable adjusts the appearance of the legend.
150
</p><p>
151
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">legend_colorbox_width</code></span></dt><dd><p>
152
This is an adjustment factor for the width of the color boxes in the legend.
153
With the default value 1.0, the color boxes are as wide as one character in
154
the font used in the legend (width of "E" for TrueType fonts).
155
A value of 2.0 makes the color boxes twice as wide, and 0.5 makes them half
156
the character width.
157
(This was added in PHPlot-5.3.0.)
158
        </p><p>
159
If point shapes are used in the legend instead of color boxes
160
(see <a class="xref" href="SetLegendUseShapes.html" title="SetLegendUseShapes"><span class="refentrytitle">SetLegendUseShapes</span></a> - for points plots and similar),
161
then <code class="literal">legend_colorbox_width</code> still adjusts the horizontal
162
space allocated for the point shape. The point shape itself is not scaled,
163
but is always drawn at the same size as in the plot itself. If the plot
164
area has a color background, the width adjustment will stretch the
165
box in that color which is drawn behind the point shape.
166
        </p><p>
167
If line markers are used in the legend of instead of color boxes (see
168
<a class="xref" href="SetLegendUseShapes.html" title="SetLegendUseShapes"><span class="refentrytitle">SetLegendUseShapes</span></a> - with line plots and similar),
169
then <code class="literal">legend_colorbox_width</code> scales the horizontal
170
space allocated for the line marker, but there is an additional factor
171
of 4 applied by PHPlot.
172
This leaves enough room to draw a line segment that can be identified
173
visually by color and width.
174
        </p></dd></dl></div><p>
175
</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>
176
These variables affect the appearance of labels.
177
</p><p>
178
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">data_value_label_angle</code></span></dt><dd><p>
179
This sets the angle, in degrees, for the position of data value labels near
180
the data points they label.
181
Together with <code class="varname">data_value_label_distance</code>,
182
it determines the position of the reference point for the label.
183
(This does not apply to data value labels for bars or stackedbars plots, as
184
the label position is fixed for these plot types.)
185
The default is 90 degrees, which places the label above the data point.
186
PHPlot automatically selects which text alignment to use, based on the angle.
187
For example, with the default 90 degree angle, the label will
188
be horizontally centered, vertically bottom aligned.  If the angle is 0
189
degrees, the alignment is horizontally left, vertically centered.
190
        </p></dd><dt><span class="term"><code class="varname">data_value_label_distance</code></span></dt><dd><p>
191
This sets the distance, in pixels, for the position of data value labels near
192
the data points they label.
193
Together with <code class="varname">data_value_label_angle</code>,
194
it determines the position of the reference point for the label.
195
(This does not apply to data value labels for bars or stackedbars plots, as
196
the label position is fixed for these plot types.)
197
The default is 5 pixels.
198
        </p></dd></dl></div><p>
199
</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>
200
These variables affect other aspects of the appearance of a plot.
201
</p><p>
202
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">grid_at_foreground</code></span></dt><dd><p>
203
Controls the order in which certain plot elements are drawn. The default is
204
FALSE, meaning the X axis, Y axis, and grid lines are drawn before the main
205
part of the plot. If TRUE, the X axis, Y axis, and grid lines are drawn
206
after the main part of the plot, which results in the grid lines overlaying
207
the plotted data.
208
        </p></dd><dt><span class="term"><code class="varname">locale_override</code></span></dt><dd><p>
209
Set this to TRUE (or any non-empty value) to prevent PHPlot from loading
210
information about the locale from the operating system.
211
You must do this if you want to override the locale using
212
<code class="function">setlocale()</code> from your PHP code, perhaps because your
213
platform does not allow setting the locale from environment variables.
214
See <a class="xref" href="SetNumberFormat.html" title="SetNumberFormat"><span class="refentrytitle">SetNumberFormat</span></a> for more information.
215
        </p></dd><dt><span class="term"><code class="varname">safe_margin</code></span></dt><dd><p>
216
This is the amount of space that PHPlot leaves between elements that
217
should not touch. The default is 5 pixels. Changing this is not recommended.
218
The effect is similar to changing the cellpadding on an HTML table.
219
        </p></dd></dl></div><p>
220
</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>