DOCSEARCHbyAlgolia
Submit Docs

YouPlot

repository·main·Indexed 26 days ago

https://github.com/red-data-tools/youplot

A Ruby library and command-line tool for generating terminal-based plots from Delimiter-Separated Values (DSV) data. It supports various plot types including bar, line, scatter, density, boxplot, and histograms using the UnicodePlot backend. Features include progressive real-time data visualization, YAML configuration via youplotrc, and support for multiple data formats like xyy and xyxy.

Tokens
3.2K
Snippets
2
Records
24
Agent score
89%

What's inside YouPlot

  1. Quick Start with YouPlot

    main

    YouPlot follows the pattern: uplot <command> [options] <data.tsv>. It can accept data via stdin or files.

    Barplot

    Draw a horizontal barplot. For example, to plot landmass areas from a CSV:

    curl -sL https://git.io/ISLANDScsv \
| sort -nk2 -t, \
| tail -n15 \
| uplot bar -d, -t "Areas of the World's Major Landmasses"

    Histogram

    Draw a horizontal histogram. Example using Python generated data:

    echo -e "from numpy import random;" \
        "n = random.randn(10000);"  \
        "print('\
'.join(str(i) for i in n))" \
| python3 \
| uplot hist --nbins 20

    Lineplot

    Draw a line chart. Example with AirPassengers data:

    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 Plot

    Draw a scatter plot. Example using IRIS data:

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

    Density Plot

    Draw a density plot:

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

    Boxplot

    Draw a horizontal boxplot:

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

    Count

    Draw a barplot based on the number of occurrences of values. Note that count is implemented in Ruby and may be slow for large datasets.

    ps aux | awk '{print $1}' | uplot count
    uplot <command> [options] <data.tsv>

  2. Install YouPlot

    main

    You can install YouPlot using several package managers:

    Homebrew (macOS):

    brew install youplot

    RubyGems:

    gem install youplot

    Nix:

    nix shell nixpkgs#youplot

    Guix:

    guix install youplot

    Conda (requires Ruby and compilers):

    conda install -c conda-forge ruby
conda install -c conda-forge compilers
gem install youplot
    brew install youplot

  4. Configure YouPlot via configuration files

    main

    YouPlot can be configured using YAML files. Configuration settings are applied with the following priority:

    1. CLI options
    2. Config file
    3. DEFAULTS

    By default, YouPlot searches for configuration files in these locations:

    • The file specified by the MYYOUPLOTRC environment variable
    • .youplot.yml or .youplotrc in the current directory
    • $HOME/.youplotrc or $HOME/.youplot.yml
    • $HOME/.config/youplot/youplotrc or $HOME/.config/youplot/youplot.yml

    You can explicitly specify a configuration file using the --config flag.

  5. Run YouPlot in progressive mode

    main

    YouPlot supports a progressive mode, which allows for real-time, incremental updates to a plot as new data rows arrive via standard input.

    Key constraints and behaviors:

    • Output destination: In progressive mode, you cannot output to a file. The output must be a TTY or an IO-like object that responds to print and flush (e.g., STDOUT).
    • Data handling: The mode handles headers and transposing based on your provided options. If --headers is used, the first row is consumed as the header.
    • Visuals: The command manages the terminal cursor (making it invisible during updates and restoring it on exit) and uses ANSI escape codes to redraw the plot in place, preventing screen clutter.

  6. Configure YouPlot Output and Data Handling

    main

    Use these options to control where plots and data are sent:

    • Output the plot (-o): By default, plots are sent to stderr. To output to stdout, use -o - or no argument (e.g., uplot s -o |).
    • Output the input data (-O): By default, input data is not shown. To pass input data to stdout (useful for pipelines), use -O - or no argument (e.g., uplot s -O |).
    • Header (-H): Specify this if your input data contains a header line.
    • Delimiter (-d): Specify the delimiter. The default is a tab. For example, for space-delimited files: uplot bar -d ' ' data.txt.
    • Real-time data (-p or --progress): Experimental mode for progressive data visualization. Example: ruby -e 'loop{puts rand(100)}' | uplot line --progress

  7. Available YouPlot Subcommands

    main

    The following subcommands are available for uplot (or youplot):

    commandshortdescription
    barplotbardraw a horizontal barplot
    histogramhistdraw a horizontal histogram
    lineplotlinedraw a line chart
    lineplotslinesdraw a line chart with multiple series
    scattersdraw a scatter plot
    densityddraw a density plot
    boxplotboxdraw a horizontal boxplot
    countcdraw a barplot based on the number of occurrences (slow)
    colorscolorshow the list of available colors

  8. Configure Axis and Data Formats

    main

    YouPlot defaults to treating the first column as the X axis and the second column as the Y axis. For multiple series, the first column is X, and subsequent columns are Y1, Y2, etc.

    • Format (--fmt): Use --fmt to specify data layout. Supported options include --fmt xyy, --fmt xyxy, and --fmt yx. (Note: -x and -y options may be used for specific columns in the future).
    • Column Swapping: To swap columns, you can use standard Unix tools like awk '{print $2, $1}' before piping to uplot.
    • Configuration File: You can specify default options in a YAML configuration file (youplotrc). Run uplot --config to see information about your configuration.

  11. Generate a line plot with the UnicodePlot backend

    main

    Use the line method to create line plots.

    Behavior:

    • Single Series: If only one series is provided, it is treated as sequential data (the index is the x-axis).
    • Multiple Series:
      • Default: Assumes the first two series are x and y respectively.
      • fmt == 'yx': Assumes the first two series are y and x respectively.

    Parameters:

    • data: The data object.
    • params: Plot parameters.
    • fmt: (Optional) String 'yx' to swap x/y assumption.

  12. Prepare data for barplots with `YouPlot::Aggregation.count_values`

    main

    Use YouPlot::Aggregation.count_values to transform an array of values into a format suitable for barplots. It counts the occurrences of each unique element, sorts them by frequency in descending order, and returns the result as a transposed array (an array of arrays where each inner array contains [label, count]).

    Options:

    • tally: (Boolean): If true (default), uses Ruby's native Enumerable#tally. If false, attempts to use value_counts (requires Enumerable::Statistics).
    • reverse: (Boolean): If true, reverses the final sorted order.