Python to generate nice looking SVG graph http://pygal.org/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

624 lines
12 KiB

===============
Documentation
===============
Basic customizations
====================
.. contents::
How to customize:
-----------------
pygal is customized with the help of the `Config` class (see `config.py <https://github.com/Kozea/pygal/blob/master/pygal/config.py>`_). It can be changed in several ways:
.. pygal::
from pygal import Config
config = Config()
config.show_legend = False
config.human_readable = True
config.fill = True
config.x_scale = config.y_scale = 0.25
chart = pygal.XY(config)
from math import cos, sin, pi
a = 2 * pi / 5.
chart.add('*', [(cos(i*a+pi/2.), sin(i*a+pi/2.)) for i in (0,2,4,1,3,0)])
By instanciating it
~~~~~~~~~~~~~~~~~~~
Just import the `Config` class and instanciate it:
.. code-block::
from pygal import Config
config = Config()
config.show_legend = False
config.human_readable = True
config.fill = True
config.x_scale = .25
config.y_scale = .25
chart = pygal.XY(config)
...
By inheriting it
~~~~~~~~~~~~~~~~
Import the `Config` class and override it:
.. code-block::
from pygal import Config
class StarConfig(Config):
show_legend = False
human_readable = True
fill = True
x_scale = .25
y_scale = .25
chart = pygal.XY(StarConfig())
...
Using keyword args
~~~~~~~~~~~~~~~~~~
As a shorthand for a one shot config, you can specify all config arguments as keyword args:
.. code-block::
chart = pygal.XY(show_legend=False, human_readable=True, fill=True, x_scale=.25, y_scale=.25)
...
Size
----
``width, height, explicit_size``
The simplest and usefull customizations is the svg size to render.
It indicates the desired size of the svg.
.. pygal-code:: 200 100
chart = pygal.Bar(width=200, height=100)
chart.add('1', 1)
chart.add('2', 2)
You can also set `explicit_size` to True to add size attributes to the svg tag.
Spacing
-------
``spacing, margin``
Spacing determines the space between all elements:
.. pygal-code::
chart = pygal.Bar(spacing=50)
chart.x_labels = u'αβγδ'
chart.add('line 1', [5, 15, 10, 8])
chart.add('line 2', [15, 20, 8, 11])
Margin is the external chart margin:
.. pygal-code::
chart = pygal.Bar(margin=50)
chart.x_labels = u'αβγδ'
chart.add('line 1', [5, 15, 10, 8])
chart.add('line 2', [15, 20, 8, 11])
Scaling
-------
``include_x_axis``
Scales are computed automaticaly between the min and the max values.
You may want to always have the absissa in your graph:
.. pygal-code::
chart = pygal.Line(include_x_axis=True)
chart.add('line', [.0002, .0005, .00035])
``range``
You may also want to explicitly set a range, `range` takes a tuple containing min and max:
.. pygal-code::
chart = pygal.Line(range=(.0001, .001))
chart.add('line', [.0002, .0005, .00035])
``order_min``
Finaly you can tell at which precision pygal should stop scaling (in log10):
.. pygal-code::
chart = pygal.Line(order_min=-4)
chart.add('line', [.0002, .0005, .00035])
Titles
------
Chart title
~~~~~~~~~~~
``title``
You can add a title to the chart by setting the `title` option:
.. pygal-code::
chart = pygal.Line(title=u'Some points')
chart.add('line', [.0002, .0005, .00035])
X title
~~~~~~~
``x_title``
You can add a title to the x axis by setting the `x_title` option:
.. pygal-code::
chart = pygal.Line(title=u'Some points', x_title='X Axis')
chart.add('line', [.0002, .0005, .00035])
Y title
~~~~~~~
``y_title``
You can add a title to the y axis by setting the `y_title` option:
.. pygal-code::
chart = pygal.Line(title=u'Some points', y_title='Y Axis')
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``title_font_size``
.. pygal-code::
chart = pygal.Line(title=u'Some points', x_title='X Axis', y_title='Y Axis',
title_font_size=24)
chart.add('line', [.0002, .0005, .00035])
Labels
------
Add labels
~~~~~~~~~~
``x_labels, y_labels``
You can specify x labels and y labels, depending on the graph type:
.. pygal-code::
chart = pygal.Line()
chart.x_labels = 'Red', 'Blue', 'Green'
chart.y_labels = .0001, .0003, .0004, .00045, .0005
chart.add('line', [.0002, .0005, .00035])
Remove y labels
~~~~~~~~~~~~~~~
``show_y_labels``
Set this to False to deactivate y labels:
.. pygal-code::
chart = pygal.Line(show_y_labels=False)
chart.add('line', [.0002, .0005, .00035])
Rotate labels
~~~~~~~~~~~~~
``x_label_rotation, y_label_rotation``
Allow label rotation (in degrees) to avoid axis cluttering:
.. pygal-code::
chart = pygal.Line()
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(x_label_rotation=20)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
Change minor/major labels
~~~~~~~~~~~~~~~~~~~~~~~~~
``x_labels_major, x_labels_major_every, x_labels_major_count, show_minor_x_labels, y_labels_major, y_labels_major_every, y_labels_major_count, show_minor_y_labels``
You can alter major minor behaviour of axes thanks to `Arjen Stolk <https://github.com/simplyarjen>`_
.. pygal-code::
chart = pygal.Line(x_label_rotation=20)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(x_label_rotation=20, x_labels_major_every=3)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(x_label_rotation=20, x_labels_major_count=3)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(x_label_rotation=20, show_minor_x_labels=False)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(y_label_rotation=-20)
chart.y_labels_major = []
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line()
chart.y_labels_major = [.0001, .0004]
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(y_label_rotation=20, y_labels_major_every=3)
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(y_labels_major_count=3)
chart.add('line', [0, .0002, .0005, .00035])
.. pygal-code::
chart = pygal.Line(y_labels_major_every=2, show_minor_y_labels=False)
chart.add('line', [0, .0002, .0005, .00035])
Font size
~~~~~~~~~
``label_font_size, major_label_font_size``
.. pygal-code::
chart = pygal.Line(x_label_rotation=20, label_font_size=8, major_label_font_size=12)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.x_labels_major = ['This is the first point !', 'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
Dots
----
Removing
~~~~~~~~
``show_dots``
You can remove dots by setting `show_dots` at `False`
.. pygal-code::
chart = pygal.Line(show_dots=False)
chart.add('line', [.0002, .0005, .00035])
``show_only_major_dots``
You can remove minor x-labelled dots by setting `show_only_major_dots` at `True`
.. pygal-code::
chart = pygal.Line(show_only_major_dots=True)
chart.add('line', range(12))
chart.x_labels = map(str, range(12))
chart.x_labels_major = ['2', '4', '8', '11']
Size
~~~~
``dots_size``
.. pygal-code::
chart = pygal.Line(dots_size=5)
chart.add('line', [.0002, .0005, .00035])
Legends
-------
Removing
~~~~~~~~
``show_legend``
You can remove legend by setting these at `False`
.. pygal-code::
chart = pygal.Line(show_legend=False)
chart.add('line', [.0002, .0005, .00035])
Legend at bottom
~~~~~~~~~~~~~~~~
``legend_at_bottom``
You can put legend at bottom by setting `legend_at_bottom` at True:
.. pygal-code::
chart = pygal.Line(legend_at_bottom=True)
chart.add('line', [.0002, .0005, .00035])
Legend box size
~~~~~~~~~~~~~~~
``legend_box_size``
.. pygal-code::
chart = pygal.Line(legend_box_size=18)
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``legend_font_size``
.. pygal-code::
chart = pygal.Line(legend_font_size=20)
chart.add('line', [.0002, .0005, .00035])
Tooltip
-------
Rounded corner
~~~~~~~~~~~~~~
``tooltip_border_radius``
.. pygal-code::
chart = pygal.Line(tooltip_border_radius=10)
chart.add('line', [.0002, .0005, .00035])
Font size
~~~~~~~~~
``tooltip_font_size``
.. pygal-code::
chart = pygal.Line(tooltip_font_size=24)
chart.add('line', [.0002, .0005, .00035])
Precision
~~~~~~~~~
``value_formatter``
You can specifiy how the values are displayed on the tooltip using a lambda function.
The code below shows the values to 2 decimal places.
.. pygal-code::
chart = pygal.Line(range=(0, 5))
chart.add('line', [.070106781, 1.414213562, 3.141592654])
chart.value_formatter = lambda x: "%.2f" % x
The datey graph shows the tooltip as "x=? y=?", where the x format is the same as the x_label_format, and the y format is specified via the value_formatter.
Two y axes
----------
``secondary``
You can plot your values to 2 separate axes, thanks to `wiktorn <https://github.com/wiktorn>`_
.. pygal-code::
chart = pygal.Line(title=u'Some different points')
chart.add('line', [.0002, .0005, .00035])
chart.add('other line', [1000, 2000, 7000], secondary=True)
Rendering
---------
``fill, stroke, zero``
You can disable line stroking:
.. pygal-code::
chart = pygal.Line(stroke=False)
chart.add('line', [.0002, .0005, .00035])
And enable line filling:
.. pygal-code::
chart = pygal.Line(fill=True)
chart.add('line', [.0002, .0005, .00035])
To fill to an other reference than zero:
.. pygal-code::
chart = pygal.Line(fill=True, zero=.0004)
chart.add('line', [.0002, .0005, .00035])
Font sizes
----------
``value_font_size, tooltip_font_size``
Set the various font size
.. pygal-code::
chart = pygal.Line(label_font_size=34, legend_font_size=8)
chart.add('line', [0, .0002, .0005, .00035])
Text truncation
---------------
``truncate_legend, truncate_label``
By default long text are automatically truncated at reasonable length which fit in the graph.
You can override that by setting truncation lenght with `truncate_legend` and `truncate_label`.
.. pygal-code::
chart = pygal.Line(truncate_legend=3, truncate_label=17)
chart.x_labels = [
'This is the first point !',
'This is the second point !',
'This is the third point !',
'This is the fourth point !']
chart.add('line', [0, .0002, .0005, .00035])
Human readable
--------------
``human_readable``
Display values in human readable form:
1 230 000 -> 1.23M
.00 098 7 -> 987µ
.. pygal-code::
chart = pygal.Line(human_readable=True, y_scale=.0001)
chart.add('line', [0, .0002, .0005, .00035])
No data text
------------
``no_data_text``
Text to display instead of the graph when no data is supplied:
.. pygal-code::
chart = pygal.Line()
chart.add('line', [])
.. pygal-code::
chart = pygal.Line(no_data_text='No result found')
chart.add('line', [])
Next: `Interpolations </interpolations>`_