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.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>
This section describes how PHPlot calculates the range of
<a class="link" href="concepts.html#def-worldcoor">World Coordinate</a> space, and the tick
increment for each axis, when those values have not been set manually.
  </p></div><p>
In order to plot a data set, PHPlot needs to map the data points from world
coordinate space to device coordinate space. The world coordinates of the
data points are generally in real-world units, such as kilometers, seconds,
degrees centigrade, etc. Device coordinates are pixels in an image file,
display screen, or paper hardcopy. PHPlot knows the pixel coordinates of
the limits of the plot area in device space.  In order to translate data
points from world coordinates into pixel coordinates, it needs to know the
limits of world coordinate space.  These can be provided manually, or
computed by PHPlot.
</p><p>
The limits of world coordinate space are the end-points of the X and Y axis
lines.  The two end-points of an axis are also referred to as the plot
range along that axis.  Each of those plot ranges is divided into uniformly
sized tick intervals, which may or may not be marked by visible tick marks.
The space between tick marks is called the tick increment. PHPlot will
calculate a suitable tick increment if necessary.
</p><p>
The rest of this section describes how PHPlot calculates the limits of the
plot ranges, and the tick increments.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This section does not apply to pie charts, which do not have X or Y axis lines.
  </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>
If you use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set both
<code class="varname">Xmin</code> and <code class="varname">Xmax</code> to non-NULL values,
this will fix both ends of the X axis.  Similarly, setting both
<code class="varname">Ymin</code> and <code class="varname">Ymax</code> to non-NULL values
will fix both ends of the Y axis.
If you set both ends of an axis, PHPlot will use exactly that for the plot
range on that axis.  This is recommended if your data has a range which is
known, predictable, and/or 'natural'. For example, if your Y axis represents
percentage values from 0 to 100, you might use this to fix the Y axis ends:

</p><pre class="programlisting">$plot-&gt;SetPlotAreaWorld(NULL, 0, NULL, 100);
</pre><p>
</p><p>
You can use <a class="xref" href="SetXTickIncrement.html" title="SetXTickIncrement"><span class="refentrytitle">SetXTickIncrement</span></a> to set a fixed X tick
increment, and <a class="xref" href="SetYTickIncrement.html" title="SetYTickIncrement"><span class="refentrytitle">SetYTickIncrement</span></a> to set a fixed Y tick
increment.
If you set a fixed tick increment along an axis, PHPlot will use exactly
that value (even if it results in too many, or too few tick marks).
</p><p>
Another way to manually specify tick increments is with
<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>.
These set the desired number of tick intervals.
PHPlot will then calculate the tick increment by dividing the plot range into
exactly that many intervals.
For example, if the Y axis range is 0 to 17, and you use
<code class="literal">$plot-&gt;SetNumYTicks(6)</code> to get 6 intervals, then the tick
mark spacing will be about 2.833333.
This is probably not a desirable value for the tick increment.
Using <code class="function">SetNumXTicks</code> or <code class="function">SetNumYTicks</code>
to set the number of tick intervals is usually not a good idea, unless you
also set the plot range with <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>.
</p><p>
If you set both ends of the X or Y plot range, PHPlot will position
tick marks starting from the lower end of that range, by default.
For example, if you set the Y axis range from 1 to 20, with a tick
increment of 5, the tick marks will be at 1, 6, 11, and 16.
You can set a <span class="emphasis"><em>tick anchor</em></span> to change this.
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.
</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>
If you use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set either
<code class="varname">Xmin</code> or <code class="varname">Xmax</code> (but not both) to a
non-NULL value, or you set either
<code class="varname">Ymin</code> or <code class="varname">Ymax</code> (but not both) to a
non-NULL value, then you are fixing one end of the plot range.
PHPlot will use your fixed value for that end of the range, and calculate the
other end as described below.
</p><p>
This may make sense if your data has a fixed lower (or upper) bound. For
example, if you are plotting outdoor summer temperatures in degrees
Fahrenheit, you might use something like this:
</p><pre class="programlisting">$plot-&gt;SetPlotAreaWorld(NULL, 60);
</pre><p>
which sets Ymin to 60.
</p><p>
Since PHPlot positions tick marks starting from the lower limit of the X
and Y plot ranges, setting <code class="varname">Xmin</code> or <code class="varname">Ymin</code>
establishes the basis for tick marks along that axis.
For example, if you set the lower end of the X axis range to 12, with a tick
increment of 10, the tick marks along X will be at 12, 22, 32, etc.
You can set a <span class="emphasis"><em>tick anchor</em></span> to change this.
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.
</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>
Each end of the plot range (for both X and Y) which is not specified using
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> will be calculated by PHPlot.
The algorithm used by PHPlot to calculate the ends of a plot range is not
perfect, but is meant to create reasonable plots in a majority of cases.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This description applies starting with PHPlot-6.0.0. In older versions,
PHPlot used a more simplistic approach to calculating the plot range.
  </p></div><p>
