7.3 KiB
YouPlot is a command line tool for Unicode Plotting working with data from standard stream.
📊 Powered by UnicodePlot
Installation
gem install youplot
Quick Start
cat data.tsv | uplot <command> [options]
barplot
curl -sL https://git.io/ISLANDScsv \
| sort -nk2 -t, \
| tail -n15 \
| uplot bar -d, -t "Areas of the World's Major Landmasses"
histogram
echo -e "from numpy import random;" \
"n = random.randn(10000);" \
"print('\\\n'.join(str(i) for i in n))" \
| python \
| uplot hist --nbins 20
lineplot
curl -sL https://git.io/AirPassengers \
| cut -f2,3 -d, \
| uplot line -d, -w 50 -h 15 -t AirPassengers --xlim 1950,1960 --ylim 0,600
scatter
curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot scatter -H -t IRIS
density
curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot density -H -t IRIS
boxplot
curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot boxplot -H -t IRIS
count
In this example, YouPlot counts the number of chromosomes where the gene is located from the human gene annotation file and create a bar chart. The human gene annotation file can be downloaded from the following website.
cat gencode.v35.annotation.gff3 \
| grep -v '#' | grep 'gene' | cut -f1 | \
uplot count -t "The number of human gene annotations per chromosome" -c blue
Note: count is not very fast because it runs in a Ruby script.
This is fine if the data is small, that is, in most cases. However, if you want to visualize huge data, it is faster to use a combination of common Unix commands as shown below.
cat gencode.v35.annotation.gff3 | grep -v '#' | grep 'gene' | cut -f1 \
|sort | uniq -c | sort -nrk2 | awk '{print $2,$1}' \
| uplot bar -d ' ' -t "The number of human gene annotations per chromosome" -c blue
Usage
Why YouPlot?
Wouldn't it be a bit of pain to have to run R, Python, Julia, gnuplot or whatever REPL just to check your data? YouPlot is a command line tool for this purpose. With YouPlot, you can continue working without leaving your terminal and shell.
how to use YouPlot?
uplot is the shortened form of youplot. You can use either.
| Reads data from standard input | cat data.tsv | uplot <command> [options] |
| Reads data from files | uplot <command> [options] data.tsv ... |
| Outputs data from stdin to stdout | pipeline1 | uplot <command> -O | pipeline2 |
Where to output the plot?
By default, the plot is output to standard error output.
The output file or stream for the plot can be specified with the -o option.
Where to output the input data?
By default, the input data is not output anywhere.
The -O option, with no arguments, outputs the input data directly to the standard output. This is useful when passing data to a subsequent pipeline.
What types of plots are available?
The following sub-commands are available
| command | short | how it works |
|---|---|---|
| barplot | bar | draw a horizontal barplot |
| histogram | hist | draw a horizontal histogram |
| lineplot | line | draw a line chart |
| lineplots | lines | draw a line chart with multiple series |
| scatter | s | draw a scatter plot |
| density | d | draw a density plot |
| boxplot | box | draw a horizontal boxplot |
See Quick Start for count.
| command | short | how it works |
|---|---|---|
| count | c | draw a baplot based on the number of occurrences (slow) |
What if the header line is included?
If your input data contains a header line, you need to specify the -H option.
How to specify the delimiter?
Use the -d option. To specify a blank space, you can use uplot bar -d ' ' data.txt. The default value is tab, so you do not need to specify anything for tab-delimited text.
Is there a way to specify a specific column as the x-axis or y-axis?
Not yet. In principle, YouPlot treats the first column as the X axis and the second column as the Y axis. When working with multiple series, the first row is the X axis, the second row is series 1, the third row is series 2, and so on. If you pass only one column of data for line and bar, YouPlot will automatically use a sequential number starting from 1 as the X-axis. The --fmt xyy, --fmt xyxy and --fmt yx options give you a few more choices. See the youplot <command> --help for more details. YouPlot has limited functionality, but you can use shell scripts such as awk '{print $2, $1}' to swap lines.
How to view detailed command line options?
Use --help to print command-specific options.
uplot hist --help
Usage: uplot histogram [options] <in.tsv>
Options for histogram:
--symbol VAL character to be used to plot the bars
--closed VAL
-n, --nbins VAL approximate number of bins
Options:
...
How to view the list of available colors?
uplot colors
Contributing
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
Development
git clone https://github.com/your_name/GR.rb # Clone the Git repo
cd GR.rb
bundle install # Install the gem dependencies
bundle exec rake test # Run the test
bundle exec rake install # Installation from source code