[](https://badge.fury.io/rb/youplot)
[](https://rubydoc.info/gems/youplot)
[](LICENSE.txt)
[](https://zenodo.org/badge/latestdoi/283230219)
YouPlot is a command line tool for Unicode Plotting working with data from standard stream.
:bar_chart: Powered by [UnicodePlot](https://github.com/red-data-tools/unicode_plot.rb)
## Installation
```
gem install youplot
```
## Quick Start
* `cat data.tsv | uplot [options]` or
* `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"
```
### 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
```
### 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
```
### scatter
```sh
curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot scatter -H -t IRIS
```
### density
```sh
curl -sL https://git.io/IRIStsv \
| cut -f1-4 \
| uplot density -H -t IRIS
```
### boxplot
```sh
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 it creates a bar chart. The human gene annotation file can be downloaded from the following website.
* https://www.gencodegenes.org/human/
```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
```
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 -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.
| | |
|-----------------------------------|------------------------------------------------|
| Reads data from standard input | `cat data.tsv \| uplot [options]` |
| Reads data from files | `uplot [options] data.tsv ...` |
| Outputs data from stdin to stdout | `pipeline1 \| uplot -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 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. 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 `youplot --help` for more details. YouPlot has limited functionalities, but you can use shell scripts such as `awk '{print $2, $1}'` to swap lines.
### 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
```
## 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/kojix2/youplot/issues)
* Fix bugs and [submit pull requests](https://github.com/kojix2/youplot/pulls)
* Write, clarify, or fix documentation
* English corrections by native speakers are welcome.
* Suggest or add new features
### Development
```sh
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
```
### Acknowledgements
* [Red Data Tools](https://github.com/red-data-tools) - Technical support
* [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).