masukomi/heatmapper

a command line heatmap generator

Heatmapper

Heatmapper is a simple command line utility to output github style heatmaps on the command line.

It's specifically focused on just the heatmap, and intended to be leveraged by other programs. Either via the command line OR via your favorite language's ability to leverage C libraries (see below).

If you want to generate a command line heatmap with your GitHub information I recommend you check out these two projects

• Heatwave by James Stoup (Python)
• Git Stats by Ionică Bizău (JavaScript)

Example

Installation

Heatmapper is written in Chicken Scheme

You can install that with brew install chicken-scheme if you're on macOS or Linux, otherwise follow the instructions on their site.

Once you've gotten that installed:

cd src
# install the required libraries
./install_chicken_eggs.sh
./build.sh

That's it. You should now have a heatmapper executable in the same directory.

There are a couple test files in misc:

• numbers.txt
• random_numbers.txt

Try running cat ../misc/random_numbers.txt | ./heatmapper just to make sure everything's working. If everything looks good, copy that somewhere in your PATH and you're good to go.

Usage

Just pipe some data into it and it'll generate at heatmap 80 columns wide and 7 rows tall.

❯ ./heatmapper --help
Usage: piped data | heatmapper heatmapper [options...]
       Supported color schemes: github, darkdub, bluehub, wistia

 -c, --columns=ARG        max number of columns [default: 80]
 -r, --rows=ARG           max number of rows [default: 7]
 -s, --scheme=ARG         color scheme [default: github]
 -h, --help               Display this text

Report bugs to https://github.com/masukomi/heatmapper/issues

Usage notes

The data fills from from the top left corner down, then moves one column to the right, and fills down again. It stops when it runs out of data or hits the maximum number of columns. Unfinished rows will be filled out with zero values.

A good way to have it always use your current terminal width (in bash / zsh) is to use tput as follows:

cat numbers.txt | heatmapper --columns $(tput cols)

Pro-tip

If you want to use this in something that generates HTML you could use oho to convert the output to HTML.

Adding a Color Scheme

Adding a color scheme is pretty easy, even if you don't know Chicken Scheme. You'll need a palette of 5 colors. Get their RGB values, then open up the src/heatmap.scm file.

The first define in that file is setting up the color schemes. Just replicate what's in the existing ones, change the color numbers, and give it a new name. Note that the colors are ordered from lightest to darkest.

The color name comments are entirely optional, but nice to have. :D

There's C code too

Chicken Scheme compiles to C.

You can actually generate the C source files and headers for use in other projects. I've specifically designed this so that you can have just the core library without the command line handling stuff.

The file you want is src/heatmap.scm

Follow the instructions here to generate the C files and headers.

Oh, and ruby

Before I ported this to Chicken Scheme I prototyped the idea with a quick and dirty ruby script. You can find it in misc/ruby_prototype.rb

Contact & Contribution

If you do use this in something, please Let me know on Mastodon.

If you've got an issue, please file a ticket here on GitHub.

License

This code is distributed under the AGPL license. See the LICENSE file for more details.

If you need to incorporate this into a commercial product I'm happy to give you a difference license in exchange for money. ;)

heatmapper's Issues

columns does not appear to be honored

example:

cat random_numbers.txt | heatmapper --columns=4 --rows=1

that SHOULD result in 4 squares. (4 columns x 1 row) despite the fact that 100 items are being passed in.

rows does seem to be being honored.

the algorithm SHOULD just exit out of the loop once columns X rows squares have been populated.

It currently handles the problem of there not being enough data and padding it out to fill the remaining columns.

populate trailing rows with 1st color values

In the example images you can see that the final column doesn't have enough values.

It's difficult for the caller to pre-calculate that to make it pretty because most of the time it will depend on window width. You need Columns x Rows values, and columns is, presumably going to be variable.

So, we should edit the populate-output-data
it should take the output-data that it's about to return, and run it through a new function that checks that all the rows are the same length, and if not, fills in the remaining ones with an additional entry that consists of the 1st color of the chosen color scheme.

Support Bi-directional Heatmaps

The current heatmap shows a visual representation of "none" to "a lot" which is good for quantity / amount but not good for quality where it can be positive or negative.

so, this proposal is to allow 2 things

1. negative numbers
2. two heatmaps.

Negative Numbers

You'd want the positive and negative scales to be equal so i think just process all numbers as if positive to get the max and then use that on + & - sides.

any math calculations would have to be tweaked / have their input tweaked to not be borked by the negative numbers

Two Heatmaps

You should be able to specify 2 heatmaps to use with this scale

• the first should be negative
• the second should be positive

Visually the 1st would be flipped, but under the covers it'd be the same. -100 is functionally equivalent to 100 it's just the "more" end of the scale. more bad / negative vs more good / positive.

Thoughts

we need a positive color map that's specifically good at pairing with a negative one. I'm thinking a pair like darkhub + a wistia like variant that pairs better with it. (something orangey but with a low end that is closer to the dark of darkhub)

There would be a default negative heatmap. Simpler than dealing with "pairs" you just specify the scheme you want (or not) and, if you want to control the negative scheme you just specify --negative_scheme=xxx