Popularity
2.3
Stable
Activity
8.4
Stable
214
4
5

Description

ApexCharts.rb is a ruby gem that wraps a JavaScript charting library called with the same name, apexcharts.js, that's going to give you beautiful, interactive, and responsive charts for your ruby app.

Monthly Downloads: 198,095
Programming language: Ruby
License: MIT License
Latest version: v0.1.5

apexcharts.rb alternatives and similar gems

Based on the "Data Visualization" category

Do you think we are missing an alternative of apexcharts.rb or a related project?

Add another 'Data Visualization' Gem

README

What is this?

ApexCharts.rb is a ruby gem that wraps a JavaScript charting library called with the same name, apexcharts.js, that's going to give you a beautiful, interactive, and responsive charts for your ruby app.

Table of Contents

Usage

Cartesian Charts

Example series used for cartesian charts:

<% series = [
  {name: "Inactive", data: @inactive_properties},
  {name: "Active", data: @active_properties}
] %>

To build the data, you can use gem groupdate.
In my case, it was:

@inactive_properties = Property.inactive.group_by_week(:created_at).count
@active_properties = Property.active.group_by_week(:created_at).count

and I'll get the data in this format:

{
  Sun, 29 Jul 2018=>1,
  Sun, 05 Aug 2018=>6,
  ..
}

PS: Property can be any model you have and inactive and active are just some normal ActiveRecord scopes. Keep scrolling down to see accepted data formats.

Example options used for cartesian charts:

<% options = {
  title: 'Properties Growth',
  subtitle: 'Grouped Per Week',
  xtitle: 'Week',
  ytitle: 'Properties',
  stacked: true
} %>

Line Chart

<%= line_chart(series, options) %>

[Example Line Chart](images/line_chart.gif)

Stepline Chart

<%= line_chart(series, {**options, theme: 'palette7', curve: 'stepline'}) %>

[Example Stepline Chart](images/stepline_chart.gif)

Area Chart

<%= area_chart(series, {**options, theme: 'palette5'}) %>

[Example Area Chart](images/area_chart.gif)

Column Chart

<%= column_chart(series, {**options, theme: 'palette4'}) %>

[Example Column Chart](images/column_chart.gif)

Bar Chart

<%= bar_chart(series, {**options, xtitle: 'Properties', ytitle: 'Week', height: 800, theme: 'palette7'}) %>

[Example Bar Chart](images/bar_chart.gif)

Range Bar Chart

<% range_bar_series = [{
      name: "Series A",
      data: {
        'A' => [1, 5],
        'B' => [4, 6],
        'C' => [5, 8],
        'D' => [3, 11]
      }
    }, {
      name: "Series B",
      data: {
        'A' => [2, 6],
        'B' => [1, 3],
        'C' => [7, 8],
        'D' => [5, 9]
      }
  }]
%>

<%= range_bar_chart(range_bar_series, theme: 'palette3') %>

[Example Range Bar Chart](images/range_bar_chart.gif)

Scatter Chart

<%= scatter_chart(series, {**options, theme: 'palette3'}) %>

[Example Scatter Chart](images/scatter_chart.gif)

Candlestick Chart

Candlestick chart is typically used to illustrate movements in the price of a financial instrument over time. This chart is also popular by the name "ohlc chart". That's why you can call it with ohlc_chart too.
So, here's how you make it.

Given:

<%
  require 'date'

  def ohlc(ary)
    [rand(ary.min..ary.max), ary.max, ary.min, rand(ary.min..ary.max)]
  end

  candlestick_data = 50.times.map do |i|
    [Date.today - 50 + i, ohlc(Array.new(2){ rand(6570..6650) })]
  end.to_h

  candlestick_options = {
    plot_options: {
      candlestick: {
        colors: {
          upward: '#3C90EB',
          downward: '#DF7D46'
        }
      }
    }
  }
%>

You can make candlestick chart with this:

<%= candlestick_chart(candlestick_data, candlestick_options) %>

[Example Candlestick Chart](images/candlestick_chart.gif)

Real life candlestick chart probably don't look like that. That's because I just use random sets of numbers as the data.

Mixed Charts

You can mix charts by using mixed_charts or combo_charts methods. For example, given that:

@total_properties = Property.group_by_week(:created_at).count

and

<% total_series = {
  name: "Total", data: @total_properties
} %>

you can do this:

<%= combo_charts({**options, theme: 'palette4', stacked: false, data_labels: false}) do %>
  <% line_chart(total_series) %>
  <% area_chart(series.last) %>
  <% column_chart(series.first) %>
<% end %>

[Example Mixed Charts](images/mixed_charts.gif)

Syncing Charts

You can synchronize charts by using syncing_charts or synchronized_charts methods. For example:

<%= syncing_charts(chart: {toolbar: false}, height: 250, style: 'display: inline-block; width: 32%;') do %>
  <% mixed_charts(theme: 'palette4', data_labels: false) do %>
    <% line_chart({name: "Total", data: @total_properties}) %>
    <% area_chart({name: "Active", data: @active_properties}) %>
  <% end %>
  <% area_chart({name: "Active", data: @active_properties}, theme: 'palette6') %>
  <% line_chart({name: "Inactive", data: @active_properties}, theme: 'palette8') %>
<% end %>

[Example Syncing Charts](images/syncing_charts.gif)

Brush Chart

<%= area_chart(total_series, {
  **options, chart_id: 'the-chart', xtitle: nil, theme: 'palette2'
}) %>
<%= mixed_charts(brush_target: 'the-chart', theme: 'palette7') do %>
  <% column_chart(series.first) %>
  <% line_chart(series.last) %>
<% end %>

[Example Brush Chart](images/brush_chart.gif)

Annotations

