clic v0.2.1

C.ommand L.ine I.interface C.harts: A stdin/stdout-friendly way to render SVG and PNG charts from delimited data in your shell.

Todo

• clic-line
• clic-bar
• clic-histogram
• clic-scatter

Install

clic is built on top of d3 and requires node and npm. You can install clic using npm. It has only been tested on OS X Yosemite. Also ensure you're on a relatively recent version of node and npm. Specifically, node > 0.12.0 is recommended. npm comes bundled with node, so if you upgrade node, you should get a recent version of npm.

npm install -g clic

If you want a nicer looking font, download and install Open Sans.

Upgrade

To upgrade to the latest clic package you can run

npm install -g clic@latest

Generate a simple line chart SVG

Note: Use --points to toggle the points along a line. They are not drawn by default.

cat clic/test/dsv/simple.tsv | clic-line \
  --sep '\t' \
  --xkey month \
  --ykey total_commits,total_pushes \
  --reverse > chart.svg

Generate a time series

You can generate a time series chart by supplying the --time-series flag. The xkey is treated as the date, whose format defaults to the full ISO standard. You can use --in-time-format to pass a custom parse format to use.

cat clic/test/dsv/timeseries.csv | clic-line \
  --xkey PDT \
  --ykey 'Max TemperatureF' \
  --in-time-format '%Y-%m-%d' \
  --title 'Max temps. for Portland, OR' \
  --time-series > timeseries.svg

Format output of timeseries dates

You can specify an output format for dates along the x axis by passing a time format to --out-time-format.

cat clic/test/dsv/timeseries.csv | clic-line \
  --xkey PDT \
  --ykey 'Max TemperatureF' \
  --in-time-format '%Y-%m-%d' \
  --out-time-format '%a' \
  --title 'Max temps. for Portland, OR' \
  --time-series   > timeseries.svg

Generate a bar chart

 cat clic/test/dsv/simple.tsv | clic-bar \
    --xkey month \
    --ykey total_commits \
    --sep '\t' > bar.svg

Generate a grouped bar chart

To create a grouped bar chart you need only supply more than one ykey. Each additional ykey will generate a new bar in the group.

cat clic/test/dsv/simple.tsv | clic-bar \
    --xkey month \
    --ykey total_commits,total_pushes \
    --sep '\t' > grouped.svg

Generate a stacked bar chart

Passing --stack to clic-bar when encoding more than one ykey will result in a stacked bar chart.

cat traffic.csv | clic-bar \
    --xkey year \
    --ykey returning,new  \
    --width 300 \
    --ymin 0 \
    --stack > stacked.svg

Generate a vertical bar chart

Vertical bar charts are not supported as of yet.

Legends

Add a legend

Pass the --legend flag to generate a legend

cat awesome-percent.csv | clic-bar \
    --xkey month \
    --ykey javascript_percent,ruby_percent,python_percent,csharp_percent \
     --title 'Month over month language awesomeness' \
     --legend > test.svg

Set legend column count

clic doesn't support wrapping or clipping of legend labels, but it does give you the ability to supply how many legend items should appear on each row using --legend-columns. For instance, if you have legend items that are wrapping, try setting --legend-columns to a smaller number.

cat awesome-percent.csv | clic-bar \
    --xkey month \
    --ykey javascript_percent,ruby_percent,python_percent,csharp_percent \
     --title 'Month over month language awesomeness' \
     --legend-columns 4 \
     --legend > test.svg

cat awesome-percent.csv | clic-bar \
    --xkey month \
    --ykey javascript_percent,ruby_percent,python_percent,csharp_percent \
     --title 'Month over month language awesomeness' \
     --legend-columns 2 \
     --legend > test.svg

Titles, labels, and ticks

Adding a title

Pass a string to the --title argument to render a title

cat unique-percent.csv | clic-line \
    --xkey month \
    --ykey csharp_percent,javascript_percent \
    --legend \
    --title 'Language Growth' > line.svg

Add a label on the x or y axis

• Pass a string to the --ylabel arg to render a vertial label along the y axis
• Pass a string to the --xlabel arg to render a label along the x axis

cat unique-percent.csv |  clic-line \
    --xkey month \
    --ykey javascript_percent \
    --xlabel 'month' \
    --ylabel '% growth' > line.svg

Controlling x tick rendering along the x axis

Or "How to fix overlapping x ticks." There's basic support for controlling the spacing between x ticks using the --xticks option. The value of xticks tells clic to render a tick every nth value. So --xticks 3 would render every 3rd tick.

Rotating labels

Label rotation isn't supported as of yet. See #10 for the underlying issue.

Generate a PNG image from an SVG

Install svg2png-cli and execute it. Note that there appears to be a bug in svg2png-cli requiring you to supply either --scale or --width.

npm install svg2png-cli -g
svg2png bar.svg --scale 2

Miscellaneous options

• --reverse - Reverse the dataset before rendering.
• --sep - Specify the separator for the incoming data.

All shared options

Options:
  --help                Show help
  --xkey                Name of data key to use for x axis            [required]
  --ykey                Name of data key(s) to use for y axis         [required]
  --width               width of graph                            [default: 800]
  --height              height of graph                           [default: 500]
  --margin              Margin around graph given as "t r b l"
                          [default: {"top":10,"right":10,"bottom":30,"left":50}]
  --xticks              Render tick ever nth point
  --ymin                Min value for y axis
  --ymax                Max value for y axis
  --colors              comma-seperated list of colors to use in charts
                        [default:
                        "#63477A,#80D24D,#DA612E,#11B0A7,#BF5BD5,#C74160,#878B28,#C6509A,#7482D1,#853E22"]
  --xlabel              Label for x axis
  --ylabel              Label for y axis
  --legend              Render a legend                                [boolean]
  --legend-columns      Number of columns per row in legend         [default: 3]
  --legend-item-height  Height for individual legend item          [default: 20]
  --meta                String to print at bottom of chart
  --out                 Name of file to write
  --in                  Name of delimited file to read   [default: "/dev/stdin"]
  --sep                 Delimiter used to separate values in input
                                                                  [default: ","]