README.md
1# chart [![Build Status](https://img.shields.io/travis/marianogappa/chart.svg)](https://travis-ci.org/marianogappa/chart) [![Coverage Status](https://coveralls.io/repos/github/MarianoGappa/chart/badge.svg?branch=master&nocache=1)](https://coveralls.io/github/MarianoGappa/chart?branch=master) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/marianogappa/chart/master/LICENSE)
2
3Quick & smart charting for STDIN
4
5[Blogpost](https://movio.co/en/blog/improving-with-sql-and-charts/)
6
7## Learn by example!
8
9[Cheatsheet](https://marianogappa.github.io/chart/)
10
11## Syntax
12
13```
14chart [options]
15```
16
17- `pie`: render a pie chart
18- `bar`: render a bar chart
19- `line`: render a line chart
20- `scatter`: render a scatter plot chart
21- `log`: use logarithmic scale (bar chart only)
22- `' '|';'|','|'\t'`: this character separates columns on each line (\t = default)
23- `-t|--title`: title for the chart
24- `-x`: label for the x axis
25- `-y`: label for the y axis
26- `--date-format`: Sets the date format, according to [https://golang.org/src/time/format.go](https://golang.org/src/time/format.go)
27- `--debug`: Use to make sure to double-check the chart is showing what you expect.
28- `-h|--help`: Show help
29- `--zero-based`: Makes y-axis begin at zero
30
31## Installation
32
33```
34go get -u github.com/marianogappa/chart
35```
36
37or get the latest binary for your OS in the [Releases section](https://github.com/MarianoGappa/chart/releases).
38
39## Example use cases
40
41- Pie chart of your most used terminal commands
42```
43history | awk '{print $2}' | chart
44```
45
46![Pie chart of your most used terminal commands](img/pie.png?v=1)
47
48- Bar chart of today's currency value against USD, in logarithmic scale
49```
50curl -s http://api.fixer.io/latest?base=USD | jq -r ".rates | to_entries| \
51 map(\"\(.key)\t\(.value|tostring)\")|.[]" | chart bar log -t "Currency value against USD"
52```
53
54![Bar chart of today's currency value against USD, in logarithmic scale](img/bar-log.png?v=1)
55
56- Bar chart of a Github user's lines of code per language (requires setting up an Access Token)
57```
58USER=???
59ACCESS_TOKEN=???
60curl -u $USER:$ACCESS_TOKEN -s "https://api.github.com/user/repos" | \
61 jq -r 'map(.languages_url) | .[]' | xargs curl -s -u $USER:$ACCESS_TOKEN | \
62 jq -r '. as $in| keys[] | [.+ " "]+[$in[.] | tostring] | add' | \
63 awk '{arr[$1]+=$2} END {for (i in arr) {print i,arr[i]}}' | \
64 awk '{print $2 "\t" $1}' | sort -nr | chart bar
65```
66
67![Bar chart of a Github user's lines of code per language (requires setting up an Access Token)](img/bar.png?v=1)
68
69- Line chart of the stargazers of this repo over time up to Jan 2017 (received some attention after the publication of [this](https://movio.co/blog/migrate-Scala-to-Go/) blogpost)
70```
71curl -s "https://api.github.com/repos/marianogappa/chart/stargazers?page=1&per_page=100" \
72-H"Accept: application/vnd.github.v3.star+json" | \
73jq --raw-output 'map(.starred_at) | .[]' | awk '{print NR "\t" $0}' | \
74chart line --date-format 2006-01-02T15:04:05Z
75```
76
77![Line chart of Github stargazers of this repo over time](img/line.png?v-1)
78
79## Charting MySQL output
80
81`chart` works great with [sql](https://github.com/MarianoGappa/sql), or with any `mysql -Nsre '...'` query.
82
83## I don't trust the chart is correct
84
85Me neither. Add `--debug` to double-check (e.g. some rows could be being ignored due to parse failures, separator could be incorrect, column types could be inferred wrongly).
86
87```
88$ cat /tmp/c | ./chart bar --debug
89Lines read 3
90Line format inferred ff
91Lines used 3
92Float column count 2
93String column count 0
94Date/Time column count 0
95Chart type bar
96Scale type linear
97Separator [tab]
98```
99
100## Details
101
102- `chart` is still experimental.
103- it infers STDIN format by analysing line format on each line (doesn't infer separator though; defaults to `\t` and accepts user overrides) and computing the winner format.
104- it uses the awesome [ChartJS](http://www.chartjs.org/) library to plot the charts.
105- when input data is string-only, `chart` infers a "word frequency pie chart" use case.
106- should work on Linux/Mac/Windows thanks to [open-golang](https://github.com/skratchdot/open-golang).
107
108## Known issues
109
110- Javascript's floating point messes up y-axis https://github.com/marianogappa/chart/issues/15
111
112## Contribute
113
114PRs are greatly appreciated and are currently [being merged](https://github.com/marianogappa/chart/pull/3).
115If you have a use case that is not supported by `chart`, [I'd love to hear about it](https://github.com/marianogappa/chart/issues), but if it's too complex I'd recommend you to try [gnuplot](http://www.gnuplot.info/).
116