mirror of
https://github.com/red-data-tools/YouPlot.git
synced 2025-05-06 23:21:13 +08:00
258 lines
8.2 KiB
Markdown
258 lines
8.2 KiB
Markdown
<p align="center">
|
|
<img src="logo.svg" width="60%" height="60%" />
|
|
</p>
|
|
|
|
|
|
[](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 <command> [options]` or
|
|
* `uplot <command> [options] <data.tsv>`
|
|
|
|
### barplot
|
|
|
|
```sh
|
|
curl -sL https://git.io/ISLANDScsv \
|
|
| sort -nk2 -t, \
|
|
| tail -n15 \
|
|
| uplot bar -d, -t "Areas of the World's Major Landmasses"
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="barplot" src="https://user-images.githubusercontent.com/5798442/101999903-d36a2d00-3d24-11eb-9361-b89116f44122.png">
|
|
</p>
|
|
|
|
### 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
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="histogram" src="https://user-images.githubusercontent.com/5798442/101999820-21cafc00-3d24-11eb-86db-e410d19b07df.png">
|
|
</p>
|
|
|
|
### 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
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="lineplot" src="https://user-images.githubusercontent.com/5798442/101999825-24c5ec80-3d24-11eb-99f4-c642e8d221bc.png">
|
|
</p>
|
|
|
|
### scatter
|
|
|
|
```sh
|
|
curl -sL https://git.io/IRIStsv \
|
|
| cut -f1-4 \
|
|
| uplot scatter -H -t IRIS
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="scatter" src="https://user-images.githubusercontent.com/5798442/101999827-27284680-3d24-11eb-9903-551857eaa69c.png">
|
|
</p>
|
|
|
|
### density
|
|
|
|
```sh
|
|
curl -sL https://git.io/IRIStsv \
|
|
| cut -f1-4 \
|
|
| uplot density -H -t IRIS
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="density" src="https://user-images.githubusercontent.com/5798442/101999828-2abbcd80-3d24-11eb-902c-2f44266fa6ae.png">
|
|
</p>
|
|
|
|
### boxplot
|
|
|
|
```sh
|
|
curl -sL https://git.io/IRIStsv \
|
|
| cut -f1-4 \
|
|
| uplot boxplot -H -t IRIS
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="boxplot" src="https://user-images.githubusercontent.com/5798442/101999830-2e4f5480-3d24-11eb-8891-728c18bf5b35.png">
|
|
</p>
|
|
|
|
### 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
|
|
```
|
|
|
|
<p align="center">
|
|
<img alt="count" src="https://user-images.githubusercontent.com/5798442/101999832-30b1ae80-3d24-11eb-96fe-e5000bed1f5c.png">
|
|
</p>
|
|
|
|
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.
|
|
|
|
| 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 |
|
|
|
|
### 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.
|
|
|
|
```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] <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?
|
|
|
|
```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/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).
|