sequence_logo 1.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sequence_logo.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ilya Vorontsov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# SequenceLogo
+
+SequenceLogo is a tool for drawing sequence logos of motifs. It gets Positional Count Matrices(PCMs) at input and generates png-logos for motif. Also one can create logo for reverse complement or even generate logos for a whole collection of motifs.
+Sequence logos are a graphical representation of an amino acid or nucleic acid multiple sequence alignment developed by Tom Schneider and Mike Stephens. Each logo consists of stacks of symbols, one stack for each position in the sequence. The overall height of the stack indicates the sequence conservation at that position, while the height of symbols within the stack indicates the relative frequency of each amino or nucleic acid at that position. In general, a sequence logo provides a richer and more precise description of, for example, a binding site, than would a consensus sequence (see http://weblogo.berkeley.edu/)
+ 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'sequence_logo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sequence_logo
+
+## Usage
+
+SequenceLogo consists of three tools:
+* The most flexible tool **pmflogo** generates single logo for a single motif. It has quite complicated usage format:
+  
+    pmflogo \<input_file\> \<output_logo_filename\> [words_count] [x_unit=100] [y_size=200] [icd_mode=discrete|weblogo] [revcomp=no|yes] [scheme=nucl_simpa] [paper_mode=no|yes] [threshold_lines=yes|no]
+  
+  Any optional argument can be set as 'default', skipped parameters are also substituted as default (in example below icd_mode is default, and also scheme, paper_mode and threshold_lines): `pmflogo motif.pcm logo.png default 30 60 default yes`
+
+  Required arguments:
+    * input_file can be either in PCM format (file extension should be .pat or .pcm), or in FASTA format (file extensions: .mfa, .fasta, .plain), or in SMall BiSMark format (.xml), or in IUPAC format (any other extension).
+    * output_logo_filename is output logo file with format .png (extension should be included into name) which will be generated
+    
+  Optional parameters:
+    * words_count [=default] is a float number that represents alignment weight. If words_count is set to 'default' - it'd be obtained from input (if it's PCM or IUPAC). In some cases (when PPM is used) words_count can't be obtained. In such a case discrete logo can't be drawn, and weblogo will be drawn instead.
+    * x_unit - width of a single letter
+    * y_size - full height of an image
+    * icd_mode - information content mode
+    * revcomp - create logo for a direct or reverse-complement orientation
+    * scheme - nucleotide images folder name (by default only one scheme is used)
+    * paper_mode - if paper_mode is true then threshold lines won't be drawn but a border is drawn instead
+    * threshold_lines - lines on levels: icd2of4, icdThc(=icd3of4), icdTlc, - relative to icd4of4
+  
+* Tool **generate_logo** generates two logos - direct and reverse-complement with some reasonable defaults for a single motif and puts a logo in a logo_folder
+  
+    generate_logo \<motif_filename\> [logo_folder = directory of input motif file]
+
+* Tool **create_all_logos** generates two logos - direct and reverse-complement with some reasonable defaults for each motif in a folder and puts all logos in a logo_folder
+
+    create_all_logos \<motifs_folder> \<logo_folder>
+ 
+ 
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+Copyright (c) 2011-2012 Ivan Kulakovskiy(author), Ilya Vorontsov(refactoring and gemification)

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+# require 'rspec/core/rake_task'
+# RSpec::Core::RakeTask.new

data/bin/create_all_logos

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require 'sequence_logo/exec/create_all_logos.rb'

data/bin/generate_logo

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require 'sequence_logo/exec/generate_logo.rb'

data/bin/pmflogo

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require 'sequence_logo/exec/pmflogo.rb'

data/lib/sequence_logo.rb

@@ -0,0 +1,7 @@
+require 'sequence_logo/version'
+require 'sequence_logo/pmflogo_lib'
+
+module SequenceLogo
+  AssetsPath = File.join(File.dirname(__FILE__), 'sequence_logo', 'assets')
+  # Your code goes here...
+end

