#Copyright ReportLab Europe Ltd. 2000-2012

#see license.txt for license details

__version__=''' $Id$ '''

from tools.docco.rl_doc_utils import *

from reportlab.graphics.shapes import *

heading2("Charts")

disc("""

The motivation for much of this is to create a flexible chart

package.

This section presents a treatment of the ideas behind our charting

model, what the design goals are and what components of the chart

package already exist.

""")

heading3("Design Goals")

disc("Here are some of the design goals: ")

disc("<i>Make simple top-level use really simple </i>")

disc("""<para lindent="+36">It should be possible to create a simple chart with minimum lines of

       code, yet have it 'do the right things' with sensible automatic

       settings. The pie chart snippets above do this. If a real chart has

       many subcomponents, you still should not need to interact with them

       unless you want to customize what they do.</para>""")

disc("<i>Allow precise positioning </i>")

disc("""<para lindent="+36">An absolute requirement in publishing and graphic design is to control

       the placing and style of every element. We will try to have properties

       that specify things in fixed sizes and proportions of the drawing,

       rather than having automatic resizing. Thus, the 'inner plot

       rectangle' will not magically change when you make the font size of

       the y labels bigger, even if this means your labels can spill out of

       the left edge of the chart rectangle. It is your job to preview the

       chart and choose sizes and spaces which will work.</para>""")

disc("""<para lindent="+36">Some things do need to be automatic. For example, if you want to fit N

       bars into a 200 point space and don't know N in advance, we specify

       bar separation as a percentage of the width of a bar rather than a

       point size, and let the chart work it out. This is still deterministic

       and controllable.</para>""")

disc("<i>Control child elements individually or as a group</i>")

disc("""<para lindent="+36">We use smart collection classes that let you customize a group of

       things, or just one of them. For example you can do this in our

       experimental pie chart:</para>""")

eg("""

d = Drawing(400,200)

pc = Pie()

pc.x = 150

pc.y = 50

pc.data = [10,20,30,40,50,60]

pc.labels = ['a','b','c','d','e','f']

pc.slices.strokeWidth=0.5

pc.slices[3].popout = 20

pc.slices[3].strokeWidth = 2

pc.slices[3].strokeDashArray = [2,2]

pc.slices[3].labelRadius = 1.75

pc.slices[3].fontColor = colors.red

d.add(pc, '')

""")

disc("""<para lindent="+36">pc.slices[3] actually lazily creates a little object which holds

       information about the slice in question; this will be used to format a

       fourth slice at draw-time if there is one.</para>""")

disc("<i>Only expose things you should change </i>")

disc("""<para lindent="+36">It would be wrong from a statistical viewpoint to let you directly

       adjust the angle of one of the pie wedges in the above example, since

       that is determined by the data. So not everything will be exposed

       through the public properties. There may be 'back doors' to let you

       violate this when you really need to, or methods to provide advanced

       functionality, but in general properties will be orthogonal.</para>""")

disc("<i>Composition and component based </i>")

disc("""<para lindent="+36">Charts are built out of reusable child widgets. A Legend is an

       easy-to-grasp example. If you need a specialized type of legend (e.g.

       circular colour swatches), you should subclass the standard Legend

       widget. Then you could either do something like...</para>""")

eg("""

c = MyChartWithLegend()

c.legend = MyNewLegendClass()    # just change it

c.legend.swatchRadius = 5    # set a property only relevant to the new one

c.data = [10,20,30]   #   and then configure as usual...

""")

disc("""<para lindent="+36">...or create/modify your own chart or drawing class which creates one

       of these by default. This is also very relevant for time series

       charts, where there can be many styles of x axis.</para>""")

disc("""<para lindent="+36">Top level chart classes will create a number of such components, and

       then either call methods or set private properties to tell them their

       height and position - all the stuff which should be done for you and

       which you cannot customise. We are working on modelling what the

       components should be and will publish their APIs here as a consensus

       emerges.</para>""")

disc("<i>Multiples </i>")

disc("""<para lindent="+36">A corollary of the component approach is that you can create diagrams

       with multiple charts, or custom data graphics. Our favourite example

       of what we are aiming for is the weather report in our gallery

       contributed by a user; we'd like to make it easy to create such

       drawings, hook the building blocks up to their legends, and feed that

       data in a consistent way.</para>""")

