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.6. Plot Range and Tick Increment Calculations</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-datacolor-callback.html" title="4.5. Custom Data Color Selection" /><link rel="next" href="adv-tuning.html" title="4.7. Tuning Parameters" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.6. Plot Range and Tick Increment Calculations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adv-datacolor-callback.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-tuning.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-autorange"></a>4.6. Plot Range and Tick Increment Calculations</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
3 
This section describes how PHPlot calculates the range of
4 
<a class="link" href="concepts.html#def-worldcoor">World Coordinate</a> space, and the tick
5 
increment for each axis, when those values have not been set manually.
6 
  </p></div><p>
7 
In order to plot a data set, PHPlot needs to map the data points from world
8 
coordinate space to device coordinate space. The world coordinates of the
9 
data points are generally in real-world units, such as kilometers, seconds,
10 
degrees centigrade, etc. Device coordinates are pixels in an image file,
11 
display screen, or paper hardcopy. PHPlot knows the pixel coordinates of
12 
the limits of the plot area in device space.  In order to translate data
13 
points from world coordinates into pixel coordinates, it needs to know the
14 
limits of world coordinate space.  These can be provided manually, or
15 
computed by PHPlot.
16 
</p><p>
17 
The limits of world coordinate space are the end-points of the X and Y axis
18 
lines.  The two end-points of an axis are also referred to as the plot
19 
range along that axis.  Each of those plot ranges is divided into uniformly
20 
sized tick intervals, which may or may not be marked by visible tick marks.
21 
The space between tick marks is called the tick increment. PHPlot will
22 
calculate a suitable tick increment if necessary.
23 
</p><p>
24 
The rest of this section describes how PHPlot calculates the limits of the
25 
plot ranges, and the tick increments.
26 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
27 
This section does not apply to pie charts, which do not have X or Y axis lines.
28 
  </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-manual"></a>4.6.1. Manual (Fixed) Plot Range and Tick Increment</h3></div></div></div><p>
29 
If you use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set both
30 
<code class="varname">Xmin</code> and <code class="varname">Xmax</code> to non-NULL values,
31 
this will fix both ends of the X axis.  Similarly, setting both
32 
<code class="varname">Ymin</code> and <code class="varname">Ymax</code> to non-NULL values
33 
will fix both ends of the Y axis.
34 
If you set both ends of an axis, PHPlot will use exactly that for the plot
35 
range on that axis.  This is recommended if your data has a range which is
36 
known, predictable, and/or 'natural'. For example, if your Y axis represents
37 
percentage values from 0 to 100, you might use this to fix the Y axis ends:
38 
 
39 
</p><pre class="programlisting">$plot-&gt;SetPlotAreaWorld(NULL, 0, NULL, 100);
40 
</pre><p>
41 
</p><p>
42 
You can use <a class="xref" href="SetXTickIncrement.html" title="SetXTickIncrement"><span class="refentrytitle">SetXTickIncrement</span></a> to set a fixed X tick
43 
increment, and <a class="xref" href="SetYTickIncrement.html" title="SetYTickIncrement"><span class="refentrytitle">SetYTickIncrement</span></a> to set a fixed Y tick
44 
increment.
45 
If you set a fixed tick increment along an axis, PHPlot will use exactly
46 
that value (even if it results in too many, or too few tick marks).
47 
</p><p>
48 
Another way to manually specify tick increments is with
49 
<a class="xref" href="SetNumXTicks.html" title="SetNumXTicks"><span class="refentrytitle">SetNumXTicks</span></a> or <a class="xref" href="SetNumYTicks.html" title="SetNumYTicks"><span class="refentrytitle">SetNumYTicks</span></a>.
50 
These set the desired number of tick intervals.
51 
PHPlot will then calculate the tick increment by dividing the plot range into
52 
exactly that many intervals.
53 
For example, if the Y axis range is 0 to 17, and you use
54 
<code class="literal">$plot-&gt;SetNumYTicks(6)</code> to get 6 intervals, then the tick
55 
mark spacing will be about 2.833333.
56 
This is probably not a desirable value for the tick increment.
57 
Using <code class="function">SetNumXTicks</code> or <code class="function">SetNumYTicks</code>
58 
to set the number of tick intervals is usually not a good idea, unless you
59 
also set the plot range with <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>.
60 
</p><p>
61 
If you set both ends of the X or Y plot range, PHPlot will position
62 
tick marks starting from the lower end of that range, by default.
63 
For example, if you set the Y axis range from 1 to 20, with a tick
64 
increment of 5, the tick marks will be at 1, 6, 11, and 16.
65 
You can set a <span class="emphasis"><em>tick anchor</em></span> to change this.
66 
See <a class="xref" href="adv-autorange.html#adv-autorange-tick-positions" title="4.6.9. Tick Positions">Section 4.6.9, &#8220;Tick Positions&#8221;</a> below for more information.
67 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-partial"></a>4.6.2. Partial Fixed Plot Range</h3></div></div></div><p>
68 
If you use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set either
69 
<code class="varname">Xmin</code> or <code class="varname">Xmax</code> (but not both) to a
70 
non-NULL value, or you set either
71 
<code class="varname">Ymin</code> or <code class="varname">Ymax</code> (but not both) to a
72 
non-NULL value, then you are fixing one end of the plot range.
73 
PHPlot will use your fixed value for that end of the range, and calculate the
74 
other end as described below.
75 
</p><p>
76 
This may make sense if your data has a fixed lower (or upper) bound. For
77 
example, if you are plotting outdoor summer temperatures in degrees
78 
Fahrenheit, you might use something like this:
79 
</p><pre class="programlisting">$plot-&gt;SetPlotAreaWorld(NULL, 60);
80 
</pre><p>
81 
which sets Ymin to 60.
82 
</p><p>
83 
Since PHPlot positions tick marks starting from the lower limit of the X
84 
and Y plot ranges, setting <code class="varname">Xmin</code> or <code class="varname">Ymin</code>
85 
establishes the basis for tick marks along that axis.
86 
For example, if you set the lower end of the X axis range to 12, with a tick
87 
increment of 10, the tick marks along X will be at 12, 22, 32, etc.
88 
You can set a <span class="emphasis"><em>tick anchor</em></span> to change this.
89 
See <a class="xref" href="adv-autorange.html#adv-autorange-tick-positions" title="4.6.9. Tick Positions">Section 4.6.9, &#8220;Tick Positions&#8221;</a> below for more information.
90 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-range"></a>4.6.3. Automatic Range Calculation</h3></div></div></div><p>
91 
Each end of the plot range (for both X and Y) which is not specified using
92 
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> will be calculated by PHPlot.
93 
The algorithm used by PHPlot to calculate the ends of a plot range is not
94 
perfect, but is meant to create reasonable plots in a majority of cases.
95 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
96 
This description applies starting with PHPlot-6.0.0. In older versions,
97 
PHPlot used a more simplistic approach to calculating the plot range.
98 
  </p></div><p>
