A shell command that produces graphs
sparkler is a CLI tool like spark, that produces graphical plots from whitespace-delimited lists of numbers.
> sparkler produces graphical plots from (optionally labeled) lists of numbers.
sparkler is a CLI tool (written in Python) that I made upon discovering-and-being-inspired-by spark.
Where spark produces minimal sparklines you can actually see in your terminal, sparkler addresses the “but now I want to show it to someone else” problem by producing graphical (though very minimal) plots.
Like spark, sparkler consumes whitespace-delimited lists of numbers (and optionally a label for each data point as well) which are “piped in” or otherwise passsed by other command line arguments. sparkler can consume input in several different ways to make it easier to plug in the output from your other shell scripts!
Installation
sparkler requires the Python modules numpy and also matplotlib which can both be installed using pip.
sparkler is a standalone executable Python script which you can find in the bin directory of the git repo. You can put it anywhere in your path and it will work.
Simple graphs. Very simple.
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
Globally unique file names per data set
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. Here’s a trivial example of how this is useful, if your system supports the open command:
open `sparkler 1 2 3 4`
This would produce a plot of the four numbers given, then immediately echo the name of the plot file to the open command which would display the PNG file that was just created. If you need to save plot names to variables or rename plots on the fly, sparkler makes that really easy for you.
Easy to print, easy to PDF, easy to share with your team
sparkler graphs are produced as PNG format images and should fit exactly on a sheet of legal paper when printed.
What it looks like to use sparkler
Here’s a trivial example where I make some labeled data and feed it into sparkler. You can see that the numbers (the data) must come before the labels!
And the resulting graph PNG looks pretty much like you would imagine (click for full size):
sparkler draws a horizontal line at the median of the data series and prints the label on the right-hand y-axis. In this case you can see that the median is 2.5.
Each file name is a GUID matched to the input data set
You’ll notice that the graph PNG has a really ugly name. That’s a SHA1 hash based on the data set. It’s not pretty, but it does prevent you accidentally overwriting similar versions of the same graph when you are tweaking your data set iteratively and rapidly as tends to happen when doing command-line data analytics!!!
What’s it look like with more data?
Now just for kicks let’s feed sparkler a lot of data points. I’ll use seq to do this because it’s easy for me and obvious to the reader what is happening :)
And again the produced plot looks pretty much like you would expect. Again a line has been drawn at the median of the number series:
Pull requests welcome!
Naturally if you notice something amiss or would like to add a feature to sparkler, please contact me via the git repo or @ me on Twitter!