All cartesian charts can have annotations, for example:

<%= area_chart(series, {**options, theme: 'palette9'}) do %>
  <% x_annotation(value: ('2019-01-06'..'2019-02-24'), text: "Busy Time", color: 'green') %>
  <% y_annotation(value: 29, text: "Max Properties", color: 'blue') %>
  <% point_annotation(value: ['2018-10-07', 24], text: "First Peak", color: 'magenta') %>
<% end %>

[Example Area Chart with Annotations](images/chart_with_annotations.gif)

Heatmap Chart

<% heatmap_series = 17.downto(10).map do |n|
  {
    name: "#{n}:00",
    data: 15.times.map do |i|
      ["W#{i+1}", rand(90)]
    end.to_h
  }
end %>
<%= heatmap_chart(heatmap_series) %>

[Example Heatmap Chart](images/heatmap_chart.png)

Radar Chart

<% radar_series = [
  {
    name: "What it should be",
    data: { "Code review"=>10, "Issues"=>5, "Pull request"=>25, "Commits"=>60 }
  },
  {
    name: "What it really is",
    data: { "Code review"=>1, "Issues"=>3, "Pull request"=>7, "Commits"=>89 }
  }
] %>
<%= radar_chart(
  radar_series,
  {title: "GitHub Radar", markers: {size: 4}, theme: 'palette4'}
) %>

[Example Radar Chart](images/radar_chart.gif)

Bubble Chart

<% bubble_series = (1..4).map do |n|
  {
    name: "Bubble#{n}",
    data: 20.times.map{[rand(750),rand(10..60),rand(70)]}
  }
end %>
<%= bubble_chart(bubble_series, data_labels: false, theme: 'palette6') %>

[Example Bubble Chart](images/bubble_chart.png)

Polar Charts

Pie Chart

<%= pie_chart([
  {name: "Series A", data: 25},
  {name: "Series B", data: 100},
  {name: "Series C", data: 200},
  {name: "Series D", data: 125}
], legend: "left") %>

[Example Pie Chart](images/pie_chart.gif)

Donut Chart

<%= donut_chart([25, 100, 200, 125], theme: 'palette4') %>

[Example Pie Chart](images/donut_chart.gif)

Radial Bar Chart

Also called circle_chart.

<%= radial_bar_chart([
  {name: "Circle A", data: 25},
  {name: "Circle B", data: 40},
  {name: "Circle C", data: 80},
  {name: "Circle D", data: 45}
], legend: true) %>

[Example Circle Chart](images/radial_bar_chart.gif)

Data Formats

Cartesian Charts

The data format for line, stepline, area, column, bar, and scatter charts should be in following format per-series:

{
  <x value> => <y value>,
  <x value> => <y value>,
  ...
}

or this:

[
  [<x value>, <y value>],
  [<x value>, <y value>],
  ...
]

Candlestick Chart

Candlestick chart is just like other cartesian charts, only the y value is an array of 4 members which called the OHLC (Open-High-Low-Close):

{
  <x value> => [<Open>, <High>, <Low>, <Close>],
  <x value> => [<Open>, <High>, <Low>, <Close>],
  ...
}

or this:

[
  [<x value>, [<Open>, <High>, <Low>, <Close>]],
  [<x value>, [<Open>, <High>, <Low>, <Close>]],
  ...
]

Heatmap Chart

The data format for heatmap chart per-series is similar to cartesian charts. But instead of y values they are heat values. The series names will be the y values.

{
  <x value> => <heat value>,
  <x value> => <heat value>,
  ...
}

or this:

[
  [<x value>, <heat value>],
  [<x value>, <heat value>],
  ...
]

Radar Chart

The data format for radar chart per-series is also similar but instead of x values they are variables and instead of y values they are the only values for the variables with type of Numeric.

{
  <variable> => <value>,
  <variable> => <value>,
  ...
}

or this:

[
  [<variable>, <value>],
  [<variable>, <value>],
  ...
]

Bubble Chart

Bubble chart is similar to scatter chart, only they have one more value for bubble size:

[
  [<x value>, <bubble size>, <y value>],
  [<x value>, <bubble size>, <y value>],
  ...
]

Polar Charts

The data format for donut, pie, and radial bar are the simplest. They are just any single value of type Numeric.

Installation

Add this line to your application's Gemfile:

gem 'groupdate' # optional
gem 'apexcharts'

And then execute:

$ bundle

Web Support

Rails

After installing the gem, require it in your app/assets/javascripts/application.js.

//= require apexcharts

Or, if you use webpacker, you can run:

$ yarn add apexcharts

and then require it in your app/javascript/packs/application.js.

require("apexcharts")

Plain HTML+ERB (Without Framework)

After installing the gem, insert this to the top of your .html.erb files:

<script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
<% require 'set' %>
<% require 'apexcharts' %>
<% include ApexCharts::Helper %>

require 'set' is needed because of an issue in the dependency used, but not needed in the next release of ApexCharts.rb.

You can then generate the static html page with e.g.

$ erb sample.html.erb > sample.html

TODOs

  • Replace dependency smart_kv with dry-schema
  • Add more features (e.g. gradient line, background image, etc.)
  • Range bar chart
  • Support other ruby frameworks (sinatra, hanami, etc.)

Contributing

Everyone is encouraged to help improve this project by:

  • Reporting bugs
  • Fixing bugs and submiting pull requests
  • Fixing documentation
  • Suggesting new features
  • Implementing TODOs above

License

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

Like the charts?

Consider donating to the author of apexcharts.js to support his awesome library. This project wouldn't be possible without it.

Become a sponsor on Patreon.
One time donation on PayPal


*Note that all licence references and agreements mentioned in the apexcharts.rb README section above are relevant to that project's source code only.