99 
Here is an overview of the method, using the Y axis as an example.
100 
<code class="literal">DataMin</code> and <code class="literal">DataMax</code>
101 
are the smallest and largest Y values in the data array (or the values
102 
derived from the data array, for some plot types).
103 
<code class="literal">PlotMin</code> and <code class="literal">PlotMax</code> are the
104 
calculated limits of the plot range. Remember that PHPlot only calculates
105 
PlotMax and PlotMin if they have not already been set using
106 
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>.
107 
 
108 
  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
109 
Initialization:
110 
Start by setting the plot range to the data range: PlotMin = DataMin, and
111 
PlotMax = DataMax. The plot range will now include all the data, but just
112 
barely.
113 
      </p></li><li class="listitem"><p>
114 
Zero Magnet:
115 
If the plot range does not currently include zero
116 
(PlotMin &lt;= 0 and 0 &lt;= PlotMax), PHPlot tries to extend the range so it
117 
will begin or end at zero. This is done by either by moving PlotMin down to
118 
zero (for positive data), or by moving PlotMax up to zero (for negative data).
119 
There is a limit as to how far PHPlot is willing to extend the plot range
120 
to include zero (see below).
121 
      </p></li><li class="listitem"><p>
122 
End Adjust / Increase range:
123 
PHPlot may then adjust the ends of the plot range by a factor
124 
(adjust_amount) multiplied by the plot range.  This provides some extra
125 
room above or below the data for data value labels, and prevents the top
126 
(or bottom) of the plotted data from hitting the edge of the plot area,
127 
which would detract from the appearance. Adjustment only occurs for PlotMin
128 
if it is negative, and for PlotMax if it is positive. This corresponds to
129 
the direction of the plot data 'away' from zero.
130 
 
131 
For example, if 0 &lt; PlotMin &lt; PlotMax
132 
(all the data is positive), then PlotMax will be increased.
133 
 
134 
If PlotMin &lt; PlotMax &lt; 0 (all the data is negative),
135 
then PlotMin will be decreased.
136 
 
137 
If the range spans 0 with PlotMin &lt; 0 &lt; PlotMax,
138 
then both PlotMin will be decreased and PlotMax will be increased.
139 
      </p></li><li class="listitem"><p>