Here is an overview of the method, using the Y axis as an example.
<code class="literal">DataMin</code> and <code class="literal">DataMax</code>
are the smallest and largest Y values in the data array (or the values
derived from the data array, for some plot types).
<code class="literal">PlotMin</code> and <code class="literal">PlotMax</code> are the
calculated limits of the plot range. Remember that PHPlot only calculates
PlotMax and PlotMin if they have not already been set using
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>.

  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Initialization:
Start by setting the plot range to the data range: PlotMin = DataMin, and
PlotMax = DataMax. The plot range will now include all the data, but just
barely.
      </p></li><li class="listitem"><p>
Zero Magnet:
If the plot range does not currently include zero
(PlotMin &lt;= 0 and 0 &lt;= PlotMax), PHPlot tries to extend the range so it
will begin or end at zero. This is done by either by moving PlotMin down to
zero (for positive data), or by moving PlotMax up to zero (for negative data).
There is a limit as to how far PHPlot is willing to extend the plot range
to include zero (see below).
      </p></li><li class="listitem"><p>
End Adjust / Increase range:
PHPlot may then adjust the ends of the plot range by a factor
(adjust_amount) multiplied by the plot range.  This provides some extra
room above or below the data for data value labels, and prevents the top
(or bottom) of the plotted data from hitting the edge of the plot area,
which would detract from the appearance. Adjustment only occurs for PlotMin
if it is negative, and for PlotMax if it is positive. This corresponds to
the direction of the plot data 'away' from zero.

For example, if 0 &lt; PlotMin &lt; PlotMax
(all the data is positive), then PlotMax will be increased.

If PlotMin &lt; PlotMax &lt; 0 (all the data is negative),
then PlotMin will be decreased.

If the range spans 0 with PlotMin &lt; 0 &lt; PlotMax,
then both PlotMin will be decreased and PlotMax will be increased.
      </p></li><li class="listitem"><p>
End Adjust / Finalize:
PHPlot may then adjust the ends of the plot range further, based on the
adjustment mode (<code class="literal">adjust_mode</code>), but only if the end of
the range is not already zero.
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the adjustment mode is <code class="literal">T</code> (Tick, the default mode),
then PlotMax is adjusted up to the next higher tick mark position, and
PlotMin is adjusted down to the next lower tick mark position. Note that
this happens even if tick marks are not displayed.
If a tick anchor is set, this is taken into account when adjusting the
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).
            </p></li><li class="listitem"><p>
If the adjustment mode is <code class="literal">R</code> (Range), there is no further
adjustment.
            </p></li><li class="listitem"><p>
If the adjustment mode is <code class="literal">I</code> (Integer), then PlotMax is
adjusted up to the next higher integer, and PlotMin is adjusted down to the
next lower integer.
            </p></li></ul></div><p>
Note that adjustment modes <code class="literal">R</code> and <code class="literal">I</code> are
intended for special applications where the default <code class="literal">T</code>
(Tick) mode produces undesirable results.
      </p></li></ol></div><p>
