![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 the terminal. :bar_chart: Powered by [UnicodePlot](https://github.com/red-data-tools/unicode_plot.rb)
## Installation ``` gem install youplot ``` ## Quick Start `uplot [options] ` ### barplot ```sh curl -sL https://git.io/ISLANDScsv \ | sort -nk2 -t, \ | tail -n15 \ | uplot bar -d, -t "Areas of the World's Major Landmasses" ```

barplot

### histogram ```sh 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 ```sh 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 ```sh curl -sL https://git.io/IRIStsv \ | cut -f1-4 \ | uplot scatter -H -t IRIS ```

scatter

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

density

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

boxplot

### count ```sh 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

In this example, YouPlot counts the number of chromosomes where genes are located. * [GENCODE - Human Release](https://www.gencodegenes.org/human/) 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. ```sh 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 [options]` | Take input from stdin | | `uplot [options] data.tsv ...` | Take input from files | | `pipeline1 \| uplot -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 --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. ```sh 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] 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? ```sh uplot colors ``` ## Command line tools that are useful to use with YouPlot * [csvtk](https://github.com/shenwei356/csvtk) * [GNU datamash](https://www.gnu.org/software/datamash/) * [awk](https://www.gnu.org/software/gawk/) ## 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](https://github.com/red-data-tools/YouPlot/issues) * Fix bugs and [submit pull requests](https://github.com/red-data-tools/YouPlot/pulls) * Write, clarify, or fix documentation * English corrections by native speakers are welcome. * Suggest or add new features * Make a donation ### Development ```sh # 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](https://jypg.net/sampo_grafiikka) - Project logo creation * [yutaas](https://github.com/yutaas) - English proofreading ## License [MIT License](https://opensource.org/licenses/MIT).