disc("""<para lindent="+36">(If you want to see the image, it is available on our website

<font color="blue"><a href="https://www.reportlab.com/media/imadj/data/RLIMG_e5e5cb85cc0a555f5433528ac38c5884.PDF">here</a></font>)</para>""")

##heading3("Key Concepts and Components")

heading3("Overview")

disc("""A chart or plot is an object which is placed on a drawing; it is not

       itself a drawing. You can thus control where it goes, put several on

       the same drawing, or add annotations.""")

disc("""Charts have two axes; axes may be Value or Category axes. Axes in turn

       have a Labels property which lets you configure all text labels or

       each one individually. Most of the configuration details which vary

       from chart to chart relate to axis properties, or axis labels.""")

disc("""Objects expose properties through the interfaces discussed in the

       previous section; these are all optional and are there to let the end

       user configure the appearance. Things which must be set for a chart to

       work, and essential communication between a chart and its components,

       are handled through methods.""")

disc("""You can subclass any chart component and use your replacement instead

       of the original provided you implement the essential methods and

       properties.""")

heading2("Labels")

disc("""

A label is a string of text attached to some chart element.

They are used on axes, for titles or alongside axes, or attached

to individual data points.

Labels may contain newline characters, but only one font.

""")

disc("""The text and 'origin' of a label are typically set by its parent

       object. They are accessed by methods rather than properties. Thus, the

       X axis decides the 'reference point' for each tickmark label and the

       numeric or date text for each label. However, the end user can set

       properties of the label (or collection of labels) directly to affect

       its position relative to this origin and all of its formatting.""")

eg("""

from reportlab.graphics import shapes

from reportlab.graphics.charts.textlabels import Label

d = Drawing(200, 100)

# mark the origin of the label

d.add(Circle(100,90, 5, fillColor=colors.green))

lab = Label()

lab.setOrigin(100,90)

lab.boxAnchor = 'ne'

lab.angle = 45

lab.dx = 0

lab.dy = -20

lab.boxStrokeColor = colors.green

lab.setText('Some\nMulti-Line\nLabel')

d.add(lab)

""")

from reportlab.graphics import shapes

from reportlab.graphics.charts.textlabels import Label

d = Drawing(200, 100)

# mark the origin of the label

d.add(Circle(100,90, 5, fillColor=colors.green))

lab = Label()

lab.setOrigin(100,90)

lab.boxAnchor = 'ne'

lab.angle = 45

lab.dx = 0

lab.dy = -20

lab.boxStrokeColor = colors.green

lab.setText('Some\nMulti-Line\nLabel')

d.add(lab)

draw(d, 'Label example')

disc("""

In the drawing above, the label is defined relative to the green blob.

The text box should have its north-east corner ten points down from

the origin, and be rotated by 45 degrees about that corner.

""")

disc("""

At present labels have the following properties, which we believe are

sufficient for all charts we have seen to date:

""")

disc("")

data=[["Property", "Meaning"],

      ["dx", """The label's x displacement."""],

      ["dy", """The label's y displacement."""],

      ["angle", """The angle of rotation (counterclockwise) applied to the label."""],

      ["boxAnchor", "The label's box anchor, one of 'n', 'e', 'w', 's', 'ne', 'nw', 'se', 'sw'."],

      ["textAnchor", """The place where to anchor the label's text, one of 'start', 'middle', 'end'."""],

      ["boxFillColor", """The fill color used in the label's box."""],

      ["boxStrokeColor", "The stroke color used in the label's box."],

      ["boxStrokeWidth", """The line width of the label's box."""],

      ["fontName", """The label's font name."""],

      ["fontSize", """The label's font size."""],

      ["leading", """The leading value of the label's text lines."""],

      ["x", """The X-coordinate of the reference point."""],

      ["y", """The Y-coordinate of the reference point."""],

      ["width", """The label's width."""],

      ["height", """The label's height."""]

      ]

t=Table(data, colWidths=(100,330))

t.setStyle(TableStyle([

            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),

            ('FONT',(0,1),(0,-1),'Courier',8,8),

            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),

            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),

            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),

            ('BOX', (0,0), (-1,-1), 0.25, colors.black),

            ]))

getStory().append(t)

caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Label properties""")

disc("""

To see many more examples of $Label$ objects with different

combinations of properties, please have a look into the

ReportLab test suite in the folder $tests$, run the

script $test_charts_textlabels.py$ and look at the PDF document

it generates!

""")

heading2("Axes")

disc("""

We identify two basic kinds of axes - <i>Value</i> and <i>Category</i>

ones.