</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>
The range calculation uses parameters which can be set using
<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>.
The parameters are described in the next sections.
</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>
The <code class="varname">zero_magnet</code> parameter sets the strength of the
<span class="emphasis"><em>zero magnet</em></span>, which controls how far PHPlot is
willing to extend the plot range to include zero, if the range does not
already include zero.
This is a floating point number greater than or equal to 0, and less than
or equal to 1.0.
A value of 0 means the magnet is disabled. PHPlot will not extend the
plot range to include zero.
A value of 1.0 means the magnet strength is infinite, and PHPlot will
always extend the plot range to include zero.
For increasing values between 0.0 and 1.0, the zero magnet becomes
stronger, and PHPlot will go further in extending the plot range to include
zero.
</p><p>
Between 0 and 1.0, the zero magnet factor is applied as follows. Let
<span class="mathphrase">ZF = zero_magnet / (1 - zero_magnet)</span>.
This maps the zero magnet domain of 0:1 into the range 0:infinity.
PHPlot will extend the plot range to include 0 if that increases
the range by a factor of ZF or less.
</p><p>
For example, the default zero magnet factor of 6/7 results in ZF=6, so
PHPlot will 'pull' the bottom of the plot range down to zero if doing so
will stretch the range by 600% or less. (If the data is all negative, it
will apply the zero magnet to 'pushing' the top of the range to zero in the
same manner.)
If the data range is 500 to 600, PHPlot will adjust it to become 0 to 600,
because adjusting the lower range by 500 is less than the maximum 6*100.
If the data range is 900 to 1000, PHPlot will not adjust it to start at 0,
because the zero magnet is only 'strong enough' to pull the range down by
6*100, not 900.
</p><p>
The purpose of having a variable <span class="emphasis"><em>zero magnet</em></span> is
to balance two conflicting goals:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Including zero in the data range improves the utility of plots, 
as it facilitates comparing relative changes and differences.
      </p></li><li class="listitem"><p>
Increasing the data range of a plot makes it harder to see relatively small
changes in the data.
      </p></li></ul></div><p>
</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>
The <code class="varname">adjust_mode</code> parameter selects from one of three methods
PHPlot has to determine how to extend the end of the plot range.
The value is a single character, selecting one of three available modes.
  </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>
Tick : extend the range, then to the next tick mark.
          </td></tr><tr><td align="center">R</td><td>
Range : extend the range.
          </td></tr><tr><td align="center">I</td><td>
Integer : extend the range, then to the next integer value.
          </td></tr></tbody></table></div><p>
