Thoughts on how the API should work

[Rodrigo Araújo]

Hello everyone,

I guess most of you have realized by now that our plotting functions have grown excessively. We have examples with function calls that got extended for three lines!

I've been thinking about the pythonic way to create charts and, after checking out how our "competitors" do it [1][2], I came up with this:

OBJECTIVE

These should be some of our new default colors because the ones we have today are really bad. Also, I'm using a custom open source font [3] which might be changed in the future.

The green and blue lines are there to display the image bounds and the plotting area after deducing the padding values.

CODE

#initiating the data

a_series = series.Series('Series A', [10, 20, 30])

b_Series = series.Series('Series B', [20, 20, 40])

data = [a_series, b_series)

#creating the chart

bar_chart = cairoplot.VerticalBarPlot(data, 600, 400)

#padding equal to 30 pixels | Default = 10 or 20 or 30

#it means 30px will be deduced from each side of the image

bar_chart.padding = 30

#displaying main axis variables | Default = (True, True)

#option 1

bar_chart.axis = (True, True)

#option 2

bar_chart.x_axis = True

bar_chart.y_axis = True

#displaying label lines | Default = True if vertical labels are provided

#it should be impossible to display vertical lines

bar_chart.label_lines = True

#displaying legend | Default = Right

#available options should include left, bottom, right and box

bar_chart.legend = 'right'

#defining labels | Default = no labels

#In the future, we might add support for multiple levels of labels

#option 1

bar_chart.labels = (('Group A', 'Group B'), ('Small', 'Medium', 'Big', 'Huge'))

#option 2

bar_chart.x_labels = ('Group A', 'Group B')

bar_chart.y_labels = ('Small', 'Medium', 'Big', 'Huge')

#defining focus on B Series | Default = no focus

#focused series have double the width of the other ones

bar_chart.focus = (False,True)

#setting the title | Default = no title

bar_chart.title = 'Horizontal Bar Plot Test'

#saving the chart

bar_chart.save('horizontal_example.png')

HIDING DEFAULT CALLS AND COMMENTS

a_series = series.Series('Series A', [10, 20, 30])

b_Series = series.Series('Series B', [20, 20, 40])

data = [a_series, b_series)

bar_chart = cairoplot.VerticalBarPlot(data, 600, 400)

bar_chart.padding = 30

bar_chart.labels = (('Group A', 'Group B'), ('Small', 'Medium', 'Big', 'Huge'))

bar_chart.focus = (False,True)

bar_chart.title = 'Horizontal Bar Plot Test'

bar_chart.save('horizontal_example.png')

What do you guys think? Too much? Most of those have smart default values, so the user would omit them as I have.

Best regards,

[1] https://github.com/gak/pygooglechart/blob/master/examples/bar.py

[2] http://matplotlib.sourceforge.net/examples/api/barchart_demo.html

[3] http://www.theleagueofmoveabletype.com/league-gothic

P.S.: I haven't stopped the series refactoring, just wanted to throw these thoughts for everyone to criticize.

--
Rodrigo Araújo