Contex - a pure Elixir server-side charting library generating SVG output

mindok · January 26, 2020, 4:28am

What is ContEx?

A pure Elixir server-side data plotting/charting library outputting SVG.

It has nice barcharts in particular and works great with LiveView.

Project is here: GitHub - mindok/contex: Charting and graphing library for Elixir.

There’s a v0.1.0 package up on hex, but probably to link to github for another week or two.

Samples

The web-site https://contex-charts.org/ has some interactive samples so you can take a look, but there are some screenshots below so you don’t even have to follow a link

The code for the web-site is here: GitHub - mindok/contex-samples: Sample web application demonstrating contex features. This code is currently the best documentation…

Is it ready for production?

It’s pretty early days. I’m announcing I think it may be useful even it it’s a bit raw in places. See limitations below.

Why did you write it?

For a couple of reasons:

I had a lot of dashboard & data visualisation work coming up and although I could generate nice charts using Javascript libraries, it’s fiddly and involves quite a lot of boilerplate.
I have benefitted immensely from the open source community and decided that this could be a reasonable gift back to the community as a way of saying thanks. I know from reading the forums etc that there is a need for something like this

What are the main limitations?

It’s early days, so the API is going to change and that might break any code that relies on it. Plus documentation is somewhere between extremely poor and non-existent.
Interacting with the graphics (for example, brushing) isn’t possible without a lot of JS. If you need highly interactive graphics, use a JS charting library
Some browsers (notably iOS-based) don’t pick up clicks from SVG elements, so if you rely on this and have no control over the end user’s browser, you may want to use something else
There’s no state management in the chart generation at this point, so no smarts to send incremental diffs to the browser as a dataset changes. This may be reconsidered when Phoenix LiveView has better handling of changes to lists, although it is quite complex when it comes to managing and adjusting axes as data change.

Enjoy!

Thanks for early feedback from @elcritch & others (suggestions not yet implemented, but will be very shortly)

Eiji · January 26, 2020, 4:36am

I suggest to read :timer documentation:
https://erlang.org/doc/man/timer.html

mindok · January 26, 2020, 4:50am

Hi @Eiji,

Any hints as to why?

Eiji · January 26, 2020, 7:22am

@mindok Oh, I thought you would quickly get it.
Hint is really simple: look again at suggested module documentation and re-check your duration_* module attributes:

github.com

mindok/contex/blob/master/lib/chart/scale/time_scale.ex

defmodule Contex.TimeScale do
  @moduledoc """
  A time scale to map date and time data to a plotting coordinate system.

  Almost identical `Contex.ContinuousLinearScale` in terms of concepts and
  usage, except it applies to `DateTime` and `NaiveDateTime` domain data
  types.

  `TimeScale` handles the complexities of calculating nice tick intervals etc
  for almost any time range between a few seconds and a few years.

  """
  alias __MODULE__

  alias Contex.Utils

  @type datetimes() :: NaiveDateTime.t() | DateTime.t()

  # Approximate durations in ms for calculating ideal tick intervals
  # Modelled from https://github.com/d3/d3-scale/blob/v2.2.2/src/time.js

This file has been truncated. show original

For example instead of:

{:hour, 12, @duration_hour * 12}

you can use:

:timer.hours(12)

mindok · January 26, 2020, 9:28am

Ah! I was looking at the dynamic aspects of the :timer module thinking I’d messed up the animated barchart!

Yep - that might simplify things a little thanks, but the tricky thing with calculating nice looking timescales is knowing the type of interval you are dealing with, not just its size, so I would still need to carry :hour and 12 in the tuple in order to calculate a nice boundary for the interval (i.e. 00:00 and 12:00 in this case - the internal round_down_to functions handle this for different combinations of period size and period type). This becomes particularly important for longer time periods where the size of the period varies (e.g. 28 days for Feb and 31 for March). The millisecond estimate is just used to guess at the best time period.

outlog · January 26, 2020, 12:15pm

looks amazing! great work

fyi: the changelog link on the website is 404 - should be https://github.com/mindok/contex/blob/master/CHANGELOG.md

mindok · January 26, 2020, 2:09pm

Thanks - fix on its way…

chasers · January 26, 2020, 5:08pm

Very cool!

mazz-seven · January 26, 2020, 7:39pm

Looks awesome!