The default mode is <code class="literal">T</code>, extend to tick mark.
Mode <code class="literal">I</code>, extend to integer, is similar to the only
available adjustment mode available before PHPlot-6.0.0.
</p><p>
Range end adjustment works as follows. First, PlotMin is extended by the
<code class="literal">adjust_amount</code> multiplied by the current plot range
<span class="mathphrase">(PlotMax - PlotMin)</span>, but only if PlotMin is negative.
Similarly, PlotMax is extended by the same factor, but only if it is positive.
This corresponds to where extra spaces is needed for data value labels, for
example: above positive values, and below negative values.
</p><p>
For adjustment mode <code class="literal">R</code>, that completes the range adjustment.
For example, in this mode, with the adjustment amount 0.025 and data range
-10 to 10, the resulting plot range will be -10.5 to 10.5 (having been
increased at each end by 2.5% times the range of 20).
</p><p>
For adjustment mode <code class="literal">I</code>, after extending the range,
PHPlot adjusts PlotMin to the next lowest integer, and PlotMax to the
next highest integer.
Using the same example, with the data range -10 to 10 and adjustment amount
0.025, the range is now -11 to 11 using this mode.
</p><p>
Adjustment mode <code class="literal">T</code>, the default mode, extends the range
end to coincide with a tick mark (or where a tick mark would be, if tick
marks were displayed).
In this mode, the <code class="literal">adjust_amount</code> can be thought
of as controlling the minimum amount of space between the top of the data and
the next tick mark.  If the adjust_amount is 0, and the maximum data value
DataMax falls exactly on a tick mark, PHPlot will end the range at that
tick mark. But if adjust_amount is greater than zero, PHPlot will extend
the range by least one additional tick mark.
</p><p>
As an example of <code class="literal">T</code> adjustment mode, consider a Y tick
increment of 10, and adjustment amount 0.03 (3%). With the Y data range of
0 to 95, PHPlot will set PlotMax to 100 - extending the range to the very
next tick mark.  But with a Y data range of 0 to 98, the space between
DataMax and the tick mark at 100 is not enough (less than 3% of the range),
so the range is extended to the next tick mark after that, at 110.
</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>
The <code class="varname">adjust_amount</code> parameter determines how much the end of
the plot range is adjusted (extended) to leave room for labels within the plot
area, or to keep the plotted data from pushing against the edge of the plot.
This is a non-negative floating point value.
</p><p>
See the previous section on how the adjust_mode and adjust_amount
parameters are used.
</p><p>
The default adjustment amount is either 0 (0%) or 0.03 (3%), depending on the
plot type, and on whether the adjustment is for the independent or dependent
variable. For most plot types, the default is 0 for the independent
variable axis (X for vertical plots, Y for horizontal plots), and 3%
for the dependent variable axis.
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>,
benefit from adjustment on both axes, so the default value for
adjust_amount is 3% for both X and Y.
Other plot types, such as
<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
adjustment on either axis (because there are no data value labels, and the
upper wick may touch the edge of the plot without harm).
For these plot types, the default adjust_amount is 0% for both X and Y.
</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>
Here are 3 examples showing the automatic range calculation. Each figure
contains 4 plots showing the cumulative effect of the numbered steps which
are detailed above: (1) initial range, (2) zero magnet, (3) end adjust /
increase range, and (4) end adjust / finalize ('Tick' adjust mode).
</p><p>

In the first example, the data is all positive (DataMin &gt; 0).
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/fig-autorange-a.png" alt="Automatic Range calculation steps, positive data." /></div></div><p>
</p><p>
Note: You can see in the figure about that the small adjustment to the top
of the Y range made at step (3) is completely absorbed in the adjustment to
reach the tick mark at step (4). This is not always the case. If the data
happens to end exactly at a tick mark, and the <code class="literal">adjust_amount</code>
parameter is greater than zero, PHPlot will extend the range to the next tick
mark after that. In a more general sense, when using 'Tick' adjustment mode,
the adjustment amount represents the minimum amount of space to allow between
the data maximum and the plot maximum.
</p><p>

In the second example, the data is both negative and positive.
Note that in this case the zero magnet (step 2) has no effect, and the end
adjustment (step 3) and adjust to tick (step 4) change
<span class="emphasis"><em>both</em></span> ends of the range.
  </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>
</p><p>

The third example has all negative data (DataMax &lt; 0). Zero magnet
applies to the top of the range, and end adjustment applies to the bottom
of the range in this case.
  </p><div class="informalfigure"><div class="mediaobject"><img src="images/fig-autorange-c.png" alt="Automatic Range calculation steps, negative data." /></div></div><p>
</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>
There are two <span class="emphasis"><em>implied independent variable</em></span> cases:
  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
When using the <a class="link" href="conc-datatypes.html#text-data">text-data</a> data type, you
are drawing a vertical plot without specifying the values of the independent
variable X. Your data array will contain only labels and Y values; the X
values are implied.
      </p></li><li class="listitem"><p>
When using the <a class="link" href="conc-datatypes.html#text-data-yx">text-data-yx</a> data type, you
are drawing a horizontal plot without specifying the values of the independent
variable Y. Your data array will contain only labels and X values; the Y
values are implied.
      </p></li></ol></div><p>
