class BioDSL::PlotMatches

Plot matches from the stream as a dotplot.

plot_matches is used to create dotplots of matches in the stream. plot_matches uses Q_BEG, Q_END, S_BEG, S_END from the stream. If strand information is available either by a STRAND key with the value ‘+’ or ‘-’, or by a DIRECTION key with the value ‘forward’ or ‘reverse’ then forward matches will be output in green and reverse matches in red (in all terminals, but dumb).

Default graphics are crufty ASCII and you probably want high resolution postscript or SVG output instead with is easy using the terminal option. Plotting is done using GNUplot which allows for different types of output.

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

www.gnuplot.info/

Usage

plot_matches([direction: <string>[, output: <file>[, force: <bool>
             [, terminal: <string>[, title: <string>[, xlabel: <string>
             [, ylabel: <string>[, test: <bool>]]]]]]]])

Options

Examples

Here we plot two matches from a table. The vector records are shown in the dump output:

BD.new.read_table(input: "test.tab").dump.plot_matches.run

{:Q_BEG=>0, :Q_END=>10, :S_BEG=>0, :S_END=>10, :STRAND=>"+"}
{:Q_BEG=>0, :Q_END=>10, :S_BEG=>0, :S_END=>10, :STRAND=>"-"}

                                     Matches
      +             +             +            +             +             +
  10 +>>>-----------+-------------+------------+-------------+----------->>>+
      |  >>>>       :             :            :             :       >>>>  |
      |      >>>>   :             :            :             :   >>>>      |
   8 ++..........>>>>>......................................>>>>>..........++
      |             : >>>>        :            :        >>>> :             |
      |             :     >>>>    :            :    >>>>     :             |
   6 ++.......................>>>>>............>>>>>.......................++
      |             :             :>>>>    >>>>:             :             |
      |             :             :    >>>>    :             :             |
      |             :             :>>>>    >>>>:             :             |
   4 ++.......................>>>>>............>>>>>.......................++
      |             :     >>>>    :            :    >>>>     :             |
      |             : >>>>        :            :        >>>> :             |
   2 ++..........>>>>>......................................>>>>>..........++
      |      >>>>   :             :            :             :   >>>>      |
      |  >>>>       :             :            :             :       >>>>  |
   0 +>>>-----------+-------------+------------+-------------+----------->>>+
      +             +             +            +             +             +
      0             2             4            6             8             10
                                        x

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

plot_matches(terminal: :x11).run

To generate a PNG image and save to file:

plot_matches(terminal: :png, output: "plot.png").run

rubocop:disable ClassLength rubocop:enable LineLength

Constants

STATS

Public Class Methods

new(options) click to toggle source

Constructor for PlotMatches.

@param options [Hash] Options hash. @option options [Symbol] :direction @option options [String] :output @option options [Boolean] :force @option options [Symbol] :terminal @option options [String] :title @option options [String] :xlabel @option options [String] :ylabel @option options [Boolean] :test

@return [PlotMatches] Class instance.

# File lib/BioDSL/commands/plot_matches.rb, line 130
def initialize(options)
  @options  = options
  @gp       = nil
  @style1   = {using: '1:2:3:4', with: 'vectors nohead ls 1'}
  @style2   = {using: '1:2:3:4', with: 'vectors nohead ls 2'}

  aux_exist('gnuplot')
  check_options
  defaults
end

Public Instance Methods

lmb() click to toggle source

Return lambda for command plot_matches.

@return [Proc] Command lambda.

# File lib/BioDSL/commands/plot_matches.rb, line 144
def lmb
  lambda do |input, output, status|
    status_init(status, STATS)

    @gp = GnuPlotter.new
    plot_defaults

    @gp.add_dataset(@style1) do |forward|
      @gp.add_dataset(@style2) do |reverse|
        input.each do |record|
          @status[:records_in] += 1

          plot_match(forward, reverse, record)

          process_output(output, record)
        end
      end
    end

    plot_output
  end
end

Private Instance Methods

check_options() click to toggle source

Check options.

# File lib/BioDSL/commands/plot_matches.rb, line 170
def check_options
  options_allowed(@options, :direction, :output, :force, :terminal, :title,
                  :xlabel, :ylabel, :test)
  options_allowed_values(@options, direction: [:forward, :reverse, :both])
  options_allowed_values(@options, terminal: [:dumb, :post, :svg, :x11,
                                              :aqua, :png, :pdf])
  options_allowed_values(@options, test: [nil, true, false])
  options_files_exist_force(@options, :output)
