2020-12-13 14:03:01 +08:00
2020-07-28 22:07:15 +08:00
2020-11-23 12:09:16 +08:00
[](https://badge.fury.io/rb/youplot)
[](https://rubydoc.info/gems/youplot)
2020-08-16 13:03:34 +08:00
[](LICENSE.txt)
2020-12-15 13:31:32 +08:00
[](https://zenodo.org/badge/latestdoi/283230219)
2020-07-29 11:43:00 +08:00
2020-12-16 16:40:50 +08:00
YouPlot is a command line tool for Unicode Plotting working with data from standard stream.
2020-07-29 11:16:10 +08:00
2020-07-29 20:36:27 +08:00
:bar_chart: Powered by [UnicodePlot ](https://github.com/red-data-tools/unicode_plot.rb )
2020-07-29 11:16:10 +08:00
2020-07-28 22:07:15 +08:00
## Installation
```
2020-11-23 12:09:16 +08:00
gem install youplot
2020-07-29 10:00:00 +08:00
```
2020-07-28 22:07:15 +08:00
2020-12-12 23:50:03 +08:00
## Quick Start
2020-07-28 22:07:15 +08:00
2020-12-16 17:18:29 +08:00
`cat data.tsv | uplot <command> [options]`
2020-12-12 23:50:03 +08:00
### barplot
2020-07-29 11:16:10 +08:00
```sh
2020-12-12 23:50:03 +08:00
curl -sL https://git.io/ISLANDScsv \
| sort -nk2 -t, \
| tail \
| uplot bar -d, -t "Areas of the World's Major Landmasses"
2020-07-29 11:16:10 +08:00
```
2020-12-13 08:52:53 +08:00
2020-12-12 23:50:03 +08:00
### histogram
2020-07-29 11:16:10 +08:00
2020-10-12 13:24:02 +08:00
```sh
2020-11-04 15:08:34 +08:00
echo -e "from numpy import random;" \
"n = random.randn(10000);" \
"print('\\\n'.join(str(i) for i in n))" \
2020-10-12 13:24:02 +08:00
| python \
| uplot hist --nbins 20
```
2020-12-13 08:52:53 +08:00
2020-10-12 13:04:36 +08:00
2020-12-12 23:50:03 +08:00
### lineplot
2020-08-16 13:03:34 +08:00
2020-10-12 13:24:02 +08:00
```sh
2020-12-12 23:50:03 +08:00
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
2020-10-12 13:24:02 +08:00
```
2020-12-13 08:52:53 +08:00
2020-10-12 13:04:36 +08:00
2020-12-12 23:50:03 +08:00
### scatter
2020-10-12 13:04:36 +08:00
2020-10-12 13:24:02 +08:00
```sh
2020-12-13 08:52:53 +08:00
curl -sL https://git.io/IRIStsv \
2020-12-12 23:50:03 +08:00
| cut -f1-4 \
| uplot scatter -H -t IRIS
2020-10-12 13:24:02 +08:00
```
2020-12-13 08:52:53 +08:00
2020-10-12 13:04:36 +08:00
2020-12-12 23:50:03 +08:00
### density
2020-10-12 13:04:36 +08:00
2020-10-12 13:24:02 +08:00
```sh
2020-12-13 08:52:53 +08:00
curl -sL https://git.io/IRIStsv \
2020-12-12 23:50:03 +08:00
| cut -f1-4 \
| uplot density -H -t IRIS
2020-10-12 13:24:02 +08:00
```
2020-12-13 08:52:53 +08:00
2020-10-12 13:04:36 +08:00
2020-12-12 23:50:03 +08:00
### boxplot
2020-11-04 14:37:19 +08:00
```sh
2020-12-13 08:52:53 +08:00
curl -sL https://git.io/IRIStsv \
2020-12-12 23:50:03 +08:00
| cut -f1-4 \
| uplot boxplot -H -t IRIS
2020-11-04 14:37:19 +08:00
```
2020-12-13 08:52:53 +08:00
2020-11-04 14:37:19 +08:00
2020-12-12 23:50:03 +08:00
### count
2020-10-13 17:40:56 +08:00
2020-12-13 08:52:53 +08:00
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.
2020-10-13 17:40:56 +08:00
2020-12-13 08:52:53 +08:00
* 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
2020-10-13 17:40:56 +08:00
```
2020-12-13 08:52:53 +08:00
2020-10-13 17:40:56 +08:00
2020-12-13 08:52:53 +08:00
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.
```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
```
2020-11-06 09:23:44 +08:00
2020-12-16 17:18:29 +08:00
## Usage
2020-12-16 17:47:55 +08:00
### 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.
2020-12-16 17:18:29 +08:00
### how to use YouPlot?
2020-12-16 17:47:55 +08:00
`uplot` is the shortened form of `youplot` . You can use either.
2020-12-16 17:18:29 +08:00
| | |
|-----------------------------------|------------------------------------------------|
| Reads data from standard input | `cat data.tsv \| uplot <command> [options]` |
2020-12-16 17:47:55 +08:00
| Reads data from files | `uplot <command> [options] data.tsv ...` |
2020-12-16 17:18:29 +08:00
| Outputs data from stdin to stdout | `pipeline1 \| uplot <command> -O \| pipeline2` |
2020-12-16 17:47:55 +08:00
### 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.
2020-10-13 17:40:56 +08:00
2020-12-16 17:47:55 +08:00
### What types of plots are available?
The following sub-commands are available
| command | short | how it works |
2020-12-16 15:51:07 +08:00
|-----------|-------|----------------------------------------|
| 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 |
2020-12-12 23:50:03 +08:00
2020-12-16 17:47:55 +08:00
See Quick Start for `count` .
| command | short | how it works |
|-----------|-------|----------------------------------------------------------|
| count | c | draw a baplot based on the number of occurrences (slow) |
2020-12-12 23:50:03 +08:00
2020-12-16 17:47:55 +08:00
### How to view detailed command line options
2020-11-06 09:29:17 +08:00
2020-11-06 09:37:29 +08:00
Use `--help` to print command-specific options.
2020-11-06 09:29:17 +08:00
`uplot hist --help`
2020-11-06 09:23:44 +08:00
2020-11-06 09:29:17 +08:00
```
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
2020-10-13 17:40:56 +08:00
2020-11-06 09:29:17 +08:00
Options:
...
2020-10-13 17:40:56 +08:00
```
2020-08-16 13:03:34 +08:00
2020-12-16 17:47:55 +08:00
### How to view the list of available colors?
2020-12-12 23:50:03 +08:00
```sh
uplot colors
```
2020-12-16 17:47:55 +08:00
## Contributing
* [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
* Suggest or add new features
2020-12-16 17:18:29 +08:00
2020-12-16 17:47:55 +08:00
### Development
2020-07-28 22:07:15 +08:00
2020-12-16 15:51:07 +08:00
```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
```
2020-10-12 13:24:02 +08:00
2020-07-28 22:07:15 +08:00
## License
2020-10-12 13:57:03 +08:00
[MIT License ](https://opensource.org/licenses/MIT ).