</p><p>
If you don't use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set an explicit plot
range for the independent variable axis in these cases, PHPlot sets the plot
range for that axis to start at 0 and end at N, where N is the number of rows
in the data array. The automatic range calculation is disabled for that
axis, and there is no adjustment.
</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>
For both the X axis and Y axis, PHPlot calculates a tick increment if it was
not set as described above.
(Even if your plot has no visible tick marks along an axis, PHPlot will
calculate a tick increment for that axis, since it might be used in adjusting
the plot range.)
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This description applies starting with PHPlot-6.0.0. In older versions,
PHPlot simply divided the plot range by 10 to calculate the tick increment.
  </p></div><p>
PHPlot uses one of three methods to calculate a tick increment for a given plot
range (along the X or Y axis). The methods are called 'decimal', 'binary',
and 'date', and correspond to the <code class="varname">tick_mode</code> parameter
described below.  By default, PHPlot uses the 'decimal' method, unless the axis
labels have been set up to use date/time labels, in which case it uses the
'date' mode.
You can also directly control which method is used.
</p><p>
Using the <span class="emphasis"><em>decimal</em></span> method, PHPlot picks the largest tick
increment which is 1, 2, or 5 times a power of 10, and which divides the plot
range into no fewer than the acceptable minimum number of tick intervals
(see the <code class="varname">min_ticks</code> parameter below).
The power of 10 can be negative, zero, or positive.
Valid automatically-calculated tick increments for non-negative powers of 10
include 1, 2, 5, 10, 20, 50, 100, 200, 500, etc.
Valid automatically-calculated tick increments for negative powers of 10
include 0.5, 0.2, 0.1, 0.05, 0.02, 0.01, etc.
</p><p>
For example, given the range 0 to 135, and the default min_ticks of 8,
PHPlot will calculate a tick increment of 10, giving 14 intervals.  A tick
increment of 20 is not valid because it would result in only 7 intervals,
fewer than the minimum of 8.
A tick increment of 5 would result in 28 intervals; while there is no
explicit maximum, PHPlot chooses the largest valid increment that produces
8 or more intervals.
</p><p>
When using the <span class="emphasis"><em>date</em></span> method, PHPlot selects from a
pre-defined list of valid tick increments.
The list covers a range from 1 second up to 7 days: 1, 2, 5, 10, 15, and 30
seconds; 1, 2, 5, 10, 15, and 30 minutes, then 1, 2, 4, 8, 12, 24, 48, 96,
and 168 hours.
PHPlot will pick the largest increment in the list which will result in no
fewer than the acceptable minimum number of tick intervals
(<code class="varname">min_ticks</code>).
If the plot area range exceeds 7 days, PHPlot switches to the 'decimal' method
instead, with units of 24 hours.
With the 'date' method, PHPlot never chooses an increment less than 1 second.
</p><p>
For example, given a date/time range which spans 1020 seconds (17 minutes),
and the default min_ticks of 8, PHPlot will calculate a tick increment of 120
seconds (2 minutes), which results in 9 intervals. This is the largest
increment in the list above which results in 8 or more intervals.
</p><p>
When using the <span class="emphasis"><em>binary</em></span> method, PHPlot picks the largest
tick increment which is a power of 2, and which divides the plot range into no
fewer than the acceptable minimum number of tick intervals
(see the <code class="varname">min_ticks</code> parameter below).
The power of 2 can be negative, zero, or positive.
Valid automatically-calculated tick increments for non-negative powers of 2
include 1, 2, 4, 8, 16, 32, etc.
Valid automatically-calculated tick increments for negative powers of 2
include 1/2, 1/4, 1/8, 1/16, 1/32, etc. (Note that PHPlot will label these
ticks as decimal values 0.5, 0.25, 0.125 etc., not fractions.)
</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>
The tick increment calculation uses parameters which can be set using
<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>.
The parameters are described in the next sections.
</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>
The <code class="varname">min_ticks</code> parameter sets the minimum number of tick
intervals along the axis. The default is 8.
The maximum number of tick intervals will be about 2.5 times the minimum.
(The value 2.5 comes from the largest ratio between adjacent acceptable tick
increment values. This is true for the 'decimal' method choices of 1, 2, 5,
10, 20, etc., the 'binary' method, and also for the pre-defined list of values
used with the 'date' method.)
Therefore, by default, a plot range will have between 8 and 20 tick intervals
inclusive (before possible additional tick intervals resulting from
adjustment to the range, as described above).
</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>
The <code class="varname">tick_mode</code> parameter selects one of the three available
methods to calculate the tick increment:
  </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>
