A cli tool directly inspired by spark. sparkler produces graphical plots from whitespace-delimited lists of numbers passed by other command line arguments.

In 2017 I wrote an introductory article about sparkler.

sparkler makes an attempt to be smart about displaying data in a way that makes sense while reducing visual noise.

• if the x-axis has labels, perform sampling for large data sets (so that the labels never overlap)
• fit the graph to the drawing area, so that the graph always fills the entire area available for display
• use log scale if the range of values is large

The output image is written to a file called graph-<HASH>.png in the current working directory, where <HASH> is the sha1 hash of the argument list that was passed to sparkler. This means that each data set you pass to sparkler should result in a consistent file name that is unique to that data set. The name of the generated png file is echoed back to the command line so that you can easily reference it in your scripts. Eg:

open `sparkler 0 1 1 2 3 5`

sparkler graphs should fit exactly on a sheet of legal paper when printed.

Just pipe a newline-delimited list of integers to bin/sparkler and it will produce a graphical plot.

The following command will produce a graphical plot that shows the first nine integers of the Fibonacci Sequence.

echo 0 1 1 2 3 5 8 13 21 | bin/sparkler

or

echo "0
1
1
2" | bin/sparkler

Any text after the integer tokens is used as labels for the x-axis:

echo "0 this is a label
1 this is another label
1 and so on
2 yep labels" | bin/sparkler

You can also pass arguments directly:

bin/sparkler 0 1 1 2 3 5 8 13 21

or

bin/sparkler "0
1
1
2"

and also

bin/sparkler "0 this is a label
1 this is another label
1 and so on
2 fun with labels"

The following command will install all dependencies, and should work on any system with a relatively modern version of Python:

sudo easy_install numpy matplotlib

You can optionally move or symlink bin/sparkler to /usr/bin/sparkler (or anywhere in your path) and it should then be usable from anywhere on your system, just like any other shell command.

tests/run

If the exit code is 0, all is well.

The tests generate graphs off of various inputs and then diff the each generated image against a fixture image, to validate that the expected graphs were produced.

sparkler is intended to be like spark: a dead simple tool that does the right thing 99% of the time. Thus there are no configuration options.

The general use case for sparkler is: "I am looking at the output from a shell command and I wonder what it looks like as a graph." More complex use cases are intentionally not considered.

When you require that level of detail in your analysis, you should switch to using matplotlib directly, or use another data visualization tool like R, GNUPlot, Flot or d3.

Specifically, you cannot label the axis nor add a title to the graph using sparkler. For that you can edit the PNG output files using an image-annotating tool like Photoshop, Skitch or Jing.

And you also cannot combine multiple data series on a single graph. When you reach a point where you have multiple data series saved in different files, you should consider using a tool more powerful than sparkler.