TTY:Pie

Draw pie charts in your terminal window

TTY::Pie provides pie chart drawing component for TTY toolkit.

Pie chart drawing

Installation

Add this line to your application's Gemfile:

gem 'tty-pie'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-pie

1. Usage
2. Interface
- 2.1 data
- 2.2 add
- 2.3 update
- 2.4 draw
- 2.5 position
- 2.6 radius
- 2.7 legend

1. Usage

To draw a pie chart you need to provide an array of data items:

data = [
  { name: 'BTC', value: 5977, color: :bright_yellow, fill: '*' },
  { name: 'BCH', value: 3045, color: :bright_green, fill: 'x' },
  { name: 'LTC', value: 2030, color: :bright_magenta, fill: '@' },
  { name: 'ETH', value: 2350, color: :bright_cyan, fill: '+' }
]

Then pass data to TTY::Pie instance with a given radius:

pie_chart = TTY::Pie.new(data: data, radius: 5)

and print the pie chart in your terminal window:

print pie_chart
# =>
#         ++***
#     ++++++*******        * BTC 44.60%
#   @@@+++++*********
#  @@@@@@+++**********     x BCH 22.72%
# @@@@@@@@@+***********
# @@@@@@@@@@x**********    @ LTC 15.15%
# @@@@@@@@@xx**********
#  @@@@@@xxxx*********     + ETH 17.53%
#   @@@xxxxxxx*******
#     xxxxxxxx*****
#         xxxx*
#

2. Interface

2.1 data

To draw a pie chart you need to provide data. A single data item is just a Ruby hash that can contain the following keys:

:name - used for setting the entry name in legend
:value - used for calculating actual pie slice size
:color - used to color a pie slice corresponding with a value
:fill - used as a character to fill in a pie slice

At the very minimum you need to provide a :value in order for a pie to calculate slice sizes. If you wish to have a legend then add the :name key as well.

For example, the following will result in four slices in a pie chart:

data = [
  { name: 'BTC', value: 5977 },
  { name: 'BCH', value: 3045 },
  { name: 'LTC', value: 2030 },
  { name: 'ETH', value: 2350 }
]

However, the above data slices will be displayed without any color. Use :color out of supported colors:

data = [
  { name: 'BTC', value: 5977, color: :bright_yellow },
  { name: 'BCH', value: 3045, color: :bright_green },
  { name: 'LTC', value: 2030, color: :bright_magenta },
  { name: 'ETH', value: 2350, color: :bright_cyan }
]

To further make your chart readable consider making pie chart slices visible by channging the displayed characters using :fill key:

data = [
  { name: 'BTC', value: 5977, color: :bright_yellow, fill: '*' },
  { name: 'BCH', value: 3045, color: :bright_green, fill: 'x' },
  { name: 'LTC', value: 2030, color: :bright_magenta, fill: '@' },
  { name: 'ETH', value: 2350, color: :bright_cyan, fill: '+' }
]

There is no limit to the amount of data you can present, however there is a point of scale and legibility to be considered when printing in the terminals.

You can add data to pie chart during initialization using :data keyword:

pie_chart = TTY::Pie.new(data: data)

Alternatively, you can delay adding data later with add or << methods:

pie_chart = TTY::Pie.new
pie_chart << { name: 'BTC', value: 5977, color: :bright_yellow, fill: '*' }
pie_chart << { name: 'BCH', value: 3045, color: :bright_green, fill: 'x' }
pie_chart << { name: 'LTC', value: 2030, color: :bright_magenta, fill: '@' }
pie_chart << { name: 'ETH', value: 2350, color: :bright_cyan, fill: '+' }

2.2 add

You can also set data for the pie chart using the add or << method calls. Once a pie chart is initialized, you can add data items:

pie_chart = TTY::Pie.new
pie_chart << { name: 'BTC', value: 5977, color: :bright_yellow, fill: '*' }
pie_chart << { name: 'BCH', value: 3045, color: :bright_green, fill: 'x' }
...

2.3 update

To replace current data completely with the new use update:

data = [
  { name: 'BTC', value: 5977, color: :bright_yellow, fill: '*' },
  { name: 'BCH', value: 3045, color: :bright_green, fill: 'x' }
]
pie_chart = TTY::Pie.new(data: data)

new_data = [
  { name: 'BTC', value: 3400, color: :bright_yellow, fill: '*' },
  { name: 'BCH', value: 1200, color: :bright_green, fill: 'x' },
]

pie_chart.update(new_data)

2.4 draw

Once a pie chart has been initialized use the draw or to_s method to return a string representation of the chart.

To actually show it in a terminal, you need to print it:

print pie_chart.draw
# => this will render chart in terminal

You can skip calling any method and simply print:

print pie_chart
# => this will render chart in terminal

2.5 position

If you don't provide location for you pie chart it will be printed at the current cursor location. In order to absolutely position the chart use :left and :top keyword arguments. For example, if you wanted to position the pie chart at 50thcolumn and 10th row:

TTY::Pie.new(data: data, left: 50, top: 10)

2.6 radius

By default, a pie chart is rendered with a radius of 10, you can change this using the :radius keyword:

TTY::Pie.new(data: data, radius: 5)

2.7 legend

Provided the following data:

data = [
  { name: 'BTC', value: 5977, fill: '*' },
  { name: 'BCH', value: 3045, fill: '+' },
  { name: 'LTC', value: 2030, fill: 'x' }
]

You can control how the legend is displayed using the :legend keyword and hash as value with the following keys:

:left - used to determine spacing between a chart and a legend, defaults to 4 columns
:line - used to determine spacing between legend labels, defaults to 1 line

For example, to place a legend 10 columns away from the pie chart and separate each label by 2 lines do:

pie_chart = TTY::Pie.new(data: data, radius: 3, legend: {left: 10, line: 2})

And printing in a terminal will produce:

print pie_chart
# =>
#      x**               * BTC 54.08%
#   xxxx*****
# ++++xx*******
# ++++++*******          + BCH 27.55%
# ++++++*******
#   ++++*****
#      +**               x LTC 18.37%

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-pie_chart. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the TTY::Pie project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.