Class: BioDSL::PlotHistogram

Inherits:

Object

Object
BioDSL::PlotHistogram

Includes:: AuxHelper

Defined in:: lib/BioDSL/commands/plot_histogram.rb

Overview

Plot a histogram of numerical values for a specified key.

plot_histogram create a histogram plot of the values for a specified key from all records in the stream. Plotting is done using GNUplot which allows for different types of output the default one being crufty ASCII graphics.

GNUplot’s facility for setting the xrange labels is used for numeric values, while for non-numeric values these are used for xrange labels.

GNUplot must be installed for plot_histogram to work. Read more here:

www.gnuplot.info/

Usage

plot_histogram(<key: <string>>[, value: <string>[, output: <file>
               [, force: <bool>[, terminal: <string>[, title: <string>
               [, xlabel: <string>[, ylabel: <string>
               [, ylogscale: <bool>[, test: <bool>]]]]]]]]])

Options

key: <string> - Key to use for plotting.
value: <string> - Alternative key who’s value to use.
output: <file> - Output file.
force: <bool> - Force overwrite existing output file.
terminal: <string> - Terminal for output: dumb|post|svg|x11|aqua|png|pdf
```
(default=dumb).
```
title: <string> - Plot title (default=“Histogram”).
xlabel: <string> - X-axis label (default=<key>).
ylabel: <string> - Y-axis label (default=“n”).
ylogscale: <bool> - Set y-axis to log scale.
test: <bool> - Output Gnuplot script instead of plot.

Examples

Here we plot a histogram of sequence lengths from a FASTA file:

read_fasta(input: "test.fna").plot_histogram(key: :SEQ_LEN).run

                                  Histogram
       +             +            +            +            +             +
  90 +++-------------+------------+------------+------------+-------------+++
      |                                                                    |
  80 ++                                                                  **++
      |                                                                  **|
  70 ++                                                                  **++
  60 ++                                                                  **++
      |                                                                  **|
  50 ++                                                                  **++
      |                                                                  **|
  40 ++                                                                  **++
      |                                                                  **|
  30 ++                                                                  **++
  20 ++                                                                  **++
      |                                                                  **|
  10 ++                                                                  **++
      |                                                              ******|
   0 +++-------------+------------+**--------**+--***-------+**--**********++
       +             +            +            +            +             +
       0             10           20           30           40            50
                                     SEQ_LEN

To render X11 output (i.e. instant view) use the terminal option:

read_fasta(input: "test.fna").
plot_histogram(key: :SEQ_LEN, terminal: :x11).run

To generate a PNG image and save to file:

read_fasta(input: "test.fna").
plot_histogram(key: :SEQ_LEN, terminal: :png, output: "plot.png").run

rubocop:disable ClassLength rubocop:enable LineLength

Constant Summary collapse

STATS =

%i(records_in records_out)

Instance Method Summary collapse

#initialize(options) ⇒ PlotHistogram constructor

Constructor for PlotHistogram.
#lmb ⇒ Proc

Return the command lambda for plot_histogram.

Methods included from AuxHelper

#aux_exist

Constructor Details

#initialize(options) ⇒ `PlotHistogram`

Constructor for PlotHistogram.

Parameters:

options (Hash) —

Options hash.

Options Hash (options):

:key (String, :Symbol)
:value (String, :Symbol)
:output (String)
:force (Booleon)
:terminal (String, :Symbol)
:title (String)
:xlabel (String)
:ylabel (String)
:ylogscale (Booleon)
:test (Booleon)

# File 'lib/BioDSL/commands/plot_histogram.rb', line 128

def initialize(options)
  @options     = options
  @key         = options[:key]
  @value       = options[:value]
  @count_hash  = Hash.new(0)
  @gp          = nil

  aux_exist('gnuplot')
  check_options
  defaults
end

Instance Method Details

#lmb ⇒ `Proc`

Return the command lambda for plot_histogram

Returns:

(Proc) —

command lambda.

# File 'lib/BioDSL/commands/plot_histogram.rb', line 143

def lmb
  lambda do |input, output, status|
    status_init(status, STATS)

    process_input(input, output)
    plot_create
    plot_output
  end
end