---

YouPlot is a command line tool that draws plots in the terminal.

📊 Powered by UnicodePlot

Installation

gem install youplot

Quick Start

uplot <command> [options] <data.tsv>

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

cat gencode.v35.annotation.gff3 \
| grep -v '#' | grep 'gene' | cut -f1 \
| uplot count -t "The number of human gene annotations per chromosome"  -c blue

In this example, YouPlot counts the number of chromosomes where genes are located.

• GENCODE - Human Release

Note: count is not very fast because it runs in a Ruby script. This is fine in most cases, as long as the data size is small. 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 -nrk1 \
| uplot bar --fmt yx -d ' ' -t "The number of human gene annotations per chromosome"  -c blue

Usage

Why YouPlot?

Wouldn't it be a 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.

Command	Description
cat data.tsv | uplot <command> [options]	Take input from stdin
uplot <command> [options] data.tsv ...	Take input from files
pipeline1 | uplot <command> -O | pipeline2	Outputs data from stdin to stdout

Subcommands

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 barplot based on the number of occurrences (slow)

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 shown 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 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. You do not need to use -d option for tab-delimited text since the default value is tab.

Is there a way to specify a column as the x-axis or y-axis?

Not yet. YouPlot treats the first column as the X axis and the second column as the Y axis. When working with multiple series, the first column is the X axis, the second column is series Y1, the third column is series Y2, 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.

• --fmt xyy --fmt xyxy --fmt yx options give you a few more choices. See youplot <command> --help for more details.

• Use awk '{print $2, $1}' to swap lines.

• Use paste to concatenate series.

How to plot real-time data?

Experimental progressive mode is currently under development.

ruby -e 'loop{puts rand(100)}' | uplot line --progress

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         side of the intervals to be closed [left]
    -n, --nbins VAL          approximate number of bins

Options:
...

How to view the list of available colors?

uplot colors

Command line tools that are useful to use with YouPlot

• csvtk
• GNU datamash
• awk

Contributing

YouPlot is a library under development, so even small improvements like typofix are welcome! Please feel free to send us your pull requests.

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
  • English corrections by native speakers are welcome.
• Suggest or add new features
• Make a donation

Development

# fork the main repository by clicking the Fork button. 
git clone https://github.com/your_name/YouPlot
bundle install             # Install the gem dependencies
bundle exec rake test      # Run the test
bundle exec rake install   # Installation from source code

Acknowledgements

• sampo grafiikka - Project logo creation
• yutaas - English proofreading

License

MIT License.