mindok · January 28, 2020, 3:39am

v0.2.0 out now and pushed to hex.

The big news is documentation and type specs, which shouldn’t really be news!

There are notes in the changelog in the git repo, but the main breaking change is a rename of BarPlot to BarChart (more generally acceptable terminology).

ksherman · January 30, 2020, 4:06am

This looks pretty cool! Definitely going to watch progress

axelson · February 10, 2020, 4:17am

This is really neat! I was able to integrate it into a little tool I’m making to see Language Server Protocol requests:

mindok · June 8, 2020, 8:03am

I have just pushed v0.3.0 to Hex. The changes are listed below. I would first like to thank various contributors for their help in improving the library - @srowley in particular has done a lot of work on getting comprehensive in place, putting together the shortcut plotting API and improving the data mapping into plot elements. @Eiji has provided numerous suggestions to tighten up the code, as has @elcritch. @axelson has added a couple of features, has encouraged use of Elixir standard formatting so that it is easier to contribute and gave me a nudge to get this release out the door (I would have liked to have got line plots in first but things happened and there are lots of valuable improvements since the last release). Thanks too, to @tobstarr for the doco fix and @rodrigues for setting up github workflows.

So what’s new? The changelog has the full list, but here are the highlights:

The DataSet module can now use a list of maps - this reduces translation work from Ecto output and was really a massive oversight in the original version.
Added a short-cut API over the top of the existing API - you can supply the chart type module in Plot.new along with the data and options and have the plot constructed in a single pass, rather than constructing the PlotContent separately and passing it to the Plot to layout.
Big improvements to the code quality, e.g in TypeSpecs & for the SVG generation so hopefully others will be able to navigate the codebase a little easier.
Various bug fixes. Apologies for the clanger in Sparklines that @jimsynz found !
Basic input sanitisation for possible user inputs (e.g. titles, axis labels, category names).

jimsynz · June 8, 2020, 8:12pm

@mindok love your work.

SophieDeBenedetto · October 5, 2020, 10:00pm

Hey @mindok! I’m working on PragProg’s upcoming LiveView book with @redrapids and I’m hoping to include the usage of your library as our SVG charting library of choice! I’m stuck on rendering a bar chart with the appropriate category labels though and I’m hoping you can point me in the right direction. I’ve tried cloning down your sample repo and more or less copying the bar chart code/data structure but still no dice.

So what I’m after is the application of each column/row label, per the image below:

Could you explain what part of a given Dataset’s structure of BarChart or Plot configuration is responsible for applying those labels?

Thank you!

SophieDeBenedetto · October 5, 2020, 10:47pm

aaaand nevermind! it was a CSS issue (I should know that if I am extremely confused about something it is probably related to CSS!). I copy-pasted your styles from the example repo and my labels are there in all of their visible glory!

mindok · October 6, 2020, 1:19am

Hi @SophieDeBenedetto - that’s happened a couple of times now, so I’ll create an issue to provide a better default.

Pretty excited to hear you’re looking at Contex in the LiveView book! Let me know if you have any more q’s.

SophieDeBenedetto · October 6, 2020, 1:30am

Definitely will do! So far I’ve been able to make my way through the docs and build out what we need but I’ll keep you posted

mindok · October 23, 2020, 10:21am

A heads up - there are quite a few changes in master ahead of the next release, including:

Line Charts (at last)
All options can be set in new/2 options parameter for each of the chart types
Other ways of setting options have been marked as deprecated - any feedback on this decision would be appreciated. I know there would be some advantage in maintaining the existing option setting functions to allow a pipeline type interface
Minimal default style is there so labels show if no CSS is set
It is now possible to explicitly set scales
BarChart now has phx-target option for events so it can be used in LiveComponents

The changes are reflected in the accompanying sample project, and are up on the https://contex-charts.org/ website.

You can access these changes prior to release by point the dependency in mix.exs to github:

{:contex, git: "https://github.com/mindok/contex"},

haubie · January 22, 2021, 9:52am

Thanks for making this @mindok and sharing it with the community, a very nice library! I used it today in a live view project, something magical about seeing the chart change dynamically from server events without having to write any JavaScript.

@SophieDeBenedetto your blog on Contex (https://elixirschool.com/blog/server-side-svg-charts-with-contex-and-liveview/) was quite helpful as an example, looking forward to the book!