Both come in horizontal and vertical flavors.

Both can be subclassed to make very specific kinds of axis.

For example, if you have complex rules for which dates to display

in a time series application, or want irregular scaling, you override

the axis and make a new one.

""")

disc("""

Axes are responsible for determining the mapping from data to image

coordinates; transforming points on request from the chart; drawing

themselves and their tickmarks, gridlines and axis labels.

""")

disc("""

This drawing shows two axes, one of each kind, which have been created

directly without reference to any chart:

""")

from reportlab.graphics import shapes

from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis

drawing = Drawing(400, 200)

data = [(10, 20, 30, 40), (15, 22, 37, 42)]

xAxis = XCategoryAxis()

xAxis.setPosition(75, 75, 300)

xAxis.configure(data)

xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']

xAxis.labels.boxAnchor = 'n'

xAxis.labels[3].dy = -15

xAxis.labels[3].angle = 30

xAxis.labels[3].fontName = 'Times-Bold'

yAxis = YValueAxis()

yAxis.setPosition(50, 50, 125)

yAxis.configure(data)

drawing.add(xAxis)

drawing.add(yAxis)

draw(drawing, 'Two isolated axes')

disc("Here is the code that created them: ")

eg("""

from reportlab.graphics import shapes

from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis

drawing = Drawing(400, 200)

data = [(10, 20, 30, 40), (15, 22, 37, 42)]

xAxis = XCategoryAxis()

xAxis.setPosition(75, 75, 300)

xAxis.configure(data)

xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']

xAxis.labels.boxAnchor = 'n'

xAxis.labels[3].dy = -15

xAxis.labels[3].angle = 30

xAxis.labels[3].fontName = 'Times-Bold'

yAxis = YValueAxis()

yAxis.setPosition(50, 50, 125)

yAxis.configure(data)

drawing.add(xAxis)

drawing.add(yAxis)

""")

disc("""

Remember that, usually, you won't have to create axes directly;

when using a standard chart, it comes with ready-made axes.

The methods are what the chart uses to configure it and take care

of the geometry.

However, we will talk through them in detail below.

The orthogonally dual axes to those we describe have essentially

the same properties, except for those refering to ticks.

""")

heading3("XCategoryAxis class")

disc("""

A Category Axis doesn't really have a scale; it just divides itself

into equal-sized buckets.

It is simpler than a value axis.

The chart (or programmer) sets its location with the method

$setPosition(x, y, length)$.

The next stage is to show it the data so that it can configure

itself.

This is easy for a category axis - it just counts the number of

data points in one of the data series. The $reversed$ attribute (if 1)

indicates that the categories should be reversed.

When the drawing is drawn, the axis can provide some help to the

chart with its $scale()$ method, which tells the chart where

a given category begins and ends on the page.

We have not yet seen any need to let people override the widths

or positions of categories.

""")

disc("An XCategoryAxis has the following editable properties:")

disc("")

data=[["Property", "Meaning"],

      ["visible", """Should the axis be drawn at all? Sometimes you don't want

to display one or both axes, but they still need to be there as

they manage the scaling of points."""],

      ["strokeColor", "Color of the axis"],

      ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.

Defaults to None"""],

      ["strokeWidth", "Width of axis in points"],

      ["tickUp", """How far above the axis should the tick marks protrude?

(Note that making this equal to chart height gives you a gridline)"""],

      ["tickDown", """How far below the axis should the tick mark protrude?"""],

      ["categoryNames", """Either None, or a list of strings. This should have the

same length as each data series."""],

      ["labels", """A collection of labels for the tick marks. By default the 'north'

of each text label (i.e top centre) is positioned 5 points down

from the centre of each category on the axis. You may redefine

any property of the whole label group or of any one label. If

categoryNames=None, no labels are drawn."""],

      ["title", """Not Implemented Yet. This needs to be like a label, but also

lets you set the text directly. It would have a default

location below the axis."""]]

t=Table(data, colWidths=(100,330))

t.setStyle(TableStyle([

            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),

            ('FONT',(0,1),(0,-1),'Courier',8,8),

            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),

            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),

            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),

            ('BOX', (0,0), (-1,-1), 0.25, colors.black),

            ]))

getStory().append(t)

caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - XCategoryAxis properties""")

heading3("YValueAxis")

disc("""

The left axis in the diagram is a YValueAxis.

A Value Axis differs from a Category Axis in that each point along

its length corresponds to a y value in chart space.

