CairoPlot is an API written in Python and uses PyCairo to plot 8 kinds of graphics: horizontal and vertical bars, scatter, dots and lines and functions plots. Pie and donut plots and Gantt Charts.

It was born on an attempt to plot graphics in a more beautiful way, making it possible to use them on presentations, websites and papers.

The project is now 2 years old and many have helped through e-mails, bugs and code. Special thanks to João S. O. Bueno, Magnun Leno, Mike Rooney, Chris Ward, Karel Kolman, Victor Westman and Tim Swast.

To see what CairoPlot is capable of, visit the Gallery but if you want to see what's new on version 1.2, check the what's new session. Also, you can use the menu on the left to navigate through all the tutorials available on the site.

installation

Installation tutorials cover the files needed to install and use CairoPlot on each of the three Operational Systems available today.

data handling

Explanations on how to input data to CairoPlot.

basic use

Basic use tutorials explain how to input data to create each one of the graphics available on CairoPlot.

CairoPlot is an API written in Python and uses PyCairo to plot 8 kinds of graphics: horizontal and vertical bars, scatter, dots and lines and functions plots. Pie and donut plots and Gantt Charts.

To install CairoPlot on Ubuntu the following packages must be downloaded:

• python2.5

sudo apt-get install python2.5

• cairo

sudo apt-get install libcairo

• pycairo

sudo apt-get install pycairo

After that, CairoPlot package must be downloaded and installed

• through launchpad

sudo apt-get install bzr

bzr co lp:cairoplot

python setup.py

• through the download section

python setup.py

To install CairoPlot on Windows the following packages must be downloaded:

• python2.5
• cairo
• pycairo

After that, CairoPlot package must be downloaded and installed

• through the download section

python setup.py

Coming soon

Data objects are used to hold any primitive data along with its name.

• Numbers

integers, floats or long values.

• Points

represented as 2 (x,y) or 3 (x,y,z) items tuples;

if a user inputs a list, it's automaticaly converted to a tuple.

Examples

                d = Data(name='empty')
                print d #prints empty: ()
            

                d = Data((1,1),'point a')
                print d #prints point a: (1, 1)
            

                d = Data((1,2,3),'point b')
                print d #prints point b: (1, 2, 3)
            

                d = Data([2,3],'point c')
                print d #point c: (2, 3)
            

                d = Data(12, 'simple value')
                print d #prints simple value: 12
            

Groups are used to hold data objects, defining indepedent series of values.

Users might fill a group object in a variety of ways:

• Numbers or points

Saved as a new data object.

• List or tuple of numbers or points

Each number is converted to a data object and added to a new list, which will be held on the group.

• Two or three lists of coordinates

Sometimes, it's easier to just input all coordinates as series not as points. The group object zips them and saves them as points.

• Data object or a data objects list

Both saved directly on the group.

