![Build Status](https://github.com/red-data-tools/YouPlot/workflows/test/badge.svg) [![Gem Version](https://badge.fury.io/rb/youplot.svg)](https://badge.fury.io/rb/youplot) [![Docs Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://rubydoc.info/gems/youplot) [![The MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt) [![DOI](https://zenodo.org/badge/283230219.svg)](https://zenodo.org/badge/latestdoi/283230219) YouPlot is a command line tool that draws plots in a terminal. :bar_chart: Powered by [UnicodePlot](https://github.com/red-data-tools/unicode_plot.rb)

Installation

gem install youplot

Quick Start

  • cat data.tsv | uplot <command> [options] or
  • 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"

barplot

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

histogram

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

lineplot

scatter

curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot scatter -H -t IRIS

scatter

density

curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot density -H -t IRIS

density

boxplot

curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot boxplot -H -t IRIS

boxplot

count

In this example, YouPlot counts the number of chromosomes where the gene is located from the human gene annotation file and it creates 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

count

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 -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 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 [options]`
uplot <command> [options] data.tsv ... Take input from files
`pipeline1 \ uplot -O \

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 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 barplot 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. 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

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

License

MIT License.