140 
End Adjust / Finalize:
141 
PHPlot may then adjust the ends of the plot range further, based on the
142 
adjustment mode (<code class="literal">adjust_mode</code>), but only if the end of
143 
the range is not already zero.
144 
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
145 
If the adjustment mode is <code class="literal">T</code> (Tick, the default mode),
146 
then PlotMax is adjusted up to the next higher tick mark position, and
147 
PlotMin is adjusted down to the next lower tick mark position. Note that
148 
this happens even if tick marks are not displayed.
149 
If a tick anchor is set, this is taken into account when adjusting the
150 
range (see <a class="xref" href="adv-autorange.html#adv-autorange-tick-positions" title="4.6.9. Tick Positions">Section 4.6.9, &#8220;Tick Positions&#8221;</a> below).
151 
            </p></li><li class="listitem"><p>
152 
If the adjustment mode is <code class="literal">R</code> (Range), there is no further
153 
adjustment.
154 
            </p></li><li class="listitem"><p>
155 
If the adjustment mode is <code class="literal">I</code> (Integer), then PlotMax is
156 
adjusted up to the next higher integer, and PlotMin is adjusted down to the
157 
next lower integer.
158 
            </p></li></ul></div><p>
159 
Note that adjustment modes <code class="literal">R</code> and <code class="literal">I</code> are
160 
intended for special applications where the default <code class="literal">T</code>
161 
(Tick) mode produces undesirable results.
162 
      </p></li></ol></div><p>
163 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-params"></a>4.6.4. Automatic Range Parameters</h3></div></div></div><p>
164 
The range calculation uses parameters which can be set using
165 
<a class="xref" href="TuneXAutoRange.html" title="TuneXAutoRange"><span class="refentrytitle">TuneXAutoRange</span></a> and <a class="xref" href="TuneYAutoRange.html" title="TuneYAutoRange"><span class="refentrytitle">TuneYAutoRange</span></a>.
166 
The parameters are described in the next sections.
167 
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autorange-zero-magnet"></a>4.6.4.1. Range parameter: zero_magnet</h4></div></div></div><p>
168 
The <code class="varname">zero_magnet</code> parameter sets the strength of the
169 
<span class="emphasis"><em>zero magnet</em></span>, which controls how far PHPlot is
170 
willing to extend the plot range to include zero, if the range does not
171 
already include zero.
172 
This is a floating point number greater than or equal to 0, and less than
173 
or equal to 1.0.
174 
A value of 0 means the magnet is disabled. PHPlot will not extend the
175 
plot range to include zero.
176 
A value of 1.0 means the magnet strength is infinite, and PHPlot will
177 
always extend the plot range to include zero.
178 
For increasing values between 0.0 and 1.0, the zero magnet becomes
179 
stronger, and PHPlot will go further in extending the plot range to include
180 
zero.
181 
</p><p>
182 
Between 0 and 1.0, the zero magnet factor is applied as follows. Let
183 
<span class="mathphrase">ZF = zero_magnet / (1 - zero_magnet)</span>.
184 
This maps the zero magnet domain of 0:1 into the range 0:infinity.
185 
PHPlot will extend the plot range to include 0 if that increases
186 
the range by a factor of ZF or less.
187 
</p><p>
188 
For example, the default zero magnet factor of 6/7 results in ZF=6, so
189 
PHPlot will 'pull' the bottom of the plot range down to zero if doing so
190 
will stretch the range by 600% or less. (If the data is all negative, it
191 
will apply the zero magnet to 'pushing' the top of the range to zero in the
192 
same manner.)
193 
If the data range is 500 to 600, PHPlot will adjust it to become 0 to 600,
194 
because adjusting the lower range by 500 is less than the maximum 6*100.
195 
If the data range is 900 to 1000, PHPlot will not adjust it to start at 0,
196 
because the zero magnet is only 'strong enough' to pull the range down by
197 
6*100, not 900.
198 
</p><p>
199 
The purpose of having a variable <span class="emphasis"><em>zero magnet</em></span> is
200 
to balance two conflicting goals:
201 
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
202 
Including zero in the data range improves the utility of plots,
203 
as it facilitates comparing relative changes and differences.
204 
      </p></li><li class="listitem"><p>
205 
Increasing the data range of a plot makes it harder to see relatively small
206 
changes in the data.
207 
      </p></li></ul></div><p>
208 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autorange-adjust-mode"></a>4.6.4.2. Range parameter: adjust_mode</h4></div></div></div><p>
209 
The <code class="varname">adjust_mode</code> parameter selects from one of three methods
210 
PHPlot has to determine how to extend the end of the plot range.
211 
The value is a single character, selecting one of three available modes.
212 
  </p><div class="informaltable"><table summary="Range adjust mode choices" border="1"><colgroup><col align="center" class="c1" /><col class="c2" /></colgroup><thead><tr><th align="center">Mode</th><th>Description</th></tr></thead><tbody><tr><td align="center">T</td><td>
213 
Tick : extend the range, then to the next tick mark.
214 
          </td></tr><tr><td align="center">R</td><td>
215 
Range : extend the range.
216 
          </td></tr><tr><td align="center">I</td><td>
217 
Integer : extend the range, then to the next integer value.
218 
          </td></tr></tbody></table></div><p>
219 
The default mode is <code class="literal">T</code>, extend to tick mark.
220 
Mode <code class="literal">I</code>, extend to integer, is similar to the only
221 
available adjustment mode available before PHPlot-6.0.0.
222 
</p><p>
223 
Range end adjustment works as follows. First, PlotMin is extended by the
224 
<code class="literal">adjust_amount</code> multiplied by the current plot range
225 
<span class="mathphrase">(PlotMax - PlotMin)</span>, but only if PlotMin is negative.
226 
Similarly, PlotMax is extended by the same factor, but only if it is positive.
227 
This corresponds to where extra spaces is needed for data value labels, for
228 
example: above positive values, and below negative values.
229 
</p><p>
230 
For adjustment mode <code class="literal">R</code>, that completes the range adjustment.
231 
For example, in this mode, with the adjustment amount 0.025 and data range
232 
-10 to 10, the resulting plot range will be -10.5 to 10.5 (having been
233 
increased at each end by 2.5% times the range of 20).
234 
</p><p>
235 
For adjustment mode <code class="literal">I</code>, after extending the range,
236 
PHPlot adjusts PlotMin to the next lowest integer, and PlotMax to the
237 
next highest integer.
238 
Using the same example, with the data range -10 to 10 and adjustment amount
239 
0.025, the range is now -11 to 11 using this mode.
240 
</p><p>
241 
Adjustment mode <code class="literal">T</code>, the default mode, extends the range
242 
end to coincide with a tick mark (or where a tick mark would be, if tick
243 
marks were displayed).
244 
In this mode, the <code class="literal">adjust_amount</code> can be thought
245 
of as controlling the minimum amount of space between the top of the data and
246 
the next tick mark.  If the adjust_amount is 0, and the maximum data value
247 
DataMax falls exactly on a tick mark, PHPlot will end the range at that
248 
tick mark. But if adjust_amount is greater than zero, PHPlot will extend
249 
the range by least one additional tick mark.
250 
</p><p>
251 
As an example of <code class="literal">T</code> adjustment mode, consider a Y tick
252 
increment of 10, and adjustment amount 0.03 (3%). With the Y data range of
253 
 
254 
next tick mark.  But with a Y data range of 0 to 98, the space between
255 
DataMax and the tick mark at 100 is not enough (less than 3% of the range),
256 
so the range is extended to the next tick mark after that, at 110.
257 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autorange-adjust-amount"></a>4.6.4.3. Range parameter: adjust_amount</h4></div></div></div><p>
258 
The <code class="varname">adjust_amount</code> parameter determines how much the end of
259 
the plot range is adjusted (extended) to leave room for labels within the plot
260 
area, or to keep the plotted data from pushing against the edge of the plot.
261 
This is a non-negative floating point value.
262 
</p><p>
263 
See the previous section on how the adjust_mode and adjust_amount
264 
parameters are used.
265 
</p><p>
266 
The default adjustment amount is either 0 (0%) or 0.03 (3%), depending on the
267 
plot type, and on whether the adjustment is for the independent or dependent
268 
variable. For most plot types, the default is 0 for the independent
269 
variable axis (X for vertical plots, Y for horizontal plots), and 3%
270 
for the dependent variable axis.
271 
Some plot types, such as <a class="link" href="conc-plottypes.html#plottype-bubbles" title="3.4.4. Plot Type: bubbles (Bubble Plot)">bubbles</a>,
272 
benefit from adjustment on both axes, so the default value for
273 
adjust_amount is 3% for both X and Y.
274 
Other plot types, such as
275 
<a class="link" href="conc-plottypes.html#plottype-candlesticks" title="3.4.5. Plot Type: candlesticks (OHLC Candlesticks Plot)">candlesticks</a>, do not need any
276 
adjustment on either axis (because there are no data value labels, and the
277 
upper wick may touch the edge of the plot without harm).
278 
For these plot types, the default adjust_amount is 0% for both X and Y.
279 
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-examples"></a>4.6.5. Examples of Automatic Range Calculation</h3></div></div></div><p>
280 
Here are 3 examples showing the automatic range calculation. Each figure
281 
contains 4 plots showing the cumulative effect of the numbered steps which
282 
are detailed above: (1) initial range, (2) zero magnet, (3) end adjust /
283 
increase range, and (4) end adjust / finalize ('Tick' adjust mode).
284 
</p><p>
285 
 
286 
In the first example, the data is all positive (DataMin &gt; 0).
287 
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/fig-autorange-a.png" alt="Automatic Range calculation steps, positive data." /></div></div><p>
288 
</p><p>
289 
Note: You can see in the figure about that the small adjustment to the top
290 
of the Y range made at step (3) is completely absorbed in the adjustment to
291 
reach the tick mark at step (4). This is not always the case. If the data
292 
happens to end exactly at a tick mark, and the <code class="literal">adjust_amount</code>
293 
parameter is greater than zero, PHPlot will extend the range to the next tick
294 
mark after that. In a more general sense, when using 'Tick' adjustment mode,
295 
the adjustment amount represents the minimum amount of space to allow between
296 
the data maximum and the plot maximum.
297 
</p><p>
298 
 
299 
In the second example, the data is both negative and positive.
300 
Note that in this case the zero magnet (step 2) has no effect, and the end
301 
adjustment (step 3) and adjust to tick (step 4) change
302 
<span class="emphasis"><em>both</em></span> ends of the range.
303 
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/fig-autorange-b.png" alt="Automatic Range calculation steps, data spans zero." /></div></div><p>
304 
</p><p>
305 
 
306 
The third example has all negative data (DataMax &lt; 0). Zero magnet
307 
applies to the top of the range, and end adjustment applies to the bottom
308 
of the range in this case.
309 
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/fig-autorange-c.png" alt="Automatic Range calculation steps, negative data." /></div></div><p>
310 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-implied"></a>4.6.6. Implied Independent Variable Case</h3></div></div></div><p>
311 
There are two <span class="emphasis"><em>implied independent variable</em></span> cases:
312 
  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
313 
When using the <a class="link" href="conc-datatypes.html#text-data">text-data</a> data type, you
314 
are drawing a vertical plot without specifying the values of the independent
315 
variable X. Your data array will contain only labels and Y values; the X
316 
values are implied.
317 
      </p></li><li class="listitem"><p>
318 
When using the <a class="link" href="conc-datatypes.html#text-data-yx">text-data-yx</a> data type, you
319 
are drawing a horizontal plot without specifying the values of the independent
320 
variable Y. Your data array will contain only labels and X values; the Y
321 
values are implied.
322 
      </p></li></ol></div><p>
323 
</p><p>
324 
If you don't use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set an explicit plot
325 
range for the independent variable axis in these cases, PHPlot sets the plot
326 
range for that axis to start at 0 and end at N, where N is the number of rows
327 
in the data array. The automatic range calculation is disabled for that
328 
axis, and there is no adjustment.
329 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-tick"></a>4.6.7. Automatic Tick Increment Calculation</h3></div></div></div><p>
330 
For both the X axis and Y axis, PHPlot calculates a tick increment if it was
331 
not set as described above.
332 
(Even if your plot has no visible tick marks along an axis, PHPlot will
333 
calculate a tick increment for that axis, since it might be used in adjusting
334 
the plot range.)
335 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
336 
This description applies starting with PHPlot-6.0.0. In older versions,
337 
PHPlot simply divided the plot range by 10 to calculate the tick increment.
338 
  </p></div><p>
339 
PHPlot uses one of three methods to calculate a tick increment for a given plot
340 
range (along the X or Y axis). The methods are called 'decimal', 'binary',
341 
and 'date', and correspond to the <code class="varname">tick_mode</code> parameter
342 
described below.  By default, PHPlot uses the 'decimal' method, unless the axis
343 
labels have been set up to use date/time labels, in which case it uses the
344 
'date' mode.
345 
You can also directly control which method is used.
346 
</p><p>
347 
Using the <span class="emphasis"><em>decimal</em></span> method, PHPlot picks the largest tick
348 
increment which is 1, 2, or 5 times a power of 10, and which divides the plot
349 
range into no fewer than the acceptable minimum number of tick intervals
350 
(see the <code class="varname">min_ticks</code> parameter below).
351 
The power of 10 can be negative, zero, or positive.
352 
Valid automatically-calculated tick increments for non-negative powers of 10
353 
include 1, 2, 5, 10, 20, 50, 100, 200, 500, etc.
354 
Valid automatically-calculated tick increments for negative powers of 10
355 
include 0.5, 0.2, 0.1, 0.05, 0.02, 0.01, etc.
356 
</p><p>
357 
For example, given the range 0 to 135, and the default min_ticks of 8,
358 
PHPlot will calculate a tick increment of 10, giving 14 intervals.  A tick
359 
increment of 20 is not valid because it would result in only 7 intervals,
360 
fewer than the minimum of 8.
361 
A tick increment of 5 would result in 28 intervals; while there is no
362 
explicit maximum, PHPlot chooses the largest valid increment that produces
363 
8 or more intervals.
364 
</p><p>
365 
When using the <span class="emphasis"><em>date</em></span> method, PHPlot selects from a
366 
pre-defined list of valid tick increments.
367 
The list covers a range from 1 second up to 7 days: 1, 2, 5, 10, 15, and 30
368 
seconds; 1, 2, 5, 10, 15, and 30 minutes, then 1, 2, 4, 8, 12, 24, 48, 96,
369 
and 168 hours.
370 
PHPlot will pick the largest increment in the list which will result in no
371 
fewer than the acceptable minimum number of tick intervals
372 
(<code class="varname">min_ticks</code>).
373 
If the plot area range exceeds 7 days, PHPlot switches to the 'decimal' method
374 
instead, with units of 24 hours.
375 
With the 'date' method, PHPlot never chooses an increment less than 1 second.
376 
</p><p>
377 
For example, given a date/time range which spans 1020 seconds (17 minutes),
378 
and the default min_ticks of 8, PHPlot will calculate a tick increment of 120
379 
seconds (2 minutes), which results in 9 intervals. This is the largest
380 
increment in the list above which results in 8 or more intervals.
381 
</p><p>
382 
When using the <span class="emphasis"><em>binary</em></span> method, PHPlot picks the largest
383 
tick increment which is a power of 2, and which divides the plot range into no
384 
fewer than the acceptable minimum number of tick intervals
385 
(see the <code class="varname">min_ticks</code> parameter below).
386 
The power of 2 can be negative, zero, or positive.
387 
Valid automatically-calculated tick increments for non-negative powers of 2
388 
include 1, 2, 4, 8, 16, 32, etc.
389 
Valid automatically-calculated tick increments for negative powers of 2
390 
include 1/2, 1/4, 1/8, 1/16, 1/32, etc. (Note that PHPlot will label these
391 
ticks as decimal values 0.5, 0.25, 0.125 etc., not fractions.)
392 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-tick-params"></a>4.6.8. Automatic Tick Increment Parameters</h3></div></div></div><p>
393 
The tick increment calculation uses parameters which can be set using
394 
<a class="xref" href="TuneXAutoTicks.html" title="TuneXAutoTicks"><span class="refentrytitle">TuneXAutoTicks</span></a> and <a class="xref" href="TuneYAutoTicks.html" title="TuneYAutoTicks"><span class="refentrytitle">TuneYAutoTicks</span></a>.
395 
The parameters are described in the next sections.
396 
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autotick-min-ticks"></a>4.6.8.1. Tick Increment parameter: min_ticks</h4></div></div></div><p>
397 
The <code class="varname">min_ticks</code> parameter sets the minimum number of tick
398 
intervals along the axis. The default is 8.
399 
The maximum number of tick intervals will be about 2.5 times the minimum.
400 
(The value 2.5 comes from the largest ratio between adjacent acceptable tick
401 
increment values. This is true for the 'decimal' method choices of 1, 2, 5,
402 
10, 20, etc., the 'binary' method, and also for the pre-defined list of values
403 
used with the 'date' method.)
404 
Therefore, by default, a plot range will have between 8 and 20 tick intervals
405 
inclusive (before possible additional tick intervals resulting from
406 
adjustment to the range, as described above).
407 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autotick-mode"></a>4.6.8.2. Tick Increment parameter: tick_mode</h4></div></div></div><p>
408 
The <code class="varname">tick_mode</code> parameter selects one of the three available
409 
methods to calculate the tick increment:
410 
  </p><div class="informaltable"><table summary="Axis tick modes" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Mode</th><th>Description</th></tr></thead><tbody><tr><td>decimal</td><td>Use a power of 10 times 1, 2, or 5</td></tr><tr><td>binary</td><td>Use a power of 2</td></tr><tr><td>date</td><td>Use a date/time increment value</td></tr></tbody></table></div><p>
411 
These methods are described in more detail above.
412 
</p><p>
413 
By default, PHPlot will automatically decide which method to use.
414 
It will use the <code class="literal">'date'</code> method if the corresponding axis
415 
tick labels use date/time formatting (as set with
416 
<a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a><code class="literal">('time')</code> or
417 
<a class="xref" href="SetYLabelType.html" title="SetYLabelType"><span class="refentrytitle">SetYLabelType</span></a><code class="literal">('time')</code>).
418 
Otherwise is will use the <code class="literal">'decimal'</code>  method.
419 
</p><p>
420 
Use this parameter to override the automatic tick increment method selection.
421 
For example, if you are using date/time values along the X axis,
422 
but have a custom label formatting function (rather than selecting
423 
<code class="literal">time</code> format type), you will probably want to tell PHPlot
424 
to pick a date/time tick increment for the X axis:
425 
</p><pre class="programlisting">// Pick a date/time tick increment on X:
426 
$plot-&gt;TuneXAutoTicks(NULL, 'date');
427 
</pre><p>
428 
</p><p>
429 
Another example is if you are using time value label types along X,
430 
but you want tick increments to follow the 1, 2, 5 times power of 10 rule,
431 
rather than choosing a date/time value. You can use:
432 
</p><pre class="programlisting">// Format X labels as time values:
433 
$plot-&gt;SetXLabelType('time', '%H:%M:%S');
434 
// Override default and use the decimal method to pick a tick increment:
435 
$plot-&gt;TuneXAutoTicks(NULL, 'decimal');
436 
</pre><p>
437 
</p><p>
438 
In this third example, your Y axis values represent something like memory
439 
sizes which are normally measured in powers of two. You can have PHPlot pick
440 
a power of two as a tick increment with:
441 
</p><pre class="programlisting">// Use a power of 2 for the Y axis tick increment:
442 
$plot-&gt;TuneYAutoTicks(NULL, 'binary');
443 
</pre><p>
444 
</p><p>
445 
If the plot range is small enough, PHPlot may select a tick increment which
446 
is less than one - a negative power of two.
447 
This results in a tick increment of 1/2, 1/4, 1/8, 1/16, or smaller.
448 
If you want to use the binary tick method, but do not want fractional tick
449 
increments, set <code class="varname">tick_inc_integer</code> (see next section):
450 
</p><pre class="programlisting">// Valid tick increments are powers of 2 &amp;gt;= 1
451 
$plot-&gt;TuneXAutoTicks(NULL, 'binary', TRUE);
452 
</pre><p>
453 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="autotick-tick-inc-integer"></a>4.6.8.3. Tick Increment parameter: tick_inc_integer</h4></div></div></div><p>
454 
The <code class="varname">tick_inc_integer</code> parameter is a boolean flag which
455 
can be set to prevent fractional tick increments.
456 
If the flag is TRUE, PHPlot will not pick a tick increment less than 1.
457 
This may result in fewer than <code class="varname">min_ticks</code> tick intervals.
458 
If the flag is FALSE, PHPlot may pick any tick increment.
459 
The default is FALSE.
460 
</p><p>
461 
The 'decimal' and 'binary' tick increment selection methods (see above)
462 
can select tick increments less than 1, using negative powers of 10 or 2
463 
respectively.
464 
This will happen if the plot range is small enough (and/or
465 
<code class="varname">min_ticks</code> is high enough).
466 
Specifically, a fractional tick increment will result from having a plot
467 
range which is less than the minimum number of ticks.
468 
Set <code class="varname">tick_inc_integer</code> to TRUE if you do not want
469 
fractional tick increments.
470 
This parameter does not apply to the 'date' tick increment selection method,
471 
which does not support tick increments less than 1 second.
472 
In 'date' mode, <code class="varname">tick_inc_integer</code> is assumed TRUE.
473 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
474 
PHPlot never picks a tick increment which is greater than one and not a whole
475 
number. Selected tick increments are either integers &gt;= 1, or fractions
476 
between 0 and 1.
477 
  </p></div><p>
478 
For example, if your Y data range is 0 to 1.8, and you set the
479 
<code class="varname">tick_inc_integer</code> parameter for Y to TRUE,
480 
then PHPlot will use a tick increment of 1, and you will get only
481 
2 tick intervals.  This is less than the default minimum of 8
482 
tick intervals.
483 
With <code class="varname">tick_inc_integer</code> FALSE, PHPlot would use a tick
484 
increment of 0.2 in 'decimal' mode, or 0.125 in 'binary' mode.
485 
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-tick-positions"></a>4.6.9. Tick Positions</h3></div></div></div><p>
486 
This section describes how PHPlot positions the tick marks along the X and Y
487 
axis (if tick marks are enabled), and the tick label values which result.
488 
Several factors are involved:
489 
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
490 
The plot range minimum (PlotMin), which is the world coordinates of the left
491 
end of the X axis, or the world coordinates of the bottom of the Y axis.
492 
      </p></li><li class="listitem"><p>
493 
Whether or not a tick anchor was set. You use a tick anchor to tell PHPlot
494 
that you want tick marks based on a particular world coordinate value.
495 
      </p></li><li class="listitem"><p>
496 
The plot range adjustment mode <code class="varname">adjust_mode</code> (see above),
497 
if PHPlot calculated the plot range minimum PlotMin automatically.
498 
      </p></li></ul></div><p>
499 
</p><p>
500 
PHPlot generally places tick marks along each axis starting from the minimum
501 
value of the plot range (PlotMin), which is the left-most position on the X
502 
axis, and the bottom-most position on the Y axis.
503 
Therefore, the value of PlotMin affects all the tick values. For example,
504 
if the tick increment is 10, and PlotMin is 12, ticks will be at 12, 22,
505 
32, 42.
506 
</p><p>
507 
A tick anchor can be set with <a class="xref" href="SetXTickAnchor.html" title="SetXTickAnchor"><span class="refentrytitle">SetXTickAnchor</span></a> or
508 
<a class="xref" href="SetYTickAnchor.html" title="SetYTickAnchor"><span class="refentrytitle">SetYTickAnchor</span></a> to change tick mark positions. In the
509 
above example, with PlotMin 12, if you set a tick anchor at 10, you will
510 
get tick positions 20, 30, 40, etc. Setting the tick anchor shifts all the
511 
ticks, so one of them falls at the anchor (or would, if the axis was
512 
extended).  Thus, a tick anchor can be used to 'round off' the tick values
513 
to desired numbers, when the plot range minimum (PlotMin) is not a multiple
514 
of the tick increment.
515 
</p><p>
516 
If you set the plot range minimum (PlotMin) to a fixed value with
517 
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>, consider that this value will be
518 
used as the basis for tick marks along that axis, unless you also set
519 
a tick anchor.
520 
</p><p>
521 
If PHPlot calculates the plot range minimum using the default adjustment
522 
mode <code class="literal">T</code> (adjust to tick, see above), then PHPlot will
523 
adjust the range to start at a tick mark. That is, PHPlot acts as if a
524 
tick anchor was set at 0. Your tick marks will be at whole multiples
525 
of the tick increment, unless you set a tick anchor to move them somewhere
526 
else.
527 
</p><p>
528 
In the other adjustments modes - <code class="literal">I</code> (integer) or
529 
<code class="literal">R</code> (range) - PHPlot makes no attempt to correlate the
530 
plot range minimum with the tick increment. Your tick marks will probably
531 
not be located at multiples of the tick increment.
532 
In mode <code class="literal">R</code> (range), your tick marks will likely not even be
533 
whole numbers.  As in all other cases, you can set a tick anchor to position
534 
the tick marks at the values you prefer.
535 
</p><p>
536 
Here are some examples of PHPlot-calculated plot ranges and tick positions,
537 
when no tick anchor has been set.
538 
  </p><div class="informaltable"><table summary="Range and tick position results" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /><col align="center" class="c4" /><col align="center" class="c5" /><col class="c6" /></colgroup><thead><tr><th align="center">Y data min</th><th align="center">Y data max</th><th align="center">Adjustment Mode</th><th align="center">Resulting Plot Range</th><th align="center">Resulting Tick Positions</th><th>Notes</th></tr></thead><tbody><tr><td align="center">7</td><td align="center">123</td><td align="center"><code class="literal">T</code> (tick)</td><td align="center">0 to 130</td><td align="center">0, 10, 20, ... 130</td><td>
539 
The bottom of the Y range is extended to zero, and the tick marks are at
540 
multiples of 10. The top of the Y range is extended to the next tick mark.
541 
          </td></tr><tr><td align="center">7</td><td align="center">123</td><td align="center"><code class="literal">R</code> (range)</td><td align="center">0 to 126.69</td><td align="center">0, 10, 20, ... 120</td><td>
542 
With <code class="literal">'R'</code> adjustment mode, the top of the Y range is
543 
extended by 3% of the range. The bottom of the Y range was moved to zero
544 
(due to the <span class="emphasis"><em>zero magnet</em></span>), so the tick marks are based
545 
at 0 and positioned at whole multiples of 10. The resulting tick marks
546 
are the same as <code class="literal">'T'</code> mode, except the Y axis does not end
547 
at a tick mark.
548 
          </td></tr><tr><td align="center">7</td><td align="center">123</td><td align="center"><code class="literal">I</code> (integer)</td><td align="center">0 to 127</td><td align="center">0, 10, 20, ... 120</td><td>
549 
Here <code class="literal">'I'</code> adjustment mode is almost the the same as the
550 
previous case, except the top of the range is adjusted to the next integer.
551 
Since there is no tick mark there, the difference would not be visible.
552 
          </td></tr><tr><td align="center">-17</td><td align="center">33</td><td align="center"><code class="literal">T</code> (tick)</td><td align="center">-20 to 35</td><td align="center">-20, -15, -10, -5, 0, 5, 10, ... 35</td><td>
553 
Both ends of plot range are adjusted to a tick position,
554 
with an implied tick anchor at 0. The resulting tick marks are at
555 
whole multiples of the tick step 5.
556 
          </td></tr><tr><td align="center">-17</td><td align="center">33</td><td align="center"><code class="literal">R</code> (range)</td><td align="center">-18.5 to 34.5</td><td align="center">-18.5, -13.5, -8.5, 1.5, 6.5, ... 31.5</td><td>
557 
In this mode, the range is simply extended by 3% (by default) at each end,
558 
where 3% of (33+17) = 1.5. The resulting tick mark positions are probably
559 
not ideal.
560 
          </td></tr><tr><td align="center">-17</td><td align="center">33</td><td align="center"><code class="literal">I</code> (integer)</td><td align="center">-19 to 35</td><td align="center">-19, -14, -9, -4, 1, 6, ... 31</td><td>
561 
In this mode, the range is extended by 3%, and then the ends are extended
562 
to the next integer. The tick mark positions are whole numbers now, but
563 
not anchored at 0.
564 
          </td></tr></tbody></table></div><p>
565 
</p><p>
566 
To summarize, setting a tick anchor to force the tick positions to align one
567 
tick at a particular value, usually 0, can be useful in the situations
568 
including:
569 
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
570 
You are letting PHPlot calculate the range, but with adjustment mode
571 
<code class="literal">R</code> (range) or <code class="literal">I</code> (integer).
572 
      </p></li><li class="listitem"><p>
573 
You are manually setting the minimum of the plot range with
574 
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to a value other than zero or
575 
a whole multiple of the tick increment.
576 
      </p></li><li class="listitem"><p>
577 
You are using date/time values along the axis, and you need the ticks to
578 
start at a specific date/time value (such as the start of an experiment).
579 
      </p></li><li class="listitem"><p>
580 
You are using a version before PHPlot-6.0.0, which only supports an
581 
adjustment mode similar to <code class="literal">I</code> (integer).
582 
      </p></li></ul></div><p>
583 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="adv-autorange-regress"></a>4.6.10. Plot Range Regressive Cases</h3></div></div></div><p>
584 
Given incomplete or contradictory data, PHPlot will always produce a positive
585 
plot range (PlotMin &lt; PlotMax), although the range may be somewhat arbitrary.
586 
Here are some of the regressive cases, and how PHPlot produces an automatic
587 
range for them. <code class="literal">DataMin</code> and <code class="literal">DataMax</code>
588 
mean the limits of the data from the data array; <code class="literal">PlotMin</code>
589 
and <code class="literal">PlotMax</code> are the limits of the plot range.
590 
In all cases, any values specified in <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> will
591 
not be altered by PHPlot, even if it results in a plot with no visible data
592 
points.
593 
 
594 
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Empty range with non-zero values (DataMin == DataMax != 0):</span></dt><dd><p>
595 
For positive data, PHPlot uses the range 0 to K, where K is the larger of
596 
DataMin and 10. For example, if all the Y values are 5, PHPlot uses 0 to 10
597 
for the Y range; if all the Y values are 150, PHPlot uses 0 to 150.
598 
For negative data, PHPlot uses a similar method, setting PlotMax=0.
599 
        </p></dd><dt><span class="term">Empty range with all zero values (DataMin == DataMax == 0):</span></dt><dd><p>
600 
PHPlot uses the arbitrary range 0 to 10.
601 
        </p></dd><dt><span class="term">Partially specified range with maximum set and all data above that:</span></dt><dd><p>
602 
If you set PlotMax to a value, but all your data is above that (DataMin &gt;
603 
PlotMax), you will get an empty plot. PHPlot will use a range of 0 to
604 
PlotMax if your PlotMax is positive, else a range of PlotMax-10 to PlotMax.
605 
All your data points will be outside the plot area.
606 
        </p></dd><dt><span class="term">Partially specified range with minimum set and all data below that:</span></dt><dd><p>
607 
If you set PlotMin to a value, but all your data is below that (DataMax &lt;
608 
PlotMin), you will get an empty plot. PHPlot will use a range of PlotMin
609 
to 0 if your PlotMin is negative, else a range of PlotMin to PlotMin+10.
610 
All your data points will be outside the plot area.
611 
        </p></dd><dt><span class="term">Negative range or zero range:</span></dt><dd><p>
612 
If you try to use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set a negative
613 
range (PlotMin &gt; PlotMax) or zero range (PlotMin == PlotMax), PHPlot
614 
will report an error and not produce a plot.
615 
        </p></dd></dl></div><p>
616 
</p><p>
617 
Note that the above range choices happen as part of the "initialization"
618 
step of automatic range calculation (see <a class="xref" href="adv-autorange.html#adv-autorange-range" title="4.6.3. Automatic Range Calculation">Section 4.6.3, &#8220;Automatic Range Calculation&#8221;</a>
619 
above). That is, the selected range is then subject to the same adjustments as
620 
in other cases.
621 
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adv-datacolor-callback.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-tuning.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.5. Custom Data Color Selection </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.7. Tuning Parameters</td></tr></table></div></body></html>