data/lib/sequence_logo/exec/create_all_logos.rb

@@ -0,0 +1,25 @@
+require 'sequence_logo'
+require 'fileutils'
+
+motifs_folder = ARGV.shift
+unless motifs_folder && Dir.exist?(motifs_folder)
+  puts('Specified input folder not exists')
+  exit(1)
+end
+
+logo_folder = ARGV.shift
+unless logo_folder
+  puts('Output logo folder must be specified')
+  exit(1)
+end
+
+Dir.mkdir(logo_folder)  unless Dir.exist?(logo_folder)
+
+Dir.glob(File.join(motifs_folder, '*')).to_enum.each do |filename|
+  filename_wo_ext = File.basename(filename, File.extname(filename))
+  direct_output = File.join(logo_folder,"#{filename_wo_ext}_direct.png")
+  revcomp_output = File.join(logo_folder,"#{filename_wo_ext}_revcomp.png")
+
+  draw_logo(filename, direct_output, words_count: 'default', x_unit: 30, y_size: 60, icd_mode: 'discrete', revcomp: 'direct')
+  draw_logo(filename, revcomp_output, words_count: 'default', x_unit: 30, y_size: 60, icd_mode: 'discrete', revcomp: 'revcomp')
+end

data/lib/sequence_logo/exec/generate_logo.rb

@@ -0,0 +1,18 @@
+require 'sequence_logo'
+require 'fileutils'
+
+filename = ARGV.shift
+unless filename && File.exist?(filename)
+  puts 'Existing input file should be specified'
+  exit(1)
+end
+
+logo_dir = ARGV.shift || File.dirname(filename)
+FileUtils.mkdir(logo_dir) unless Dir.exist?(logo_dir)
+
+filename_wo_ext = File.basename(filename, File.extname(filename))
+direct_output = File.join(logo_dir,"#{filename_wo_ext}_direct.png")
+revcomp_output = File.join(logo_dir,"#{filename_wo_ext}_revcomp.png")
+
+draw_logo(filename, direct_output,  x_unit: 30, y_size: 60, revcomp: 'direct')
+draw_logo(filename, revcomp_output, x_unit: 30, y_size: 60, revcomp: 'revcomp')

data/lib/sequence_logo/exec/pmflogo.rb

@@ -0,0 +1,26 @@
+# pmflogo <input_file> <output_logo_filename> [words_count] [x_unit=100] [y_size=200] [icd_mode=discrete|weblogo] [revcomp=no|yes] [scheme=nucl_simpa] [paper_mode=no|yes] [threshold_lines=yes|no]
+# Any optional argument can be set as 'default' e.g.
+#   pmflogo motif.pcm logo.png default 30 60 default yes
+# skipped parameters are also substituted as default (in example above icd_mode is default, and also scheme, paper_mode and threshold_lines)
+
+require 'sequence_logo'
+
+if ARGV.size < 2
+  puts('At least two arguments must be specified, see usage of pmflogo')
+  exit(2)
+end
+
+input_file, output_logo_filename = ARGV.shift(2)
+unless File.exist?(input_file)
+  puts('Specified input file not exists')
+  exit(1)
+end
+
+options = {}
+options[:words_count] = ARGV.shift
+options[:x_unit], options[:y_size] = ARGV.shift(2)
+options[:icd_mode], options[:revcomp], options[:scheme], options[:paper_mode], options[:threshold_lines] = ARGV.shift(5)
+
+options.reject!{|k,v| v.nil?}
+
+draw_logo(input_file, output_logo_filename, options)

data/lib/sequence_logo/pmflogo_lib.rb