These methods are described in more detail above.
</p><p>
By default, PHPlot will automatically decide which method to use.
It will use the <code class="literal">'date'</code> method if the corresponding axis
tick labels use date/time formatting (as set with 
<a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a><code class="literal">('time')</code> or
<a class="xref" href="SetYLabelType.html" title="SetYLabelType"><span class="refentrytitle">SetYLabelType</span></a><code class="literal">('time')</code>).
Otherwise is will use the <code class="literal">'decimal'</code>  method.
</p><p>
Use this parameter to override the automatic tick increment method selection.
For example, if you are using date/time values along the X axis,
but have a custom label formatting function (rather than selecting
<code class="literal">time</code> format type), you will probably want to tell PHPlot
to pick a date/time tick increment for the X axis:
</p><pre class="programlisting">// Pick a date/time tick increment on X:
$plot-&gt;TuneXAutoTicks(NULL, 'date');
</pre><p>
</p><p>
Another example is if you are using time value label types along X,
but you want tick increments to follow the 1, 2, 5 times power of 10 rule,
rather than choosing a date/time value. You can use:
</p><pre class="programlisting">// Format X labels as time values:
$plot-&gt;SetXLabelType('time', '%H:%M:%S');
// Override default and use the decimal method to pick a tick increment:
$plot-&gt;TuneXAutoTicks(NULL, 'decimal');
</pre><p>
</p><p>
In this third example, your Y axis values represent something like memory
sizes which are normally measured in powers of two. You can have PHPlot pick
a power of two as a tick increment with:
</p><pre class="programlisting">// Use a power of 2 for the Y axis tick increment:
$plot-&gt;TuneYAutoTicks(NULL, 'binary');
</pre><p>
</p><p>
If the plot range is small enough, PHPlot may select a tick increment which
is less than one - a negative power of two.
This results in a tick increment of 1/2, 1/4, 1/8, 1/16, or smaller.
If you want to use the binary tick method, but do not want fractional tick
increments, set <code class="varname">tick_inc_integer</code> (see next section):
</p><pre class="programlisting">// Valid tick increments are powers of 2 &amp;gt;= 1
$plot-&gt;TuneXAutoTicks(NULL, 'binary', TRUE);
</pre><p>
</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>
The <code class="varname">tick_inc_integer</code> parameter is a boolean flag which
can be set to prevent fractional tick increments.
If the flag is TRUE, PHPlot will not pick a tick increment less than 1.
This may result in fewer than <code class="varname">min_ticks</code> tick intervals.
If the flag is FALSE, PHPlot may pick any tick increment.
The default is FALSE.
</p><p>
The 'decimal' and 'binary' tick increment selection methods (see above)
can select tick increments less than 1, using negative powers of 10 or 2
respectively.
This will happen if the plot range is small enough (and/or
<code class="varname">min_ticks</code> is high enough).
Specifically, a fractional tick increment will result from having a plot
range which is less than the minimum number of ticks.
Set <code class="varname">tick_inc_integer</code> to TRUE if you do not want
fractional tick increments.
This parameter does not apply to the 'date' tick increment selection method,
which does not support tick increments less than 1 second.
In 'date' mode, <code class="varname">tick_inc_integer</code> is assumed TRUE.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
PHPlot never picks a tick increment which is greater than one and not a whole
number. Selected tick increments are either integers &gt;= 1, or fractions
between 0 and 1.
  </p></div><p>
