(r1) CDAxisSetAxisAutoScale < Main

Tags: view all tags
---+ .AXIS SET AXIS SCALE

_This subroutine sets the top extension, bottom extension, and zero affinity values that are to be used when auto-scaling the "current" axis._

<br />%TOC%
---++ Usage:
<pre>* Opt PASS         &lt;top_exten&gt;                FIELD            SHARE? N
* Opt PASS         &lt;bot_exten&gt;                FIELD            SHARE? N
* Opt PASS         &lt;zero_affn&gt;                FIELD            SHARE? N
*     GOSUB    0CD .AXIS SET AXIS SCALE
      *        Check for error
*     IF       0CD .AXIS SET AXIS SCALE       NE

</pre>
---++ Description:

This subroutine sets the top extension, bottom extension, and zero affinity values that are to be used when auto-scaling the "current" axis. You must have selected a "current" axis via [[CDAxisSetCurrent][.AXIS SET CURRENT]] before calling this routine.

<div id="_mcePaste">During auto-scaling, it is often desirable to leave some margins at the ends of the axis. For example, suppose in a bar chart, the longest bar is 10 units. If auto-scaling chooses 0 - 10 as the scale, the longest bar will touch the top edge of the plot area. In many cases, the chart will look better if there is some margin so that the longest bar does not touch the top edge.</div>

<div id="_mcePaste">This subroutine can be used to reserve some margins at the ends of the axis by using a scale that is larger than necessary. For example, in the above case, if a scale of 0 - 12 is used, then the longest bar will not touch the top edge.</div> <div id="_mcePaste"></div>

Other common reasons for reserving margins at the ends of the axis include making sure the data labels (which may be drawn on top of the data points) will not go outside the plot area, and that objects put at the top or bottom of the plot area (such as legend box and custom text box) will not overlap with the data points.

<div id="_mcePaste">Note that there is an alternative way to reserve space at the ends of the axis - the [[CDAxisSetAxisMargins][.AXIS SET AXIS MARGIN]] subroutine.</div>

<div id="_mcePaste">The amount of margins reserved is controlled by the &lt;top_exten&gt; and &lt;bot_exten&gt; arguments. These arguments determine the portion of the axis where no data point can reach. For example, a &lt;top_exten&gt; of 0.2 will ensure no data point can fall within the top 20% of the axis.</div>

<div id="_mcePaste">Note that Chart Director will not extend the scale across the 0 point.</div>

<div id="_mcePaste">For example, suppose the data range is 0.1 - 9.9. If 10% margin is added to the bottom end of the axis, the bottom end may become negative. In this case, Chart Director will extend the bottom end to 0 at most.</div>

<div id="_mcePaste">In other words, if the data range is completely positive, Chart Director will not extend the axis to negative, as it would be undesirable in most applications. The same applies if the data range is completely negative.</div>

<div id="_mcePaste">For a purely positive axis, the bottom end has "zero affinity". That means Chart Director will tend to choose 0 as the bottom end because zero is a natural starting point for the axis. However, if the data range is too extreme (e.g. the data is in the range 10000 - 10005), it may be "unreasonable" to choose 0 as the axis starting point. In this case, Chart Director will not use 0 as the axis starting point.</div>

<div id="_mcePaste">Chart Director will determine that it is "unreasonable" to use 0 as the axis starting point if the data fluctuation (the difference between the maximum and minimum data values) is too small compared with the data value. Chart Director tests the "too small" condition using the formula:</div>

<div id="_mcePaste">maxDataValue * zeroAffinity &lt; minDataValue</div>

<div id="_mcePaste">where zeroAffinity by default is 0.8.</div>

<div id="_mcePaste">Similar "zero affinity" mechanism applies to the top end of the axis for a purely negative axis. If the data range contains both positive and negative values, the zero point is always included.</div>

<div id="_mcePaste">The &lt;zero_affn&gt; parameter allows you to modify the zero affinity when performing auto-scaling. Zero affinity should be between 0 and 1. A large value encourages Chart Director to start the axis from zero.</div>

<div id="_mcePaste">A &lt;zero_affn&gt; of 1 means the axis always includes the zero point. A &lt;zero_affn&gt; of 0 means that the axis is scaled purely according to the data range, without any preference for the zero point.</div>

---++ Comments:

_Read what other users have said about this page or add your own comments._

<br />%COMMENT%

-- Main.JeanNeron - 2011-11-09
Topic revision: r1 - 2011-11-09 - JeanNeron
~~Edit~~
~~Attach~~