design/graph.txt

   1 Structure of modules and classes in the graph subdirectory
   2
   3 general TODO: separate all interface definitions from implemenations (and finish all interface definitions)
   4
   5 tick.py
   6
   7     frac [a very basic and limited rational number type]
   8     tick(frac) [tick position based on a rational number (includes interface definition)]
   9
  10     (contains some helper functions to build and handle a list of ticks)
  11
  12     TODO: - move tick.py to axis/tick.py
  13           - frac -> rational
  14
  15
  16 parter.py
  17
  18     _Iparter [interface definition]
  19
  20     linparter [parter for linear axes]
  21     autolinparter [automatic parter for linear axes (default parter for linear axes)]
  22
  23     preexp [helper class for defining tick positions on a logarithmic scale]
  24
  25     logparter(linparter) [parter for logarithmic axes]
  26     autologparter(logparter) [automatic parter for logarithmix axes (default parter for logarithmic axes)]
  27
  28     TODO: - move parter.py to axis/parter.py
  29           - linparter -> linear
  30           - autolinparter -> autolinear
  31           - logparter -> logarithmic
  32           - autologparter -> autologarithmic
  33
  34 texter.py
  35
  36     _Itexter [interface definition]
  37
  38     rationaltexter [implements _Itexter to create rational number labels]
  39     decimaltexter [implements _Itexter to create decimal labels]
  40     exponentialtexter [implements _Itexter to create exponentential labels]
  41     defaulttexter [implements _Itexter by mixing decimal and exponential texter (default texter for regular axes)]
  42
  43     TODO: - move texter.py to axis/texter.py
  44           - rationaltexter -> rational
  45           - decimaltexter -> decimal
  46           - exponentialtexter -> exponential
  47           - defaulttexter -> default
  48
  49 painter.py
  50
  51     _Iaxispainter [interface definition]
  52     _Iaxispos [interface definition]
  53
  54     axiscanvas(canvas.canvas) [canvas to draw axis on (includes interface definition)]
  55     rotatetext [class to calculate rotation operation for a given tick direction (includes interface definition)]
  56
  57     _axispos [partially implements _Iaxispos interface]
  58     pathaxispos(_axispos) [implements _Iaxispos for an arbitrary path]
  59
  60     axistitlepainter [implements _Iaxis (shared task of plotting axis titles in derived axispainters)]
  61
  62     geometricseries(attr.changeattr) [a changeable attribute resulting in a geometric series]
  63     ticklength(geometricseries) [geometric series for tick lengths]
  64
  65     axispainter(axistitlepainter) [default axis painter for regular axes (linaxis, logaxis)]
  66     linkaxispainter(axispainter) [default axis painter for linked regular axes (turns off some features)]
  67
  68     subaxispos [implements _Iaxispos for subaxes, which occure in split axes and bar axes)]
  69
  70     splitaxispainter(axistitlepainter) [default axis painter for split axes]
  71     omitsubaxispainter [helper class for linksplitaxis argument handling]
  72     linksplitaxispainter(splitaxispainter) [default axis painter for linked split axes]
  73
  74     baraxispainter(axistitlepainter) [default axis painter for bar axes]
  75     linkbaraxispainter(baraxispainter) [default axis painter for linked bar axes]
  76
  77     TODO: - move painter.py to axis/painter.py
  78           - axistitlepainter -> _axistitle
  79           - axispainter -> default
  80 <MS>               ein "default" sollte doch eigentlich nur ein link auf einen existierenden painter sein.
  81                    (gilt auch beim texter, etc...)
  82                    wie waere es mit "plain" ?
  83 <AW>               Von mir aus gern. Ich würde dann aber das default ganz sein lassen. Es gibt einen plain
  84                    painter für normale Achsen ...
  85           - linkaxispainter -> linked
  86           - splitaxispainter -> split
  87           - linksplitaxispainter -> linkedsplit
  88           - baraxispainter -> bar
  89           - linkbaraxispainter -> linkedbar
  90
  91 rater.py
  92
  93     cuberater [rater for values like the number of ticks etc. (includes interface definition)]
  94
  95     distancerater [rater for optimal distances of boxes (includes interface definition)]
  96
  97     rater.py [rater for ticks and axis layout (includes interface definition)]
  98
  99     TODO: - move rater.py to axis/rater.py
 100           - cuberater -> cube
 101 <MS>                was hat der Wuerfel mit dem rater zu tun?
 102                     "Double Dangerous Bends" here: Ich habe noch _nie_ einen rater umgestellt ;-)
 103 <AW>                selbst ich habe noch nie einen Achsenrater auch nur umkonfiguriert. Man braucht
 104                     das defakto nicht. Umso uninteressanter ist der Name. Ich würde cube lassen, denn
 105                     es ist ein **3-rater für Zahlen. Wie sollte man den sonst nennen?
 106           - distancerater -> distance
 107           - rater -> _rater
 108           - new class "linear" with predefined variables for linear partitions
 109           - new class "logarithmic" with predefined variables for logarithmic partitions
 110
 111 axis.py
 112
 113     _Imap [interface definition]
 114     _Iaxis [interface definition]
 115
 116     _linmap [implements _Imap for a linear axis]
 117     _logmap [implements _Imap for a logarithmic axis]
 118
 119     _axis [partitionally implements _Iaxis; _Imap is missing to fully implement _Iaxis]
 120
 121     linaxis(_axis, _linmap) [implements _Iaxis for a linear axis]
 122     logaxis(_axis, _linmap) [implements _Iaxis for a logarithmic axis]
 123
 124     linkaxis [implements _Iaxis by linking to a linaxis or logaxis instance]
 125
 126     splitaxis [implements _Iaxis for a splitable axis]
 127     linksplitaxis(linkaxis) [implements _Iaxis by linking to a splitaxis instance]
 128
 129     baraxis [implements _Iaxis for a bar axis]
 130     linkbaraxis(linkaxis) [implements _Iaxis by linking to a baraxis instance]
 131
 132     (helper function pathaxis to draw a axis at an arbitrary path)
 133
 134     TODO: - move axis.py to axis/type.py
 135 <MS>                Ich finde -- vor allem bei der Diskussion um zu lange Namen --
 136                     das "type" ueberfluessig. Man sollte das hier ins __init__ von axis einfuegen
 137                     mit "from type import *" in __init__.py,
 138                     so dass man mit graph.axis.linear(...) bekommt, was Du hier anbietest.
 139
 140                     Das gleiche gilt uebrigens fuer graph.type
 141
 142 <AW>                Interessante Möglichkeit. Allerdings wird im __init__ nie viel ausprogrammiert.
 143                     Man könnte aber Dinge reinladen. Bin -0 zum Laden ...
 144
 145                     Hat denn die Benutzerbefragung hinsichtlich eines Verzeichnisses pyx/axis was
 146                     gebracht? Das ist hinsichtlich der Verkürzung der Namen viel wirksamer ...
 147           - linaxis -> linear
 148           - logaxis -> logarithmic
 149           - linkaxis -> linked
 150           - splitaxis -> split
 151           - linksplitaxis -> linkedsplit
 152           - baraxis -> bar
 153           - linkbaraxis -> linkedbar
 154
 155 key.py
 156
 157     [interface definition missing]
 158
 159     class key [graph key painter]
 160
 161 style.py
 162
 163     [interface definition missing]
 164
 165     _style [collection of common operations performed by styles]
 166
 167     symbolline(_style) [style for drawing symbols with errorbars and lines]
 168     line(symbolline) [reduction of symbollines to lines only]
 169     symbol(symbolline) [reduction of symbollines to symbols with errorbars only]
 170     text(symbol) [extend symbol style to show given text at the symbols]
 171     arrow(_style) [draw arrows with given size and direction]
 172     rect(_style) [draw rectangles with given color]
 173     bar(_style) [draw bars in a bar graph]
 174
 175     TODO: - rect -> rectangle
 176 <MS>               Wir habe im path, in box, etc. ueberall "rect".
 177 <AW>               Stimmt. Ist das denn gut, dass wir das da auch haben?
 178
 179
 180 data.py
 181
 182     [interface definition missing]
 183
 184     data [data from a pyx.data.data instance]
 185     function [data from a function]
 186     paramfunction [data from a parametric function]
 187
 188     TODO: - data -> file
 189           - move pyx/data.py into pyx/graph/data.py:
 190              - the construct graph.data.data(data.datafile(<filename>), ...)) should become graph.data.file(...)
 191              - the construct graph.data.data(data.data(<filename>), ...)) should become graph.data.list(...)
 192 <MS>                   Man will doch drei Arten, einen Datenplot zu machen:
 193                        1. filename
 194                        2. Liste von Daten
 195                        3. Data-Objekt (wenn man vorher diverse addcolumn-Methoden aufgerufen hat)
 196                        Oben sieht das so aus, als wolltest Du nur noch 1. und 2. unterstuetzen.
 197 <AW>                   Nun, ich will eigentlich die Seiteneffekte auch loswerden. Das addcolumn ist vollkommen
 198                        krank. Wenn man graph.data.data(df, x="2*$1") machst, hast Du auf einmal eine Spalte
 199                        im df mehr (!) ... addcolumn ist eine Eigenschaft, die graph.data.data haben sollte und
 200                        nichts mit dem pyx.data.datafile zu tun hat. Zusätzlich berechnete Spalten sollten in einer
 201                        zweiten, neuen Datenliste gehalten werden -- das jetzige Durcheinander ist eine Katastrophe.
 202                        Die Styles müssen lernen, damit umzugehen. Das wird im graph.style._style zur Verfügung gestellt
 203                        (im wesentlichen ein itertool.izip bzw. eine entsprechende fallback-Lösung).
 204              - the caching currently available by using the same instance of data.datafile several times
 205                should become an intrinsic feature (with the option to turn it off by the keyword parameter cache=0
 206                (like in rrules of the dateutil package))
 207
 208 type:
 209
 210     [interface definition missing -- we don't really have interfaces here, but we may introduce some generic
 211     behaviour of all graphs (domethods, access to axes and positions, etc.)]
 212
 213     lineaxispos [implements _Iaxispos for a straight line]
 214     lineaxisposlinegrid(lineaxispos) [like _Iaxispos but adds grid lines for a x-y-graph]
 215     graphxy(canvas.canvas) [x-y-graph]
 216
 217 timeaxis.py (experimental code, needs python 2.3)
 218
 219     _timemap [implements _Imap for datetime instances]
 220     timetick(datetime.datetime) [tick position based on datetime]
 221     timetexter [implements _Itexter as a primitiv texter for datetime instances]
 222     timeaxis(axis._axis, _timemap) [implements _Iaxis for a time axis]
 223
 224 NOTE: The timeaxis should be kept as separately as possible. It needs Python 2.3 and dateutils
 225       (dateutils is not yet needed while we currently also lack (auto-)partitioning of a timeaxis;
 226       there is an ongoing discussion with Gustavo Niemeyer about some patches).
 227