For example, if your Y data range is 0 to 1.8, and you set the
<code class="varname">tick_inc_integer</code> parameter for Y to TRUE,
then PHPlot will use a tick increment of 1, and you will get only
2 tick intervals.  This is less than the default minimum of 8
tick intervals.
With <code class="varname">tick_inc_integer</code> FALSE, PHPlot would use a tick
increment of 0.2 in 'decimal' mode, or 0.125 in 'binary' mode.
</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>
This section describes how PHPlot positions the tick marks along the X and Y
axis (if tick marks are enabled), and the tick label values which result.
Several factors are involved:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The plot range minimum (PlotMin), which is the world coordinates of the left
end of the X axis, or the world coordinates of the bottom of the Y axis.
      </p></li><li class="listitem"><p>
Whether or not a tick anchor was set. You use a tick anchor to tell PHPlot
that you want tick marks based on a particular world coordinate value.
      </p></li><li class="listitem"><p>
The plot range adjustment mode <code class="varname">adjust_mode</code> (see above),
if PHPlot calculated the plot range minimum PlotMin automatically.
      </p></li></ul></div><p>
</p><p>
PHPlot generally places tick marks along each axis starting from the minimum
value of the plot range (PlotMin), which is the left-most position on the X
axis, and the bottom-most position on the Y axis.
Therefore, the value of PlotMin affects all the tick values. For example,
if the tick increment is 10, and PlotMin is 12, ticks will be at 12, 22,
32, 42.
</p><p>
A tick anchor can be set with <a class="xref" href="SetXTickAnchor.html" title="SetXTickAnchor"><span class="refentrytitle">SetXTickAnchor</span></a> or
<a class="xref" href="SetYTickAnchor.html" title="SetYTickAnchor"><span class="refentrytitle">SetYTickAnchor</span></a> to change tick mark positions. In the
above example, with PlotMin 12, if you set a tick anchor at 10, you will
get tick positions 20, 30, 40, etc. Setting the tick anchor shifts all the
ticks, so one of them falls at the anchor (or would, if the axis was
extended).  Thus, a tick anchor can be used to 'round off' the tick values
to desired numbers, when the plot range minimum (PlotMin) is not a multiple
of the tick increment.
</p><p>
If you set the plot range minimum (PlotMin) to a fixed value with
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a>, consider that this value will be
used as the basis for tick marks along that axis, unless you also set
a tick anchor.
</p><p>
If PHPlot calculates the plot range minimum using the default adjustment
mode <code class="literal">T</code> (adjust to tick, see above), then PHPlot will
adjust the range to start at a tick mark. That is, PHPlot acts as if a
tick anchor was set at 0. Your tick marks will be at whole multiples
of the tick increment, unless you set a tick anchor to move them somewhere
else.
</p><p>
In the other adjustments modes - <code class="literal">I</code> (integer) or
<code class="literal">R</code> (range) - PHPlot makes no attempt to correlate the
plot range minimum with the tick increment. Your tick marks will probably
not be located at multiples of the tick increment.
In mode <code class="literal">R</code> (range), your tick marks will likely not even be
whole numbers.  As in all other cases, you can set a tick anchor to position
the tick marks at the values you prefer.
</p><p>
Here are some examples of PHPlot-calculated plot ranges and tick positions,
when no tick anchor has been set.
  </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>
The bottom of the Y range is extended to zero, and the tick marks are at
multiples of 10. The top of the Y range is extended to the next tick mark.
          </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>
With <code class="literal">'R'</code> adjustment mode, the top of the Y range is
extended by 3% of the range. The bottom of the Y range was moved to zero
(due to the <span class="emphasis"><em>zero magnet</em></span>), so the tick marks are based
at 0 and positioned at whole multiples of 10. The resulting tick marks
are the same as <code class="literal">'T'</code> mode, except the Y axis does not end
at a tick mark.
          </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>