@@ -0,0 +1,193 @@
+require 'sequence_logo/ytilib'
+require 'RMagick'
+
+class PPM
+  def get_ppm
+    self
+  end
+  
+  def get_line(v)
+    ( (v - icd4of4) / icd4of4 ).abs
+  end
+  
+  def get_logo(icd_mode)
+    if icd_mode == :weblogo
+      get_logo_weblogo
+    else
+      get_logo_discrete
+    end
+  end
+
+
+  def get_logo_weblogo
+    rseq = []
+    @matrix['A'].each_index { |i|
+      rseq << 2 + ['A','C','G','T'].inject(0) { |sum, l|
+        pn = @matrix[l][i]
+        sum += (pn == 0) ? 0 : pn * Math.log(pn) / Math.log(2)
+      }
+    }
+    
+    mat = {'A'=>[], 'C'=>[], 'G'=>[], 'T'=>[]}
+    @matrix['A'].each_index { |i|
+      ['A','C','G','T'].each { |l|
+        mat[l][i]= @matrix[l][i] * rseq[i] / 2 # so we can handle a '2 bit' scale here
+      }
+    }
+    
+    mat
+  end
+
+  def get_logo_discrete
+    checkerr("words count is undefined") { !words_count }
+    
+    rseq = []
+    @matrix['A'].each_index { |i|
+      rseq << (icd4of4 == 0 ? 1.0 : ( (infocod(i) - icd4of4) / icd4of4 ).abs)
+    }
+    
+    mat = {'A'=>[], 'C'=>[], 'G'=>[], 'T'=>[]}
+    @matrix['A'].each_index { |i|
+      ['A','C','G','T'].each { |l| 
+        mat[l][i] = @matrix[l][i] * rseq[i]
+      }
+    }
+    
+    mat
+  end
+end
+
+def get_ppm_from_file(in_file_name, words_count)
+  case File.ext_wo_name(in_file_name)
+  when 'pat', 'pcm'
+    pm = PM.load(in_file_name)
+    pm.fixwc  if pm.words_count
+  when 'mfa', 'fasta', 'plain'
+    pm = PM.new_pcm(Ytilib.read_seqs2array(in_file_name))
+  when 'xml'
+    pm = PM.from_bismark(Bismark.new(in_file_name).elements["//PPM"])
+  when in_file_name
+    pm = PPM.from_IUPAC(in_file_name.upcase)
+  end
+  pm = pm.get_ppm
+  pm.words_count = words_count  if words_count
+  pm
+end
+
+def create_canvas(x_size, y_size, icd_mode, paper_mode, threshold_lines, pm)
+  
+  i_logo = Magick::ImageList.new
+  if paper_mode
+    i_logo.new_image(x_size, y_size)
+  else
+    if icd_mode == :discrete
+      i_logo.new_image(x_size, y_size, Magick::HatchFill.new('white', 'white'))
+      if threshold_lines
+        dr = Magick::Draw.new
+        dr.fill('transparent')
+        
+        dr.stroke_width(y_size / 200.0)
+        dr.stroke_dasharray(7,7)
+        
+        line2of4 = y_size - pm.get_line(pm.icd2of4) * y_size
+        lineThc = y_size - pm.get_line(pm.icdThc) * y_size
+        lineTlc = y_size - pm.get_line(pm.icdTlc) * y_size
+        
+        dr.stroke('silver')
+        dr.line(0, line2of4, x_size, line2of4)
+        dr.line(0, lineThc, x_size, lineThc)
+        dr.line(0, lineTlc, x_size, lineTlc)
+        
+        dr.draw(i_logo)
+      end
+    else
+      i_logo.new_image(x_size, y_size, Magick::HatchFill.new('white', 'bisque'))
+    end
+  end
+  i_logo
+end
+
+def letter_images(scheme_dir)
+  if File.exist?(File.join(scheme_dir,'a.png'))
+    lp = {'A' => File.join(scheme_dir,'a.png'), 'C' => File.join(scheme_dir,'c.png'), 'G' => File.join(scheme_dir,'g.png'), 'T' => File.join(scheme_dir,'t.png')}
+  elsif File.exist?(File.join(scheme_dir,'a.gif'))
+    lp = {'A' => File.join(scheme_dir,'a.gif'), 'C' => File.join(scheme_dir,'c.gif'), 'G' => File.join(scheme_dir,'g.gif'), 'T' => File.join(scheme_dir,'t.gif')}
+  else
+    raise "Scheme not exists in folder #{scheme_dir}"
+  end
+  i_letters = Magick::ImageList.new(lp['A'], lp['C'], lp['G'], lp['T'])
+end
+
+def draw_letters_on_canvas(i_logo, i_letters, matrix, y_size, x_unit)
+  matrix['A'].each_index { |i|
+    y_pos = 0
+    sorted_letters = ['A', 'C', 'G', 'T'].collect { |letter| {:score => matrix[letter][i], :letter => letter} }.sort_by { |pair| pair[:score] }.collect { |pair| pair[:letter] }.reverse
+    sorted_letters.each { |letter|
+      next if y_size * matrix[letter][i] <= 1
+      letter_index = {'A' => 0, 'C' => 1, 'G' => 2, 'T' => 3}[letter]
+      y_block = (y_size * matrix[letter][i]).round
+      i_logo << i_letters[letter_index].dup.resize(x_unit, y_block)
+      y_pos += y_block
+      i_logo.cur_image.page = Magick::Rectangle.new(0, 0, i * x_unit, y_size - y_pos )
+    }
+  }
+end
+
+
+def draw_logo(in_file_name, out_file_name, options = {})
+  default_options = { words_count: nil,
+                      x_unit: 100,
+                      y_size: 200,
+                      icd_mode: 'discrete',
+                      revcomp: false,
+                      scheme: 'nucl_simpa',
+                      paper_mode: false,
+                      threshold_lines: true }
+
+  options = options.reject{|k,v| v == 'default' || v == :default}
+  options = default_options.merge( options )
+
+  x_unit = options[:x_unit].to_i
+  y_size = options[:y_size].to_i
+  icd_mode = options[:icd_mode].to_sym
+  scheme = options[:scheme]
+  
+  words_count = options[:words_count]
+  words_count = words_count.to_f  if words_count
+  
+  revcomp = options[:revcomp]
+  revcomp = false  if revcomp == 'no' || revcomp == 'false' || revcomp == 'direct'
+  
+  paper_mode = options[:paper_mode]
+  paper_mode = false  if paper_mode == 'no' || paper_mode == 'false'
+
+  threshold_lines = options[:threshold_lines]
+  threshold_lines = false  if threshold_lines == 'no' || threshold_lines == 'false'
+  
+  ########################
+  
+  pm = get_ppm_from_file(in_file_name, words_count)
+  checkerr("bad input file") { pm == nil }
+  
+  x_size = x_unit * pm.length
+  
+  
+  unless pm.words_count
+    report "words count for PM is undefined, assuming weblogo mode"
+    icd_mode = :weblogo
+  end
+  
+  i_logo = create_canvas(x_size, y_size, icd_mode, paper_mode, threshold_lines, pm)
+  
+  pm.revcomp! if revcomp
+  matrix = pm.get_logo(icd_mode)
+
+  scheme_dir = File.join(SequenceLogo::AssetsPath, scheme)
+  i_letters = letter_images(scheme_dir)
+  draw_letters_on_canvas(i_logo, i_letters, matrix, y_size, x_unit)
+
+  i_logo = i_logo.flatten_images
+  i_logo.cur_image.border!(x_unit / 100 + 1, x_unit / 100 + 1, icd_mode == :discrete ? "green" : "red") if paper_mode
+
+  i_logo.write(out_file_name)
+end