It is the job of the axis to configure itself, and to convert Y values

from chart space to points on demand to assist the parent chart in

plotting.

""")

disc("""

$setPosition(x, y, length)$ and $configure(data)$ work exactly as

for a category axis.

If you have not fully specified the maximum, minimum and tick

interval, then $configure()$ results in the axis choosing suitable

values.

Once configured, the value axis can convert y data values to drawing

space with the $scale()$ method.

Thus:

""")

eg("""

>>> yAxis = YValueAxis()

>>> yAxis.setPosition(50, 50, 125)

>>> data = [(10, 20, 30, 40),(15, 22, 37, 42)]

>>> yAxis.configure(data)

>>> yAxis.scale(10)  # should be bottom of chart

50.0

>>> yAxis.scale(40)  # should be near the top

167.1875

>>>

""")

disc("""By default, the highest data point is aligned with the top of the

       axis, the lowest with the bottom of the axis, and the axis choose

       'nice round numbers' for its tickmark points. You may override these

       settings with the properties below. """)

disc("")

data=[["Property", "Meaning"],

      ["visible", """Should the axis be drawn at all? Sometimes you don't want

to display one or both axes, but they still need to be there as

they manage the scaling of points."""],

      ["strokeColor", "Color of the axis"],

      ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.

Defaults to None"""],

      ["strokeWidth", "Width of axis in points"],

      ["tickLeft", """How far to the left of the axis should the tick marks protrude?

(Note that making this equal to chart height gives you a gridline)"""],

      ["tickRight", """How far to the right of the axis should the tick mark protrude?"""],

      ["valueMin", """The y value to which the bottom of the axis should correspond.

Default value is None in which case the axis sets it to the lowest

actual data point (e.g. 10 in the example above). It is common to set

this to zero to avoid misleading the eye."""],

      ["valueMax", """The y value to which the top of the axis should correspond.

Default value is None in which case the axis sets it to the highest

actual data point (e.g. 42 in the example above). It is common to set

this to a 'round number' so data bars do not quite reach the top."""],

      ["valueStep", """The y change between tick intervals. By default this is

None, and the chart tries to pick 'nice round numbers' which are

just wider than the minimumTickSpacing below."""],

      ["valueSteps", """A list of numbers at which to place ticks."""],

      ["minimumTickSpacing", """This is used when valueStep is set to None, and ignored

otherwise. The designer specified that tick marks should be no

closer than X points apart (based, presumably, on considerations

of the label font size and angle). The chart tries values of the

type 1,2,5,10,20,50,100... (going down below 1 if necessary) until

it finds an interval which is greater than the desired spacing, and

uses this for the step."""],

      ["labelTextFormat", """This determines what goes in the labels. Unlike a category

axis which accepts fixed strings, the labels on a ValueAxis are

supposed to be numbers. You may provide either a 'format string'

like '%0.2f' (show two decimal places), or an arbitrary function

which accepts a number and returns a string. One use for the

latter is to convert a timestamp to a readable year-month-day

format."""],

      ["title", """Not Implemented Yet. This needs to be like a label, but also

lets you set the text directly. It would have a default

location below the axis."""]]

t=Table(data, colWidths=(100,330))

t.setStyle(TableStyle([

            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),

            ('FONT',(0,1),(0,-1),'Courier',8,8),

            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),

            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),

            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),

            ('BOX', (0,0), (-1,-1), 0.25, colors.black),

            ]))

getStory().append(t)

caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - YValueAxis properties""")

disc("""

The $valueSteps$ property lets you explicitly specify the

tick mark locations, so you don't have to follow regular intervals.

Hence, you can plot month ends and month end dates with a couple of

helper functions, and without needing special time series chart

classes.

The following code show how to create a simple $XValueAxis$ with special

tick intervals. Make sure to set the $valueSteps$ attribute before calling

the configure method!

""")

eg("""

from reportlab.graphics.shapes import Drawing

from reportlab.graphics.charts.axes import XValueAxis

drawing = Drawing(400, 100)

data = [(10, 20, 30, 40)]

xAxis = XValueAxis()

xAxis.setPosition(75, 50, 300)

xAxis.valueSteps = [10, 15, 20, 30, 35, 40]

xAxis.configure(data)

xAxis.labels.boxAnchor = 'n'

drawing.add(xAxis)

""")

from reportlab.graphics import shapes

from reportlab.graphics.charts.axes import XValueAxis

drawing = Drawing(400, 100)