Here <code class="literal">'I'</code> adjustment mode is almost the the same as the
previous case, except the top of the range is adjusted to the next integer.
Since there is no tick mark there, the difference would not be visible.
          </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>
Both ends of plot range are adjusted to a tick position,
with an implied tick anchor at 0. The resulting tick marks are at
whole multiples of the tick step 5.
          </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>
In this mode, the range is simply extended by 3% (by default) at each end,
where 3% of (33+17) = 1.5. The resulting tick mark positions are probably
not ideal.
          </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>
In this mode, the range is extended by 3%, and then the ends are extended
to the next integer. The tick mark positions are whole numbers now, but
not anchored at 0.
          </td></tr></tbody></table></div><p>
</p><p>
To summarize, setting a tick anchor to force the tick positions to align one
tick at a particular value, usually 0, can be useful in the situations
including:
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
You are letting PHPlot calculate the range, but with adjustment mode
<code class="literal">R</code> (range) or <code class="literal">I</code> (integer).
      </p></li><li class="listitem"><p>
You are manually setting the minimum of the plot range with
<a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to a value other than zero or
a whole multiple of the tick increment.
      </p></li><li class="listitem"><p>
You are using date/time values along the axis, and you need the ticks to
start at a specific date/time value (such as the start of an experiment).
      </p></li><li class="listitem"><p>
You are using a version before PHPlot-6.0.0, which only supports an
adjustment mode similar to <code class="literal">I</code> (integer).
      </p></li></ul></div><p>
</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>
Given incomplete or contradictory data, PHPlot will always produce a positive
plot range (PlotMin &lt; PlotMax), although the range may be somewhat arbitrary.
Here are some of the regressive cases, and how PHPlot produces an automatic
range for them. <code class="literal">DataMin</code> and <code class="literal">DataMax</code>
mean the limits of the data from the data array; <code class="literal">PlotMin</code>
and <code class="literal">PlotMax</code> are the limits of the plot range.
In all cases, any values specified in <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> will
not be altered by PHPlot, even if it results in a plot with no visible data
points.

  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Empty range with non-zero values (DataMin == DataMax != 0):</span></dt><dd><p>
For positive data, PHPlot uses the range 0 to K, where K is the larger of
DataMin and 10. For example, if all the Y values are 5, PHPlot uses 0 to 10
for the Y range; if all the Y values are 150, PHPlot uses 0 to 150.
For negative data, PHPlot uses a similar method, setting PlotMax=0.
        </p></dd><dt><span class="term">Empty range with all zero values (DataMin == DataMax == 0):</span></dt><dd><p>
PHPlot uses the arbitrary range 0 to 10.
        </p></dd><dt><span class="term">Partially specified range with maximum set and all data above that:</span></dt><dd><p>
If you set PlotMax to a value, but all your data is above that (DataMin &gt;
PlotMax), you will get an empty plot. PHPlot will use a range of 0 to
PlotMax if your PlotMax is positive, else a range of PlotMax-10 to PlotMax.
All your data points will be outside the plot area.
        </p></dd><dt><span class="term">Partially specified range with minimum set and all data below that:</span></dt><dd><p>
If you set PlotMin to a value, but all your data is below that (DataMax &lt;
PlotMin), you will get an empty plot. PHPlot will use a range of PlotMin
to 0 if your PlotMin is negative, else a range of PlotMin to PlotMin+10.
All your data points will be outside the plot area.
        </p></dd><dt><span class="term">Negative range or zero range:</span></dt><dd><p>
If you try to use <a class="xref" href="SetPlotAreaWorld.html" title="SetPlotAreaWorld"><span class="refentrytitle">SetPlotAreaWorld</span></a> to set a negative
range (PlotMin &gt; PlotMax) or zero range (PlotMin == PlotMax), PHPlot
will report an error and not produce a plot.
        </p></dd></dl></div><p>
</p><p>
Note that the above range choices happen as part of the "initialization"
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>
above). That is, the selected range is then subject to the same adjustments as
in other cases.
</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>