end
defaults() click to toggle source

Set default options.

# File lib/BioDSL/commands/plot_matches.rb, line 181
def defaults
  @options[:direction] ||= :both
  @options[:terminal] ||= :dumb
  @options[:title] ||= 'Matches'
  @options[:xlabel] ||= 'x'
  @options[:ylabel] ||= 'y'
end
plot_defaults() click to toggle source

Set plot default attributes.

# File lib/BioDSL/commands/plot_matches.rb, line 190
def plot_defaults
  @gp.set terminal:  @options[:terminal].to_s
  @gp.set title:     @options[:title]
  @gp.set xlabel:    @options[:xlabel]
  @gp.set ylabel:    @options[:ylabel]
  @gp.set autoscale: 'xfix'
  @gp.set autoscale: 'yfix'
  @gp.set style:     'fill solid 0.5 border'
  @gp.set xtics:     'border out'
  @gp.set ytics:     'border out'
  @gp.set grid:      :true
  @gp.set nokey:     :true
  @gp.set style:     'line 1 linetype 1 linecolor rgb "green" linewidth ' \
    '2 pointtype 6 pointsize default'
  @gp.set style:     'line 2 linetype 1 linecolor rgb "red"   linewidth ' \
    '2 pointtype 6 pointsize default'
end
plot_match(forward, reverse, record) click to toggle source

Add match data to forward or reverse dataset.

@param forward [GnuPlotter::DataSet] Forward matches. @param reverse [GnuPlotter::DataSet] Reverse matches. @param record [Hash] BioDSL record.

# File lib/BioDSL/commands/plot_matches.rb, line 213
def plot_match(forward, reverse, record)
  return unless record[:Q_BEG] && record[:Q_END] &&
                record[:S_BEG] && record[:S_END]
  @status[:matches_in] += 1

  q_len = record[:Q_END] - record[:Q_BEG]
  s_len = record[:S_END] - record[:S_BEG]

  plot_match_strand(forward, reverse, record, q_len, s_len)
  plot_match_direction(forward, reverse, record, q_len, s_len)
end
plot_match_direction(forward, reverse, record, q_len, s_len) click to toggle source

Add match data to forward or reverse dataset depeding on match direction.

@param forward [GnuPlotter::DataSet] Forward matches. @param reverse [GnuPlotter::DataSet] Reverse matches. @param record [Hash] BioDSL record. @param q_len [Integer] Length of query match. @param s_len [Integer] Length of subject match.

# File lib/BioDSL/commands/plot_matches.rb, line 249
def plot_match_direction(forward, reverse, record, q_len, s_len)
  return unless record[:DIRECTION]

  if record[:DIRECTION] == 'forward'
    forward << [record[:Q_BEG], record[:S_BEG], q_len, s_len]
  else
    reverse << [record[:Q_END], record[:S_BEG], -1 * q_len, s_len]
  end
end
plot_match_strand(forward, reverse, record, q_len, s_len) click to toggle source

Add match data to forward or reverse dataset depeding on match strand.

@param forward [GnuPlotter::DataSet] Forward matches. @param reverse [GnuPlotter::DataSet] Reverse matches. @param record [Hash] BioDSL record. @param q_len [Integer] Length of query match. @param s_len [Integer] Length of subject match.

# File lib/BioDSL/commands/plot_matches.rb, line 232
def plot_match_strand(forward, reverse, record, q_len, s_len)
  return unless record[:STRAND]

  if record[:STRAND] == '+'
    forward << [record[:Q_BEG], record[:S_BEG], q_len, s_len]
  else
    reverse << [record[:Q_END], record[:S_BEG], -1 * q_len, s_len]
  end
end
plot_output() click to toggle source

Output plot data

# File lib/BioDSL/commands/plot_matches.rb, line 260
def plot_output
  @gp.set output: @options[:output] if @options[:output]

  if @options[:test]
    $stderr.puts @gp.to_gp
  elsif @options[:terminal] == :dumb
    puts @gp.plot
  else
    @gp.plot
  end
end
process_output(output, record) click to toggle source

Emit record to output stream if defined.

@param output [Enumerator::Yielder] Output stream. @param record [Hash] BioDSL record.

# File lib/BioDSL/commands/plot_matches.rb, line 276
def process_output(output, record)
  return unless output
  output << record
  @status[:records_out] += 1
end