rubylabs 0.9.0 → 0.9.1

data/lib/randomlab.rb

@@ -1,58 +1,104 @@
+module RubyLabs
 
 =begin rdoc
   
 == RandomLab
 
-Random number generators and associated methods.
-
-=end
+The RandomLab module has definitions of classes and methods used in the projects for Chapter 9
+of <em>Explorations in Computing</em>.  The module has methods used in experiments with pseudorandom 
+number generators.
 
-=begin
-  TODO number line -- mini-histogram, e.g. second tick drawn above first? else explain in lab manual / reference why two values per tickmark
-  TODO another thing for documentation: diff between p.random(x,y) and random(x,y) [latter uses Ruby's PRNG]
 =end
-
-module RubyLabs
-	
+  
 module RandomLab
   
   require "permute.rb"
   
+  NumberLine = Struct.new(:line, :npoints, :options)
+  Histogram = Struct.new(:bins, :max, :keys, :counts, :base, :options)
+  DotPlot = Struct.new(:max, :options)
+
+  @@numberLineOptions = { 
+    :lineThickness => 3, 
+    :lineColor => '#777777', 
+    :tickHeight => 20, 
+    :tickWidth => 1,
+    :tickColor => '#0000FF',
+  }
+  
+  @@histogramOptions = {
+    :binColor => '#000080',
+    :boxIncrement => 8.0,
+    :rescaleTrigger => 50,
+  }
+  
+  @@dotPlotOptions = {
+    :dotColor => '#000080',
+    :dotRadius => 1.0,
+  }
+  
+  @@drawing = nil
+  @@delay = 0.01
+  
 =begin rdoc
-  Pseudo-random number generator.  Constraints on a, c, and m:
-  *  c and m must be relatively prime
-  *  a-1 divisible by prime factors of m
-  *  if m is multiple of 4, a-1 must also be a multiple of 4
 
-  Note: some good values (for small m) from Numerical Recipes:
-      m = 53125, a = 171, c = 11213
+== PRNG
+
+A PRNG object is a pseudorandom number generator based on the mixed congruential method.
+Sequences generated by a PRNG are defined by three constants, named +a+, +c+, and +m+.
+If <tt>x[i]</tt> is the current item in the sequence, the equation for the next item 
+<tt>x[i+1]</tt> is
+   x[i+1] = (a * x[i] + c) % m
+
 =end
 
   class PRNG
   
     attr_accessor :a, :c, :m, :x
 
+    # Make a new pseudorandom number generator using constants +a+, +c+, and +m+.
+    # 
+    # Example -- a random number generator that has the full period of m = 1000 but some
+    # surprising correlations between successive values:
+    #   p = PRNG.new(81, 337, 1000)
+    #   => #<RandomLab::PRNG a: 81 c: 337 m: 1000>
+    # 
+    # Example: a better PRNG, using values suggested in <em>Numerical Recipes</em> (Press, et al):
+    #   >> p = PRNG.new(171, 11213, 53125)
+    #   => #<RandomLab::PRNG a: 171 c: 11213 m: 53125>
+        
     def initialize(a, c, m)
       @a = a
       @c = c
       @m = m
       @x = 0
     end
+    
+    # Return the current item in the pseudorandom sequence (the most recently generated random
+    # number).
   
     def state
       return @x
     end
+    
+    # Set the state of the pseudorandom sequence to +val+.
   
     def seed(val)
       @x = val
     end
-  
+    
+    # Get the next pseudorandom number in the sequence defined by this PRNG object.
+    #--
     # :begin :advance
     def advance
       @x = (@x * @a + @c) % @m    
     end
     # :end :advance
   
+    # Get a random integer between +min+ and +max+ from this PRNG object.  Calls
+    # advance the get the next value from the pseudorandom sequence, then maps it
+    # to an integer between +min+ and +max+.
+    #--
     # :begin :random
     def random(min, max)
       return nil if max <= min
@@ -61,6 +107,7 @@ module RandomLab
     end
     # :end :random
   
+    # Create a string that describes the attributes of this PRNG object.
     def inspect
       sprintf "#<RandomLab::PRNG a: #{@a} c: #{@c} m: #{@m}>"
     end
@@ -69,7 +116,12 @@ module RandomLab
   
   end # class PRNG
 
-# :begin :prng_sequence
+  # Return an array of +m+ numbers defined by the pseudorandom sequence with
+  # parameters +a+, +c+, and +m+.  The first number in the sequence is 0, and
+  # the remaining numbers are defined by the recurrence 
+  #   x[i+1] = (a * x[i] + c) % m
+  #--
+  # :begin :prng_sequence
   def prng_sequence(a, c, m)
     seq = [0]
     (m-1).times do
@@ -77,35 +129,34 @@ module RandomLab
     end
     return seq
   end
-# :end :prng_sequence
-
-=begin rdoc
-  Make a new deck of cards
-=end
+  # :end :prng_sequence
 
+  # Make a new deck of cards.  Returns an array of 52 card objects, arranged
+  # in order from card #0 (the ace of spades) through card #51 (the two of clubs).
+  
   def new_deck
     (0..51).map { |i| Card.new(i) }
   end
   
   
-=begin rdoc
-  Compute the probability of a duplicate item in a collection of n items
-  drawn from the range [1..d].  Example: call pdup(5,52) to compute the 
-  probability if drawing the same card twice when sampling with replacement
-  5 times from a deck of 52 cards.
-=end
+  # Compute the probability of a duplicate item in a collection of +n+ items
+  # drawn from the range [1..d].  
+  #
+  # Example -- to compute the 
+  # probability of drawing the same card twice when sampling with replacement
+  # 5 times from a deck of 52 cards:
+  #   >> pdup(5, 52)
+  #   => 0.179716221420819
 
   def pdup(n, d)
     return 1.0 if n > d
     return 1.0 - (1..(n-1)).inject(1.0) { |p, k| p * (1.0 - (k / 52.0)) }
   end
   
-=begin rdoc
-  A "helper method" that can be called via a probe, to print the contents
-  of an array during the execution of the permute! method
-=end
-
-# Note: permute! moved to own source file, permute.rb
+  # A helper method intended to be called via a probe to print the contents
+  # of an array during the execution of the <tt>permute!</tt> method.  The arguments
+  # are the array to display, the location of a left bracket, and the item
+  # location where the item next to the bracket will be moved on the next swap.
 
   def brackets(a, i, r)
     res = "#{r}: "
@@ -121,19 +172,17 @@ module RandomLab
     return res
   end
 
-
-=begin rdoc
-  Classify a poker hand -- returns a symbol describing a hand.  Return values:
-    :pair
-    :two_pair
-    :three_of_a_kind
-    :full_house
-    :straight
-    :flush
-    :four_of_a_kind
-    :straight_flush
-=end
-
+  # Given an array of 5 Card objects, determine what type of poker hand is
+  # represented by the cards.  The return value is a symbol, e.g. <tt>:pair</tt>,
+  # <tt>:full_house</tt>, etc. (call poker_rankings to see the complete list of
+  # symbols).
+  #
+  # Example (assuming +d+ is a complete deck of 52 Card objects):
+  #   >> h = permute!(d).first(5)
+  #   => [AH, 6S, 7C, JH, AC]
+  #   >> poker_rank(h)
+  #   => :pair
+ 
   def poker_rank(a)
     rcount = Array.new(Card::Ranks.length, 0)
     scount = Array.new(Card::Suits.length, 0)
@@ -158,28 +207,35 @@ module RandomLab
       return :pair
     end
   end
+  
+  # Return a list of symbols used to classify poker hands.
 
   def poker_rankings
     return [:high_card, :pair, :two_pair, :three_of_a_kind, :straight, :flush, :full_house, :four_of_a_kind, :straight_flush]
   end
 
+  # Initialize a Hash object with keys that are poker rank symbols and values that are all initially 0.
+  # Used in experiments that count the number of times various hands are dealt.
+  #
+  # Example:
+  #   >> poker_counts
+  #   => {:flush=>0, :full_house=>0, ... :high_card=>0}
+  
   def poker_counts
     h = Hash.new
     poker_rankings.each { |x| h[x] = 0 }
     return h
   end
 
-
 =begin rdoc
-  Class to represent cards from a standard 52-card deck.  Includes comparators
-  to sort by rank or suit.
-  
-  Call Card.new to get a random card, or Card.new(id) to get a specific card
-  where id is a number between 0 and 51.
-=end
 
-# To test the expression that assigns suits and ranks:
-#   52.times { |x| puts (x/13).to_s + "  " + (x%13).to_s }
+== Card
+
+A Card object represents a single card from a standard 52-card deck.  The two
+attributes of a card are its rank (represented by a symbol such as :ace, :king, :three, etc)
+and its suit (:spades, :hearts, etc).
+
+=end
 
   class Card
     attr_accessor :rank, :suit
@@ -192,16 +248,43 @@ module RandomLab
       Ranks = [:ace, :king, :queen, :jack, :ten, :nine, :eight, :seven, :six, :five, :four, :three, :two]
     end
   
+    # Create a new Card object.  Cards are ordered from 0 to 51, with 0 being the ace of spades
+    # and 51 being the two of clubs.  If no argument is passed to new, a random card is chosen.
+    # If an +id+ between 0 and 51 is passed the specified card is created.
+    #
+    # Example:
+    #    >> Card.new
+    #    => 5H
+    #    >> Card.new(0)
+    #    => AS
+    #    >> Card.new(1)
+    #    => KS
+    #    >> Card.new(51)
+    #    => 2C
+
     def initialize(id = nil)
       id = rand(52) if id.nil?
       raise "card must be between 0 and 51" if id < 0 || id > 51
       @suit = Suits[id / 13]
       @rank = Ranks[id % 13]
     end
+    
+    # Compare this Card with Card x.  Two cards are equal if they have the same
+    # suit and same rank.
   
     def ==(x)
       return @suit == x.suit && @rank == x.rank
     end
+    
+    # Define the sort ordering for Card objects.  Cards are compared first by suit,
+    # and then by rank.  The result of sorting a hand (and array of Card objects) is
+    # the common situation for most card games, where cards are grouped by suit.
+    #
+    # Example (assuming +d+ is a complete deck of 52 cards):
+    #    >> h = permute!(d).first(13)
+    #    => [2C, QS, 8S, 6C, 10H, JS, AD, AS, 7D, 8D, JC, 4C, AH]
+    #    >> h.sort
+    #    => [AS, QS, JS, 8S, AH, 10H, AD, 8D, 7D, JC, 6C, 4C, 2C]
   
     def <=>(x)
       r0 = Ranks.index(@rank); r1 = Ranks.index(x.rank)
@@ -215,6 +298,11 @@ module RandomLab
   
     @@outputform = :utf8
   
+    # Make a string to display a Card objects on the terminal. Checks
+    # Ruby's $KCODE global variable to see if the system is using UTF-8.  If so, the code for a glyph that
+    # shows a spade, heart, diamond, or club is inserted into the string, otherwise a letter is
+    # used.
+
     def inspect
       s = ""
       s << case @rank
@@ -252,7 +340,6 @@ module RandomLab
         end
       end
       return s
-      # "#{@rank} #{@suit}"
     end
   
     alias to_s inspect
@@ -267,21 +354,18 @@ module RandomLab
   
   end # class Card
 
-=begin rdoc
-	Visualization methods called by students to test a PRNG object:
-
-		view_numberline(n)	      make a number line for integers between 0 and n-1
-		tick_mark(i)			        draw a tick mark at location i on the number line
-
-    view_histogram(n, max)    make a histogram with n bins for value from 0 to max
-    view_histogram(a)         make a histogram with one bin for each item in a
-    update_bin(x)             add 1 to the count of items in bin x
-    get_counts                get a copy of the bins (array of counts)
-    
-    view_dotplot(n)           initialize an n x n dotplot
-    plot_point(x,y)           add a dot at (x,y) to the dotplot
-=end
-
+  # Initialize the RubyLabs Canvas with a drawing of a number line for integers from 0 to +npoints+-1.
+  # Options that control the appearance of the display, and their default values, are:
+  #   :lineThickness => 3
+  #   :lineColor => '#777777'
+  #   :tickHeight => 20
+  #   :tickWidth => 1
+  #   :tickColor => '#0000FF'
+  #
+  # Example:
+  #   >> view_numberline(500, :lineColor => 'blue', :lineThickness => 1)
+  #   => true
+  
   def view_numberline(npoints, userOptions = {})
     Canvas.init(500, 100, "RandomLab::NumberLine")
     options = @@numberLineOptions.merge(userOptions)
@@ -290,21 +374,48 @@ module RandomLab
     return true
   end
 
-	def tick_mark(i)
-		if @@drawing.class != NumberLine
-			puts "call view_numberline to initialize the number line"
-		elsif i < 0 || i >= @@drawing.npoints
-			puts "tick_mark: 0 <= i < #{@@drawing.npoints}"
-		else
-		  x0, y0, x1, y1 = @@drawing.line.coords
-			tx = (i.to_f / @@drawing.npoints) * (x1-x0)
-			ty = y0 - @@drawing.options[:tickHeight]
-			Canvas::Line.new(tx, y0, tx, ty, :width => @@drawing.options[:tickWidth], :fill => @@drawing.options[:tickColor])
-			sleep(@@delay)
-		end
-		return true
-	end
-	
+  # Draw a tick mark on the RubyLabs Canvas, provided the canvas has been initialized with a call to
+  # view_numberline.  
+  
+  def tick_mark(i)
+    if @@drawing.class != NumberLine
+      puts "call view_numberline to initialize the number line"
+    elsif i < 0 || i >= @@drawing.npoints
+      puts "tick_mark: 0 <= i < #{@@drawing.npoints}"
+    else
+      x0, y0, x1, y1 = @@drawing.line.coords
+      tx = (i.to_f / @@drawing.npoints) * (x1-x0)
+      ty = y0 - @@drawing.options[:tickHeight]
+      Canvas::Line.new(tx, y0, tx, ty, :width => @@drawing.options[:tickWidth], :fill => @@drawing.options[:tickColor])
+      sleep(@@delay)
+    end
+    return true
+  end
+  
+  # Initialize the RubyLabs Canvas to show a histogram with the specified bins.  In the 
+  # initial drawing each bin is represented by a rectangle one pixel tall, i.e. a horizontal line.  
+  # As items are added to a bin the rectangle will grow in height.  If any rectangle reaches the
+  # maximum height, all the rectangles are rescaled so the bins can continue to grow.
+  #
+  # The argument to view_histogram can either be an integer, which specifies the number of bins,
+  # or an array of symbols, in which case there will be one bin for each symbol.  If the argument is an integer,
+  # a second argument can specify a maximum data value; for example, calling <tt>view_histogram(10,100)</tt>
+  # will make a histogram with 10 bins for numbers between 0 and 99, so that data values 0 through
+  # 9 will go in the first bin, 10 through 19 in the second bin, and so on.
+  #
+  # Display options and their default values are:
+  #   :binColor => '#000080'
+  #   :boxIncrement => 8.0
+  #   :rescaleTrigger => 50
+  #
+  # Example:  make a histogram for the numbers between 0 and 5:
+  #   >> view_histogram(6)
+  #   => true
+  # Example:  make a histogram to count the number of times each type of poker hand is seen in an
+  # experiment:
+  #   >> view_histogram(poker_rankings, :binColor => 'darkgreen')
+  #   => true
+  
   def view_histogram(*args)
     begin
       if args[0].class == Array
@@ -341,7 +452,10 @@ module RandomLab
 
     return true  
   end
-	
+  
+  # Update the bin for data item +x+, presuming the RubyLabs Canvas has been initialized to show
+  # a histogram for data of this type.  The bin for +x+ increases in height.  If it reaches
+  # the maximum height, rescale all the bins and increase the maximum height.
 
   def update_bin(x)
     if @@drawing.class != Histogram
@@ -380,6 +494,8 @@ module RandomLab
     sleep(@@delay)
     return true
   end
+  
+  # Return an array of counts for the bins in the histogram currently on the RubyLabs Canvas.
 
   def get_counts
     if @@drawing.class == Histogram
@@ -389,55 +505,45 @@ module RandomLab
       return nil
     end
   end
-
+  
+  # Initialize the RubyLabs Canvas to show a dot plot with +npoints+ in both the +x+
+  # and +y+ dimension.  Drawing options and their defaults are
+  #   :dotColor => '#000080'
+  #   :dotRadius => 1.0
+  #
+  # Example:  intialize the drawing for a 250 x 250 dot plot with green dots:
+  #   >> view_dotplot(250, :dotColor => 'darkgreen')
+  #   => true
+  
   def view_dotplot(npoints, userOptions = {})
     Canvas.init(500, 500, "RandomLab::DotPlot")
     options = @@dotPlotOptions.merge(userOptions)
     @@drawing = DotPlot.new(npoints, options)
     return true
   end
+  
+  # Add a point at location 'x', 'y' to the dot plot on the RubyLabs Canvas.
+  #
+  # Example:  if the canvas was initialized to show a 250 x 250 plot, this call
+  # will display a point in the center of the drawing:
+  #   >> plot_point(125,125)
+  #   => nil
 
   def plot_point(x,y)
     if @@drawing.class != DotPlot
       puts "call view_dotplot to initialize a dot plot"
-		elsif x < 0 || x >= @@drawing.max || y < 0 || y >= @@drawing.max
-			puts "plot_point: 0 <= x, y < #{@@drawing.max}"
-		else
+    elsif x < 0 || x >= @@drawing.max || y < 0 || y >= @@drawing.max
+      puts "plot_point: 0 <= x, y < #{@@drawing.max}"
+    else
       px = (x.to_f / @@drawing.max) * Canvas.width
       py = (y.to_f / @@drawing.max) * Canvas.height
       r = @@drawing.options[:dotRadius]
       color = @@drawing.options[:dotColor]
       Canvas::Circle.new( px, py, r, :outline => color, :fill => color ) 
-		end
-		return nil
+    end
+    return nil
   end
-  
-  NumberLine = Struct.new(:line, :npoints, :options)
-  Histogram = Struct.new(:bins, :max, :keys, :counts, :base, :options)
-  DotPlot = Struct.new(:max, :options)
-
-  @@numberLineOptions = { 
-    :lineThickness => 3, 
-    :lineColor => '#777777', 
-    :tickHeight => 20, 
-    :tickWidth => 1,
-    :tickColor => '#0000FF',
-  }
-  
-  @@histogramOptions = {
-    :binColor => '#000080',
-    :boxIncrement => 8.0,
-    :rescaleTrigger => 50,
-  }
-  
-  @@dotPlotOptions = {
-    :dotColor => '#000080',
-    :dotRadius => 1.0,
-  }
-  
-  @@drawing = nil
-  @@delay = 0.01
-  
+    
 end # RandomLab
 
 end # RubyLabs