data/lib/sequence_logo/version.rb

@@ -0,0 +1,3 @@
+module SequenceLogo
+  VERSION = "1.0.2"
+end

data/lib/sequence_logo/ytilib.rb

@@ -0,0 +1,9 @@
+require 'sequence_logo/ytilib/ytilib'
+require 'sequence_logo/ytilib/addon'
+require 'sequence_logo/ytilib/iupac'
+require 'sequence_logo/ytilib/pm'
+require 'sequence_logo/ytilib/pmsd'
+require 'sequence_logo/ytilib/randoom'
+require 'sequence_logo/ytilib/bismark'
+require 'sequence_logo/ytilib/hack1'
+require 'sequence_logo/ytilib/infocod'

data/lib/sequence_logo/ytilib/addon.rb

@@ -0,0 +1,247 @@
+#!/usr/bin/ruby
+
+def File.ext_wo_name(what)
+  return what if what.rindex(".") == nil
+  what = File.basename(what)
+  "#{what}"[what.rindex(".")+1..-1]
+end
+
+def File.name_wo_ext(what)
+  return what if what.rindex(".") == nil
+  what = File.basename(what)
+  "#{what}"[0...what.rindex(".")]
+end
+
+class Float
+  def round_to(x)
+    (self * 10**x).round.to_f / 10**x
+  end
+  
+  def cut_to(x)
+    (self.abs * 10**x).floor.to_f * (self == 0.0 ? 0 : self/self.abs).round / 10**x
+  end
+end
+
+class Array
+  def shuffle
+    arr = self.dup
+    arr.size.downto 2 do |j|
+      r = rand j
+      arr[j-1], arr[r] = arr[r], arr[j-1]
+    end
+    arr
+  end
+  
+  def shuffle!
+    (size - 1).downto 1 do |i|
+      j = rand(i + 1)
+      self[i], self[j] = self[j], self[i]
+    end
+    self
+  end
+  
+  def average
+    self.empty? ? nil : self.inject(0) { |sum,s| sum += s } / self.size
+  end
+  alias mean average
+  
+  def variance
+    return self.collect { |s| s*s }.average - average**2
+  end
+  
+  def sum
+    self.inject(self[0]) { |sum,s| sum += s} - self[0]
+  end
+
+end
+
+class String
+  
+  def compl!
+    self.tr!("acgtACGT", "tgcaTGCA")
+    return self
+  end
+  
+  def compl
+    return self.tr("acgtACGT", "tgcaTGCA")
+  end
+  
+  alias comp! compl!
+  alias complement! compl!
+  alias comp compl
+  alias complement compl
+  
+  def revcomp
+    return comp.reverse
+  end
+  
+  def revcomp!
+    return comp!.reverse!
+  end
+  
+  def to_id
+    return self.gsub(/[^.\w]/, '_').upcase
+  end
+  
+end
+
+# Also this can be done is a more sophisticated way
+=begin
+String.class_eval do    
+  def to_id
+    return self.gsub(/[^.\w]/, '_') 
+  end   
+end
+=end
+
+class String
+  # The opposite of String::next / String::succ. It is impossible to be a
+  # *complete* opposite because both "9".next = "10" and "09".next = "10";
+  # if going backwards from "10" there's no way to know whether the result
+  # should be "09" or "9". Where the first ranged character is about to
+  # underflow and the next character is within the same range the result
+  # is shrunk down - that is, "10" goes to "9", "aa" goes to "z"; any non-
+  # range prefix or suffix is OK, e.g. "+!$%10-=+" goes to "+!$%9-=+".
+  # Items in the middle of a string don't do this - e.g. "12.10" goes to
+  # "12.09", to match how "next" would work as best as possible.
+  #
+  # The standard "next" function works on strings that contain *no*
+  # alphanumeric characters, using character codes. This implementation
+  # of "prev" does *not* work on such strings - while strings may contain
+  # any characters you like, only the alphanumeric components are operated
+  # upon.
+  #
+  # Should total underflow result, "nil" will be returned - e.g. "00".prev
+  # returns 'nil', as does "a".prev. This is done even if there are other
+  # characters in the string that were not touched - e.g. "+0.0".prev
+  # also returns "nil". Broadly speaking, a "nil" return value is used for
+  # any attempt to find the previous value of a string that could not have
+  # been generated using "next" in the first place.
+  #
+  # As with "next" sometimes the result of "prev" can be a little obscure
+  # so it is often best to try out things using "irb" if unsure. Note in
+  # particular that software revision numbers do not necessarily behave
+  # predictably, because they don't with "next"! E.g. "12.4.9" might go to
+  # "12.4.10" for a revision number, but "12.4.9".next = "12.5.0". Thus
+  # "12.5.0".prev = "12.4.9" and "12.4.10".prev = "12.4.09" (because the
+  # only way to make "12.4.10" using "next" is to start at "12.4.09").
+  #
+  # Since 'succ' (successor) is an alias for 'next', so 'pred'
+  # (predecessor) is an alias for 'prev'.
+  #
+  def prev(collapse = false)
+    str        = self.dup
+    early_exit = false
+    any_done   = false
+    ranges     = [
+                   ('0'[0]..'9'[0]),
+                   ('a'[0]..'z'[0]),
+                   ('A'[0]..'Z'[0]),
+                   nil
+                 ]
+
+    # Search forward for the first in-range character. If found check
+    # to see if that character is "1", "a" or "A". If it is, record
+    # its index (from 0 to string length - 1). We'll need this if
+    # underflows wrap as far as the found byte because in that case
+    # this first found byte should be deleted ("aa..." -> "z...",
+    # "10..." -> "9...").
+
+    first_ranged = nil
+
+    for index in (1..str.length)
+      byte = str[index - 1]
+
+      # Determine whether or not the current byte is a number, lower case
+      # or upper case letter. We expect 'select' to only find one matching
+      # array entry in 'ranges', thus we dereference index 0 after the
+      # 'end' to put a matching range from within 'ranges' into 'within',
+      # or 'nil' for any unmatched byte.
+
+      within = ranges.select do |range|
+        range.nil? or range.include?(byte)
+      end [0]
+
+      unless within.nil?
+        case within.first
+          when '0'[0]
+            match_byte = '1'[0]
+          else
+            match_byte = within.first
+        end
+
+        first_ranged = index - 1 if (byte == match_byte)
+        first_within = within
+        break
+      end
+    end
+
+    for index in (1..str.length)
+
+      # Process the input string in reverse character order - fetch the
+      # bytes via negative index.
+
+      byte = str[-index]
+
+      within = ranges.select do |range|
+        range.nil? or range.include?(byte)
+      end [0]
+
+      # Skip this letter unless within a known range. Otherwise note that
+      # at least one byte was able to be processed.
+
+      next if within.nil?
+      any_done = true
+
+      # Decrement the current byte. If it is still within its range, set
+      # the byte and bail out - we're finished. Flag the early exit. If
+      # the byte is no longer within range, wrap the character around
+      # and continue the loop to carry the decrement to an earlier byte.
+
+      byte = byte - 1
+
+      if (within.include? byte)
+        str[-index] = byte
+        early_exit  = true
+        break
+      else
+        str[-index] = within.last
+
+        # If we've just wrapped around a character immediately after the
+        # one found right at the start ('0', 'a' or 'A') then this first
+        # ranged character should be deleted (so "10" -> "09"
+
+        if (first_ranged != nil and first_within.include?(byte + 1) and (first_ranged - str.length) == -(index + 1))
+          str.slice!(-(index + 1))
+          early_exit = true
+          break
+        end
+      end
+
+    end # From outer 'for' loop
+
+    # If we did process at least one byte but we did not exit early, then
+    # the loop completed due to carrying a decrement to other bytes. This
+    # means an underflow condition - return 'nil'.
+
+    if (any_done == true and early_exit == false)
+      return nil
+    else
+      return str
+    end
+  end
+
+  # As (extended) String::pred / String::prev, but modifies the string in
+  # place rather than returning a copy. If underflow occurs, the string
+  # will be unchanged. Returns 'self'.
+  #
+  def prev!
+    new_str = prev
+    self.replace(new_str) unless new_str.nil?
+    return self
+  end
+
+  alias pred  prev
+  alias pred! prev!
+
+end