manual/axis.tex

   1 \chapter{Axes\label{axis}}
   2
   3 Axes are a fundamental component of graphs although there might be use
   4 cases outside of the graph system. Internally axes are constructed out
   5 of components, which handle different tasks and axis need to fullfill:
   6
   7 \begin{definitions}
   8 \term{axis}
   9   Basically a container for axis data and the components. It
  10   implements the conversion of a data value to a graph coordinate of
  11   range [0:1]. It does also handle the proper usage of the components
  12   in complicated tasks (\emph{i.e.} combine the partitioner, texter,
  13   painter and rater to find the best partitioning).
  14 \term{tick}
  15   Ticks are plotted along the axis. They might be labeled with text as
  16   well.
  17 \term{partitioner, in the code the short form ``parter'' is used}
  18   Creates one or several choises of tick lists suitable to a certain
  19   axis range.
  20 \term{texter}
  21   Creates labels for ticks when they are not set manually.
  22 \term{painter}
  23   Responsible to paint the axis.
  24 \term{rater}
  25   Calculate ratings, which can be used to select the best suitable
  26   partitioning.
  27 \end{definitions}
  28
  29 The names above map directly to modules, which are provided in the
  30 directory \file{graph/axis}. Sometimes it might be conventient to
  31 import the axis directory directly rather access them through the
  32 graph. This would look like:
  33 \begin{verbatim}
  34   from pyx import *
  35   graph.axis.painter() # and the like
  36
  37   from pyx.graph import axis
  38   axis.painter() # this is shorter ...
  39 \end{verbatim}
  40
  41 In most cases different implementations are available through
  42 different classes, which can be combined in various ways. There are
  43 various axis examples distributed with \PyX{}, where you can see some
  44 of the features of the axis with a few lines of code each. Hence we
  45 can here directly step on to the reference of the available
  46 components.
  47
  48 \section{Axes}
  49
  50 \declaremodule{}{graph.axis.axis}
  51 \modulesynopsis{Axes}
  52
  53 The following classes are part of the module \module{graph.axis.axis}.
  54 However, there is a shortcut to access those classes via
  55 \code{graph.axis} directly. Instances of the classes can be passed to
  56 the \var{**axes} keyword arguments of a graph. Those instances should
  57 be used once only.
  58
  59 \begin{classdesc}{linear}{min=None, max=None, reverse=0, divisor=None, title=None,
  60                           parter=parter.autolinear(), manualticks=[],
  61                           density=1, maxworse=2, rater=rater.linear(),
  62                           texter=texter.default(), painter=painter.plain()}
  63   This class provides a linear axis. \var{min} and \var{max} are the
  64   axis range. When not set, they are adjusted automatically by the
  65   data to be plotted in the graph. Note, that some data might want to
  66   access the range of an axis (\emph{e.g.} the \class{function} class
  67   when no range was provided there) or you need to specify a range
  68   when using the axis without plugging it into a graph (\emph{e.g.}
  69   when drawing a axis along a path).
  70
  71   \var{reverse} can be set to indicate a reversed axis starting with
  72   bigger values first. Alternatively you can fix the axis range by
  73   \var{min} and \var{max} accordingly. When divisor is set, it is
  74   taken to divide all data range and position informations while
  75   creating ticks. You can create ticks not taking into account a
  76   factor by that. \var{title} is the title of the axis.
  77
  78   \var{parter} is a partitioner instance, which creates suitable ticks
  79   for the axis range. Those ticks are merged with manual given ticks
  80   by \var{manualticks} before proceeding with rating, painting
  81   \emph{etc.} Manually placed ticks win against those created by the
  82   partitioner. For automatic partitioners, which are able to calculate
  83   several possible tick lists for a given axis range, the
  84   \var{density} is a (linear) factor to favour more or less ticks. It
  85   should not be stressed to much (its likely, that the result would be
  86   unappropriate or not at all valid in terms of rating label
  87   distances). But within a range of say 0.5 to 2 (even bigger for
  88   large graphs) it can help to get less or more ticks than the default
  89   would lead to. \var{maxworse} is a the number of trials with more
  90   and less ticks when a better rating was already found. \var{rater}
  91   is a rater instance, which rates the ticks and the label distances
  92   for being best suitable. It also takes into account \var{density}.
  93   The rater is only needed, when the partitioner creates several tick
  94   lists.
  95
  96   \var{texter} is a texter instance. It creates labels for those
  97   ticks, which claim to have a label, but do not have a label string
  98   set already. Ticks created by partitioners typically receive their
  99   label strings by texters. The \var{painter} is finally used to
 100   construct the output. Note, that usually several output
 101   constructions are needed, since the rater is also used to rate the
 102   distances between the label for an optimum.
 103 \end{classdesc}
 104
 105 \begin{classdesc}{lin}{...}
 106   This class is an abbreviation of \class{linear} described above.
 107 \end{classdesc}
 108
 109 \begin{classdesc}{logarithmic}{min=None, max=None, reverse=0, divisor=None, title=None,
 110                                parter=parter.autologarithmic(), manualticks=[],
 111                                density=1, maxworse=2, rater=rater.logarithmic(),
 112                                texter=texter.default(), painter=painter.plain()}
 113   This class provides a logarithmic axis. All parameters work like
 114   \class{linear}. Only two parameters have a different default:
 115   \var{parter} and \var{rater}. Furthermore and most importantly, the
 116   mapping between data and graph coordinates is logarithmic.
 117 \end{classdesc}
 118
 119 \begin{classdesc}{log}{...}
 120 This class is an abbreviation of \class{logarithmic} described above.
 121 \end{classdesc}
 122
 123 \begin{classdesc}{linked}{linkedaxis, painter=painter.linked()}
 124   This class provides an axis, which is linked to another axis
 125   instance. This means, it shares all its properties with the axis it
 126   is linked too except for the painter. Thus a linked axis is painted
 127   differently.
 128
 129   A standard use case are the \code{x2} and \code{y2} axes in an
 130   x-y-graph. Linked axes to the \code{x} and \code{y} axes are created
 131   automatically when not disabled by setting those axes to
 132   \code{None}. By that, ticks are stroked at both sides of an
 133   x-y-graph. However, linked axes can be used for in other cases as
 134   well. You can link axes within a graph or between different graphs
 135   as long as the orgininal axis is finished first (it must fix its
 136   layout first).
 137 \end{classdesc}
 138
 139 \begin{classdesc}{split}{subaxes, splitlist=[0.5],
 140                          splitdist=0.1, relsizesplitdist=1,
 141                          title=None, painter=painter.split()}
 142   This class provides an axis, splitting the input values to its
 143   subaxes depeding on the range of the subaxes. Thus the subaxes
 144   need to have fixed range, up to the minimum of the first axis and
 145   the maximum of the last axis. \var{subaxes} actually takes the list
 146   of subaxes. \var{splitlist} defines the positions of the spliting
 147   in graph coordinates. Thus the length of \var{subaxes} must be the
 148   length of \var{splitlist} plus one. If an entry in \var{splitlist}
 149   is \code{None}, the axes aside define the split position taking into
 150   account the ratio of the axes ranges (meassured by an internal
 151   \code{relsize} attribute of each axis).
 152
 153   \var{splitdist} is the space reserved for a splitting in graph
 154   coordinates, when the corresponding entry in \var{splitlist} is not
 155   \code{None}. \var{relsizesplitdist} is the space reserved for the
 156   splitting in terms, when the corresponding entry in \var{splitlist}
 157   is \code{None} compared to the \code{relsize} of the axes aside.
 158
 159   \var{title} is the title of the split axes and \var{painter} is a
 160   specialized painter, which takes care of marking the axes breaks,
 161   while the painting of the subaxes are performed by their painters
 162   themself.
 163 \end{classdesc}
 164
 165 \begin{classdesc}{linkedsplit}{linkedaxis,
 166                                painter=painter.linkedsplit(),
 167                                subaxispainter=omitsubaxispainter}
 168   This class provides an axis, which is linked to an instance of
 169   \class{split}. The purpose of a linked axis is described in class
 170   \class{linked} above. \var{painter} replaces the painter from the
 171   \var{linkedaxis} instance.
 172
 173   While this class creates linked axes for the subaxes of
 174   \var{linkedsplit} as well, the question arises what painters to use
 175   there. When \var{subaxispainter} is not set, no painter is given
 176   explicitly leaving this decision to the subaxes themself. This will
 177   lead to omitting all labels and the title. However, you can use a
 178   changeable attribute of painters in \var{subaxispainter} to replace
 179   the default.
 180 \end{classdesc}
 181
 182 \begin{classdesc}{bar}{subaxis=None, multisubaxis=None,
 183                        dist=0.5, firstdist=None, lastdist=None,
 184                        title=None, painter=painter.bar()}
 185   This class provides an axis suitable for a bar style. It handles a
 186   discrete set of values and maps them to distinct ranges in graph
 187   coordinates. For that, the axis gets a list as data values. The
 188   first entry is taken to be one of the discrete values valid on this
 189   axis. All other parameters, lets call them others, are passed to a
 190   subaxis. When others has only one entry, it is passed as a value,
 191   otherwise as a list. The result of the conversion done by the
 192   subaxis is mapped into the graph coordinate range for this discrete
 193   value. When neigher \var{subaxis} nor \var{multisubaxis} is set,
 194   others must be a single value in range [0:1]. This value is used for
 195   the position at the subaxis without converion.
 196
 197   When \var{subaxis} is set, it is used for the conversion of others.
 198   When \var{multisubaxis} is set, it must be an instance of \var{bar}
 199   as well. It is than dublicated for each of the discrete values
 200   allowed for the axis. By that, you can create nested bar axes with
 201   a different discrete values for each discrete value of the axis. It
 202   is not allowed to set both, \var{subaxis} and \var{multisubaxis}.
 203
 204   \var{dist} is used as the spacing between the ranges for each
 205   distinct value. It is measured in the same units as the subaxis
 206   results, thus the default value of \code{0.5} means halve the width
 207   between the distinct values as the width for each distinct value.
 208   \var{firstdist} and \var{lastdist} are used before the first and
 209   after the last value. When set to \code{None}, halve of \var{dist}
 210   is used.
 211
 212   \var{title} is the title of the split axes and \var{painter} is a
 213   specialized painter for an bar axis. When \var{multisubaxis} is
 214   used, their painters are called as well, otherwise they are not
 215   taken into account.
 216 \end{classdesc}
 217
 218 \section{Ticks}
 219
 220 \declaremodule{}{graph.axis.tick}
 221 \modulesynopsis{Axes ticks}
 222
 223 We describe only one class of the module \module{graph.axis.tick}
 224 here. Instances of this class are usefill in the \code{manualticks}
 225 parameter of a regular axis.
 226
 227 \begin{classdesc}{tick}{pos, ticklevel=0, labellevel=0, label=None,
 228                         labelattrs=[], power=1, floatprecision=10}
 229   \var{pos} is the position of the tick. Since ticks use rational
 230   number arithmetics, a convertion to a rational number needs to be
 231   performed. \var{pos} can hold different types for that:
 232   \begin{itemize}
 233   \item A float. It is converted to a rational with finite precision
 234     determined by \var{floatprecision}.
 235   \item A string, which is parsed to a rational number with full
 236     precision. It is also allowed to provide a fraction like
 237     \samp{1/3}.
 238   \item A tuple of two integers. Those integers are taken as
 239     enumerator and denominator of the rational.
 240   \end{itemize}
 241
 242   A tick has a tick level (\emph{i.e.} markers at the axis path) and a
 243   label lavel (\emph{e.i.} place text at the axis path),
 244   \var{ticklevel} and \var{labellevel}. These are non-negative
 245   integers or \var{None}. A value of \code{0} means a regular tick or
 246   label, \code{1} stands for a subtick or sublabel, \code{2} for
 247   subsubtick or subsublabel and so on. \code{None} means omitting the
 248   tick or label. \var{label} is the text of the label. When not set,
 249   it can be created automatically by a texter. \var{labelattrs} are
 250   the attributes for the labels.
 251
 252   \var{power} is an integer to calculate \samp{pos**code}. This is
 253   usefull at certain places in partitioners.
 254 \end{classdesc}
 255
 256 \section{Partitioners}
 257
 258 \declaremodule{}{graph.axis.parter}
 259 \modulesynopsis{Axes partitioners}
 260
 261 The following classes are part of the module \module{graph.axis.parter}.
 262 Instances of the classes can be passed to the parter keyword argument
 263 of regular axes.
 264
 265 \begin{classdesc}{linear}{tickdist=None, labeldist=None,
 266                           extendtick=0, extendlabel=None,
 267                           epsilon=1e-10}
 268   TODO: to be continued ...
 269 \end{classdesc}
 270
 271 \begin{classdesc}{lin}{...}
 272 This class is an abbreviation of \class{linear} described above.
 273 \end{classdesc}
 274
 275 \begin{classdesc}{autolinear}{variants=defaultvariants,
 276                               extendtick=0,
 277                               epsilon=1e-10}
 278   TODO: to be continued ...
 279 \end{classdesc}
 280
 281 \begin{classdesc}{autolin}{...}
 282 This class is an abbreviation of \class{autolinear} described above.
 283 \end{classdesc}
 284
 285 \begin{classdesc}{logarithmic}{tickpos=None, labelpos=None,
 286                                extendtick=0, extendlabel=None,
 287                                epsilon=1e-10}
 288   TODO: to be continued ...
 289 \end{classdesc}
 290
 291 \begin{classdesc}{log}{...}
 292 This class is an abbreviation of \class{logarithmic} described above.
 293 \end{classdesc}
 294
 295 \begin{classdesc}{autologarithmic}{variants=defaultvariants,
 296                                    extendtick=0, extendlabel=None,
 297                                    epsilon=1e-10}
 298   TODO: to be continued ...
 299 \end{classdesc}
 300
 301 \begin{classdesc}{autolog}{...}
 302 This class is an abbreviation of \class{autologarithmic} described above.
 303 \end{classdesc}
 304