Tutorial

Using pycha is quite simple. You always follow the same 5 simple steps:

1. Create a Cairo surface to draw the chart on
2. Build a list of data sets from which your chart will be created
3. Customize the chart options.
4. Create the chart, add the datasets and render it
5. Save the results into a file or do whatever you want with the Cairo surface

To create the Cairo surface you just need to say the type of surface and its dimensions:

import cairo
width, height = (500, 400)
surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, width, height)

Then you should create your data set querying a database or any other data source:

dataSet = (
  ('dataSet 1', ((0, 1), (1, 3), (2, 2.5))),
  ('dataSet 2', ((0, 2), (1, 4), (2, 3))),
  ('dataSet 3', ((0, 5), (1, 1), (2, 0.5))),
)

As you can see, each data set is a tuple where the first element is the name of the data set and the second is another tuple composed by points. Each point is a two-elements tuple, the first one is the x value and the second the y value.

Not every chart uses all the information of a data set. For example, the Pie chart only uses the first point of each dataset and it only uses the y value of the point.

Now you may want to specify some options so the chart can be customize changing its defaults values. To see the defaults you can check the pycha.chart.Chart.__init__ method in the source code. You can use regular dictionaries to define your options. For example, imagine you want to hide the legend and use a different color for the background:

options = {
    'legend': {'hide': True},
    'background': {'color': '#f0f0f0'},
}

Now we are ready to instantiate the chart, add the data set and render it:

import pycha.bar
chart = pycha.bar.VerticalBarChart(surface, options)
chart.addDataset(dataSet)
chart.render()

Right now you can choose among several different kind of charts:

• Pie Charts (pycha.pie.PieChart)
• Bar Charts (pycha.bar.VerticalBarChart and pycha.bar.HorizontalBarChart)
• Line Charts (pycha.bar.LineChart)
• Scatterplot Charts (pycha.scatter.ScatterplotChart)
• Stacked Bar Charts (pycha.stackedbar.StackedVerticalBarChart and pycha.stackedbar.StackedHorizontalBarChart)

Finally you can write the surface to a graphic file or anything you want using the cairo library:

surface.write_to_png('output.png')

That’s it!