Squid

Squid helps you write Ruby code to draw graphs in PDF files.

The source code is available on GitHub and the documentation on RubyDoc.

Build Status Coverage Status Dependency Status Code Climate Online docs Gem Version

Prawn is a great Ruby library to generate PDF files but lacks high-level components to draw graphs.

Squid adds a single method chart(data = {}, options = {}) to Prawn.

Provide the data to plot as a hash, with each key/value representing a series.

For instance, the following code generates the graph below:

data = {views: {2013 => 182, 2014 => 46, 2015 => 134}}
chart data

01-basic

Graph options

By providing options to the chart method, you can customize the format of the graph.

Multiple options can be combined. Here is a comprehensive list.

:type sets the type of graph. Can be :column (default), :point, or :line.

02-type-point

:line_widths changes the line width (default: [3], only applies to line graphs).

03-type-line

:colors changes the colors of the chart (default: %w(2e578c 5d9648 e7a13d bc2d30 6f3d79 7d807f)).

04-colors

:steps changes the number of gridlines (default: 4).

05-gridlines

:ticks shows/hides the ticks between the baseline and each category (default: true).

06-ticks

:baseline shows/hides the baseline (default: true).

07-baseline

:every specifies how often to show category labels on the baseline (default: 1).

08-every

:legend shows/hides the legend (default: true).

09-legend

:legend can also set the distance of the legend from the right margin (default: {offset: 0}).

10-legend-offset

:format changes the format of the label values. Can be :integer (default), :float, :percentage, :currency, or :seconds.

11-format

:labels shows/hides the value for each point in the graph (default: false).

12-labels

:border shows/hides a border around the graph (default: false).

13-border

:height changes the height of the graph (default: 250).

14-height

Multiple series

By providing multiple key/values data to the chart method, you can plot multiple series on a graph.

For instance, the following code generates the graph below:

data = {safari:  {2013 => 43.2, 2014 => 46.1, 2015 => 50.7},
       firefox:  {2013 => 56.8, 2014 => 53.9, 2015 => 49.3}}
chart data, labels: true, format: :percentage

15-multiple-columns

When plotting multiple series, the option type: :stack can be set to display stacked columns:

16-multiple-stacks

Finally, the option type: :two_axis can be set to display two separate axes in your series belong to two different domains.

For instance, the following code generates the graph below:

data = {views: {2013 => 182, 2014 => 46, 2015 => 88},
     earnings: {2013 => 104_323, 2014 => 27_234, 2015 => 14_123}}
chart data, type: :two_axis

17-two-axis

How to install

Squid requires Ruby 2.1 or higher. If used in a Rails project, requires Rails 4.0 or higher.

To include in your project, add gem 'squid', github: 'fullscreen/squid' to the Gemfile file of your Ruby project.

How to generate the manual

rake manual

How to contribute

If you’ve made it this far in the README… thanks! :v:

I’m still in the process of extracting Squid from a private project, so I’m probably adding new features to the chart method as you are reading.

Feel free to try it out and send issues or pull requests regarding what Squid includes so far.

All pull requests will have to make Travis and Code Climate happy in order to be accepted. :kissing_smiling_eyes: You can also run the tests locally with bundle exec rspec. Happy hacking!