TTY:Pie

Draw pie charts in your terminal window

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

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

Contents

• 1. Usage
• 2. Interface
  • 2.1 data
  • 2.2 add
  • 2.3 update
  • 2.4 render
  • 2.5 position
  • 2.6 radius
  • 2.7 legend
    • 2.7.1 format

1. Usage

To render 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 render 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 render

Once a pie chart has been initialized use the render 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.render
# => 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
• :format - used to format a display label using template named strings
• :precision - used to determine currency display decimal places, defaults to 2
• :delimiter - used to set thousands delimiter in currency format

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%

2.7.1 format

The :format uses Ruby's format sequences and named strings placeholders:

• <label> - the icon matching pie chart display
• <name> - the label name provided in data
• <value> - the label value provided in data, by default not displayed
• <currency> - the label value formatted as currency
• <percent> - the percent automatically calculated from data

By default the label is formatted according to the following pattern with named strings:

"%<label>s %<name>s %<percent>.2f%%"

Given data items:

data = [
  { name: "BTC", value: 5977.12345, fill: "*" },
  { name: "BCH", value: 3045.2, fill: "+" },
  { name: "LTC", value: 2030.444, fill: "x" }
]

The legend will show:

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

To display value together with percent, use <value> named string in the format:

legend: {
  format: "%<label>s %<name>s %<value>d (%<percent>.2f%%)"
}

The legend will show:

# =>
#      x**       * BTC 5977 (54.08%)
#   xxxx*****
# ++++xx*******
# ++++++*******  + BCH 3045 (27.55%)
# ++++++*******
#   ++++*****
#      +**       x LTC 2030 (18.37%)

To display value as currency use <currency> name string in the format:

legend: {
  format: "%<label>s %<name>s $%<currency>s (%<percent>.0f%%)"
}

The legend will show:

# =>
#      x**       * BTC $5,977 (54%)
#   xxxx*****
# ++++xx*******
# ++++++*******  + BCH $3,045 (28%)
# ++++++*******
#   ++++*****
#      +**       x LTC $2,030 (18%)

The currency can be further customised using :precision and :delimiter keys:

legend: {
  format: "%<label>s %<name>s $%<currency>s (%<percent>.0f%%)",
  precision: 3,
  delimiter: "*"
}

The legend will show:

# =>
#      x**       * BTC $5*977.123 (54%)
#   xxxx*****
# ++++xx*******
# ++++++*******  + BCH $3*045.200 (28%)
# ++++++*******
#   ++++*****
#      +**       x LTC $2*030.444 (18%)

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. 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.

Copyright

Copyright (c) 2018 Piotr Murach. See LICENSE.txt for further details.