Examples

                g = Group(13, 'simple number') 
                print g
                #prints simple number ['13']
            

                g = Group((1,2), 'simple point')
                print g
                #prints simple point ['(1, 2)']
            

                g = Group([1,2,3,4], 'list of numbers'
                print g
                #prints list of numbers ['1', '2', '3', '4']
            

                g = Group((1,2,3,4),'tuple of numbers')
                print g
                #prints tuple of numbers ['1', '2', '3', '4']
            

                g = Group([(1,2),(2,3),(3,4)], 'list of points')
                print g
                #prints list of points ['(1, 2)', '(2, 3)', '(3, 4)']
            

                g = Group([[1,2,3],[1,2,3]], '2D coordinate lists')
                print g
                #prints 2D coordinated lists ['(1, 1)', '(2, 2)', '(3, 3)']
            

                g = Group([[1,2],[1,2],[1,2]], '3D coordinate lists')
                print g
                #prints 3D coordinated lists ['(1, 1, 1)', '(2, 2, 2)']
            

Used to model groups of groups, so it's possible to define and plot more than one series on the same graphic.

Users might fill a series object in a variety of ways:

• Numbers or points

Saved as a new group containing a new data object.

• Lists or tuples of numbers or points

Each is converted into a new group.

• Lists of two or three lists of coordinates

Converted into new groups.

• Data object or a data objects list

Both converted into new groups.

• Dictionaries

Each of the elements will be converted into groups and, if the keys are strings, they'll be used as group names.

• Group object or a group objects list

Converted into a new series object.

Examples

                print Series([1,2,3,4])
                #prints ["Group 1 ['1', '2', '3', '4']"]
            

                print Series([[1,2,3],[4,5,6]])
                #prints ["Group 1 ['1', '2', '3']", "Group 2 ['4', '5', '6']"]
            

                print Series((1,2))
                #prints ["Group 1 ['(1, 2)']"]
            

                print Series([(1,2),(2,3)])
                #prints ["Group 1 ['(1, 2)', '(2, 3)']"]
            

                print Series([[(1,2),(2,3)],[(4,5),(5,6)]])
                #prints ["Group 1 ['(1, 2)', '(2, 3)']", "Group 2 ['(4, 5)', '(5, 6)']"]
            

                print Series([[[1,2,3],[1,2,3],[1,2,3]]])
                #prints ["Group 1 ['(1, 1, 1)', '(2, 2, 2)', '(3, 3, 3)']"]
            

                print Series({'g1':[1,2,3], 'g2':[4,5,6]})
                #prints ["g1 ['1', '2', '3']", "g2 ['4', '5', '6']"]
            

                print Series({'g1':[(1,2),(2,3)], 'g2':[(4,5),(5,6)]})
                #prints ["g1 ['(1, 2)', '(2, 3)']", "g2 ['(4, 5)', '(5, 6)']"]
            

                print Series({'g1':[[1,2],[1,2]], 'g2':[[4,5],[4,5]]})
                #prints ["g1 ['(1, 1)', '(2, 2)']", "g2 ['(4, 4)', '(5, 5)']"]
            

                print Series(Data(1,'d1'))
                #prints ["Group 1 ['d1: 1']"]
            

                print Series(Group([(1,2),(2,3)],'g1'))
                #prints ["g1 ['(1, 2)', '(2, 3)']"]
            

All graphics in CairoPlot might be generated using one of two ways: defining an object or calling a function.

                #Defining a new object
                data = [[1,2,3],[4,5,6],[7,8,9]]
                test = cairoplot.HorizontalBarPlot("object_way.svg", data, 640, 480)
                test.render()
                test.commit()
    
                #Calling a function
                data = [[1,2,3],[4,5,6],[7,8,9]]
                test = cairoplot.horizontal_bar_plot("function_way.svg", data, 640, 480)
            

The arguments of the functions are, exactly, the same as the ones from the classes' __init__ methods, and that's why only the former will be detailed on the next sections. But, as all classes inherit data from the Plot class, many of these arguments would be repeated if explained on each class, that's why they are detailed below.

surface

Default value: None

A filename or a Cairo surface. For filenames, CairoPlot supports svg, png, pdf and ps extensions.

Examples: "test.svg", "test.png", "test.pdf", "test.ps"

data

Default value: None

A series, group or data object is expected. But, as of version 1.2, some classes also accept lists/dictionaries of numbers and lists/dictionaries of lists of numbers.

Examples will be given on each section.

width

Default value: 640

Output file width.

height

Default value: 480

Output file height.

background

Default value: "white light_gray"

Tuple (green,blue,blue,alpha) or color name (available names are explained on the color section);

Linear gradient defined by a string containing two or more color names separated by spaces (see default value);

Cairo Linear/Radial Gradient object.

Examples: (1,0,0), (0,1,0), "green", "white", "green blue gray", "black white"

border

Default value: 0

Size in pixels of the space between the border of the image and the plotting area.

grid

Default value: False

Whether or not a grid should be displayed.

x_labels

Default value: None

A list containing labels for the x axis.

Example: ["x_label_one", "x_label_two", "x_label_three"]

y_labels

Default value: None

A list containing labels for the y axis.

Example: ["y_label_one", "y_label_two", "y_label_three"]

x_bounds

Default value: None

A 2-tuple containing the lowest and highest bounds for the x axis.

y_bounds

Default value: None

A 2-tuple containing the lowest and highest bounds for the y axis.

overview

Horizontal Bar Plots might be created using the HorizontalBarPlot class or the function horizontal_bar_plot. The function takes the same parameters as the class's __init__ method, described below.

data

Default value: None

A series, group or data object is expected. But, as of version 1.2, lists/dictionaries of numbers and lists/dictionaries of lists of numbers are also accepted.

display_values

Default value: False

Whether or not the values of each bar should be displayed on their right.

rounded_corners

Default value: False

Whether or not the bars' corners should be rounded.

stack

Default value: False

Whether groups should be drawn as separated or stacked bars.

three_dimension

Default value: False

Whether bars should be drawn in pseudo-3D style.

series_labels

Default value: None

A list containing labels for each bar of a group.

series_colors

Default value: None

A list of color values for each bar in a group.

examples

                    data = [[1,2,3],[4,5,6],[7,8,9]]
                    test = cairoplot.horizontal_bar_plot("function_way.svg", data, 640, 480)
                

                    data = [[1,2,3],[4,5,6],[7,8,9]]
                    test = cairoplot.horizontal_bar_plot("function_way.svg", data, 640, 480)
                

overview

Vertical Bar Plots might be created using the VerticalBarPlot class or the function vertical_bar_plot. The function takes the same parameters as the class's __init__ method, described below.

data

Default value: None

A series, group or data object is expected. But, as of version 1.2, lists/dictionaries of numbers and lists/dictionaries of lists of numbers are also accepted.

display_values

Default value: False

Whether or not the values of each bar should be displayed on their right.

rounded_corners

Default value: False

Whether or not the bars' corners should be rounded.

stack

Default value: False

Whether groups should be drawn as separated or stacked bars.

three_dimension

Default value: False

Whether bars should be drawn in pseudo-3D style.

series_labels

Default value: None

A list containing labels for each bar of a group.

series_colors

Default value: None

A list of color values for each bar in a group.

examples

                    data = [[1,2,3],[4,5,6],[7,8,9]]
                    test = cairoplot.horizontal_bar_plot("function_way.svg", data, 640, 480)
                

                    data = [[1,2,3],[4,5,6],[7,8,9]]
                    test = cairoplot.horizontal_bar_plot("function_way.svg", data, 640, 480)
                

overview

Donut graphics are useful to show the participation of different objects on the whole. As the other graphics, it's possible to create it by instantianting a DonutPlot object or by calling the donut_plot function. Below are the arguments for the __init__ method of the class, which are the same as the function's.

data

Default value: None

A data, group or series object. As of version 1.2, a dictionary mapping strings to numbers is also accepted.

gradient

Default value: False

Whether to use solid or gradient colors.

Scheduled to be removed on version 2.0 due to the acceptance of gradient information on the colors list.

shadow

Default value: False

Whether or not a shadow will be drawn.

colors

Default value: None

A list of color values as explained on Colors section.

inner_radius

Default value: a third of the main radius

The the hole radius.

examples

overview

Introduction.

data

Default value: None

A data, group or series object. As of version 1.2, a list of numbers, or a list/dictionary of lists of numbers is also accepted.

axis

Default value: False

Whether the x and y axis should be drawn.

dash

Default value: False

A list of booleans defining whether or not the respective group lines should be dashed.

dots

Default value: False

Whether or not circles must be drawn on every point provided.

series_legend

Default value: False

True displays an white box on the upper right corner containing a color legend.

x_title

Default value: None

A title for the x axis.

y_title

Default value: None

A title for the y axis.

series_colors

Default value: False

A list of color values as explained on the Colors section containing one color for each group on the data.

examples

overview

Introduction.

data

Default value: None

A data, group or series object. As of version 1.2, a function or a list/dictionary of functions is also accepted.

axis

Default value: False

Whether the x and y axis should be drawn.

discrete

Default value: False

Whether the points should be connected or not.

dots

Default value: False

Whether or not circles must be drawn on every point provided.

series_legend

Default value: False

True displays an white box on the upper right corner containing a color legend.

x_title

Default value: None

A title for the x axis.

y_title

Default value: None

A title for the y axis.

series_colors

Default value: False

A list of color values as explained on the Colors section containing one color for each group on the data.

step

Default value: 1

The increment value used to generate values from the lower x_bound to the upper x_bound.

Scheduled to be removed on version 2.0 due to the Series module.

examples

overview

Introduction.

data

Default value: None

A data, group or series object. As of version 1.2, a list of 2D/3D points, a list/dictionary of 2D/3D points or a list of 2D/3D coordinates also accepted.

error_x

Default value: None

One or two list (if errors are simetric or not) containing error values to be drawn as horizontal error bars on each point.

error_y

Default value: None

One or two list (if errors are simetric or not) containing error values to be drawn as vertical error bars on each point.

axis

Default value: False

Whether the x and y axis should be drawn.

dash

Default value: False

A list of booleans defining whether or not the respective group lines should be dashed.

discrete

Default value: False

Whether the points should be connected or not.

dots

Default value: False

Whether or not circles must be drawn on every point provided.

series_legend

Default value: False

True displays an white box on the upper right corner containing a color legend.

z_bounds

Default value: None

For Scatter Plots, the z coordinate is drawn as the radius and color (see circle_colors) of each point. The z_bounds parameter defines the lower and higher values for the points' radius.

x_title

Default value: None

A title for the x axis.

y_title

Default value: None

A title for the y axis.

series_colors

Default value: False

A list of color values as explained on the Colors section containing one color for each group on the data.

circle_colors

Default value: None

A tuple of two colors, defining the colors associated to the z_bounds.

examples

overview

Introduction.

data

Default value: None

A data, group or series object. As of version 1.2, a list of tuples containing starting and ending values for the bars is also accepted.

colors

Default value: None

A list of color values as explained on the Colors section containing one color for each group on the data.

examples

overview

Pie graphics are useful to show the participation of different objects on the whole. CairoPlot provides two ways of creating one: instantianting a PiePlot object or calling the pie_plot function. The arguments for the class' __init__ method are the same as the function's and are detailed below.

data

Default value: None

A data, group or series object. As of version 1.2, a dictionary mapping strings to numbers is also accepted.

gradient

Default value: False

Whether to use solid or gradient colors.

Scheduled to be removed on version 2.0 due to the acceptance of gradient information on the colors list.

shadow

Default value: False

Whether or not a shadow will be drawn.

colors

Default value: None

A list of color values as explained on Colors section.

examples