more_math 1.5.0 → 1.6.0

data/lib/more_math/permutation.rb

@@ -1,13 +1,38 @@
 require 'more_math/ranking_common'
 
 module MoreMath
+  # A permutation represents a rearrangement of elements in a set. Permutations
+  # are ranked in lexicographic order, allowing efficient enumeration and
+  # indexing.
+  #
+  # @example Create a permutation of size 3
+  #   perm = Permutation.new(3)
+  #   # => #<Permutation:0x6ae34 @last=5, @rank=0, @size=3>
+  #
+  # @example Create a permutation with specific rank
+  #   perm = Permutation.new(3, 5)
+  #   # => #<Permutation:0x6ae34 @last=5, @rank=5, @size=3>
+  #
+  # @example Get the permutation as an array of indices
+  #   perm = Permutation.new(3, 5)
+  #   perm.value
+  #   # => [2, 1, 0]
+  #
+  # @example Project onto actual data
+  #   perm = Permutation.new(3, 5)
+  #   perm.project(['a', 'b', 'c'])
+  #   # => ['c', 'b', 'a']
   class Permutation
     include Enumerable
     include Comparable
     include RankingCommon
 
-    # Creates a new Permutation instance of <code>size</code>
-    # (and ranked with <code>rank</code>).
+    # Creates a new Permutation instance of <code>size</code> (and ranked with
+    # <code>rank</code>). Creates a new Permutation instance of size (and
+    # ranked with rank).
+    #
+    # @param size [Integer] The size of the permutation
+    # @param rank [Integer] The rank of the permutation (default: 0)
     def initialize(size, rank = 0)
       @size, self.rank = size, rank
       @last = factorial(size) - 1
@@ -17,6 +42,9 @@ module MoreMath
     # <code>indices</code>, that should consist of a permutation of Fixnums
     # in the range of <code>0</code> and <code>indices.size - 1</code>. This is
     # for example the result of a call to the Permutation#value method.
+    #
+    # @param indices [Array<Integer>] array of indices representing a permutation
+    # @return [Permutation] new permutation instance
     def self.from_value(indices)
       indices = indices.clone
       obj = new(indices.size)
@@ -29,6 +57,10 @@ module MoreMath
     # Creates a new Permutation instance from the Array of Arrays
     # <code>cycles</code>. This is for example the result of a
     # call to the Permutation#cycles method .
+    #
+    # @param cycles [Array<Array<Integer>>] array of cycles
+    # @param max [Integer] maximum element index (default: 0)
+    # @return [Permutation] new permutation instance
     def self.from_cycles(cycles, max = 0)
       indices = Array.new(max)
       cycles.each do |cycle|
@@ -45,6 +77,10 @@ module MoreMath
     # collection as the default Permutation#project data object. A
     # collection should respond to size, [], and []=. The Permutation
     # instance will default to rank 0 if none is given.
+    #
+    # @param collection [Object] collection to use for projection
+    # @param rank [Integer] the rank of this permutation (default: 0)
+    # @return [Permutation] new permutation instance
     def self.for(collection, rank = 0)
       perm = new(collection.size, rank)
       perm.instance_variable_set(:@collection, collection)
@@ -53,12 +89,17 @@ module MoreMath
 
     # Shortcut to generate the identity permutation that has
     # Permutation#size <code>n</code>.
+    #
+    # @param n [Integer] size of identity permutation
+    # @return [Permutation] identity permutation of size n
     def self.identity(n)
       new(n)
     end
 
     # Returns the identity permutation that has the same Permutation#size as this
     # instance.
+    #
+    # @return [Permutation] identity permutation of same size
     def identity
       self.class.new(size)
     end
@@ -67,6 +108,10 @@ module MoreMath
     # Both arguments must be the same length and must contain the same
     # elements.  If these arrays contain duplicate elements, the solution
     # will not be unique.
+    #
+    # @param a [Array] initial array of elements
+    # @param b [Array] target array of elements
+    # @return [Permutation] permutation that maps a to b
     def self.for_mapping(a, b)
       a.size == b.size or
         raise ArgumentError, "Initial and final lists must be the same length"
@@ -83,6 +128,9 @@ module MoreMath
 
     # Computes the nth power (ie the nth repeated permutation) of this instance.
     # Negative powers are taken to be powers of the inverse.
+    #
+    # @param n [Integer] power to raise permutation to
+    # @return [Permutation] result of permutation raised to power n
     def power(n)
       if n.respond_to?(:to_int)
         n = n.to_int
@@ -102,6 +150,9 @@ module MoreMath
     # instance. That implies that the indices produced by a call to the
     # Permutation#value method of this instance is the permutation ranked with
     # this new <code>rank</code>.
+    #
+    # @param m [Integer] new rank value
+    # @return [Integer] assigned rank
     def rank=(m)
       @rank = m % factorial(size)
     end
@@ -114,6 +165,8 @@ module MoreMath
     #  # => #<Permutation:0x6ae34 @last=719, @rank=312, @size=6>
     #  perm.value
     #  # => [2, 4, 0, 1, 3, 5]
+    #
+    # @return [Array<Integer>] array of indices representing this permutation
     def value
       unrank_indices(@rank)
     end
@@ -124,30 +177,47 @@ module MoreMath
     # with Permutation.for the collection used to create
     # it is used as a data object.
     #
-    # <b>Example:</b>
-    #  perm = Permutation.new(6, 312)
-    #  # => #<Permutation:0x6ae34 @last=719, @rank=312, @size=6>
-    #  perm.project("abcdef")
-    #  # => "ceabdf"
+    # @example
+    #   perm = Permutation.new(6, 312)
+    #   # => #<Permutation:0x6ae34 @last=719, @rank=312, @size=6>
+    #   perm.project("abcdef")
+    #   # => "ceabdf"
+    #
+    # @param data [Object] data to project onto (optional)
+    # @return [Object] projected result
     def project(data = (@collection if defined? @collection))
       data or raise ArgumentError, "a collection is required to project"
       raise ArgumentError, "data size is != #{size}!" if data.size != size
-      projection = data.clone
+      projection = data.dup
       value.each_with_index { |i, j| projection[j] = data[i] }
       projection
     end
 
-    # Compares to Permutation instances according to their Permutation#size
-    # and the Permutation#rank.
+    # Compare this permutation with another based on size and rank.
+    #
+    # This method implements the comparison operator for Permutation objects,
+    # allowing them to be sorted and compared using standard Ruby comparison
+    # operators. The comparison is first done by size, then by rank for permutations
+    # of the same size.
     #
-    # The mixed in methods from the Comparable module rely on this method.
+    # @param other [Object] the other permutation to compare with
+    # @return [Integer] -1 if this permutation should be ordered before the other,
+    #   0 if they are equal, 1 if this permutation should be ordered after the other
     def <=>(other)
-      size <=> other.size.zero? || rank <=> other.rank
+      sc = size <=> other.size
+      if sc.zero?
+        rank <=> other.rank
+      else
+        sc
+      end
     end
 
     # Returns true if this Permutation instance and the other have the same
     # value, that is both Permutation instances have the same Permutation#size
     # and the same Permutation#rank.
+    #
+    # @param other [Object] object to compare with
+    # @return [Boolean] true if equal
     def eql?(other)
       self.class == other.class && size == other.size && rank == other.rank
     end
@@ -155,12 +225,16 @@ module MoreMath
     alias == eql?
 
     # Computes a unique hash value for this Permutation instance.
+    #
+    # @return [Integer] hash value
     def hash
       size.hash ^ rank.hash
     end
 
-    # Switchtes this Permutation instance to the inverted permutation.
+    # Switches this Permutation instance to the inverted permutation.
     # (See Permutation#compose for an example.)
+    #
+    # @return [Permutation] self after inversion
     def invert!
       indices = unrank_indices(rank)
       inverted = Array.new(size)
@@ -173,6 +247,8 @@ module MoreMath
 
     # Returns the inverted Permutation of this Permutation instance.
     # (See Permutation#compose for an example.)
+    #
+    # @return [Permutation] inverted permutation
     def invert
       clone.invert!
     end
@@ -184,16 +260,20 @@ module MoreMath
     # composed with it's inverted permutation yields
     # the identity permutation, the permutation with rank 0.
     #
-    # <b>Example:</b>
-    #  p1 = Permutation.new(5, 42)
-    #  # => #<Permutation:0x75370 @last=119, @rank=42, @size=5>
-    #  p2 = p1.invert
-    #  # => #<Permutation:0x653d0 @last=119, @rank=51, @size=5>
-    #  p1.compose(p2)
-    #  => #<Permutation:0x639a4 @last=119, @rank=0, @size=5>
-    # Or a little nicer to look at:
-    #  p1 * -p1
-    #  # => #<Permutation:0x62004 @last=119, @rank=0, @size=5>
+    # @example
+    #   p1 = Permutation.new(5, 42)
+    #   # => #<Permutation:0x75370 @last=119, @rank=42, @size=5>
+    #   p2 = p1.invert
+    #   # => #<Permutation:0x653d0 @last=119, @rank=51, @size=5>
+    #   p1.compose(p2)
+    #   => #<Permutation:0x639a4 @last=119, @rank=0, @size=5>
+    #
+    #   # Or a little nicer to look at:
+    #   p1 * -p1
+    #   # => #<Permutation:0x62004 @last=119, @rank=0, @size=5>
+    #
+    # @param other [Permutation] permutation to compose with
+    # @return [Permutation] composed permutation
     def compose(other)
       size == other.size or raise ArgumentError,
         "permutations of unequal sizes cannot be composed!"
@@ -210,11 +290,13 @@ module MoreMath
     # The return value of this method can be used to create a
     # new Permutation instance with the Permutation.from_cycles method.
     #
-    # <b>Example:</b>
+    # @example
     #  perm = Permutation.new(7, 23)
     #  # => #<Permutation:0x58541c @last=5039, @rank=23, @size=7>
     #  perm.cycles
     #  # => [[3, 6], [4, 5]]
+    #
+    # @return [Array<Array<Integer>>] array of cycles
     def cycles
       perm = value
       result = [[]]
@@ -246,6 +328,8 @@ module MoreMath
     # A permutation is odd if it can be represented by an odd number of
     # transpositions (cycles of length 2), or even if it can be represented of
     # an even number of transpositions.
+    #
+    # @return [Integer] 1 for even, -1 for odd
     def signum
       s = 1
       cycles.each do |c|
@@ -257,11 +341,15 @@ module MoreMath
     alias sgn signum
 
     # Returns true if this permutation is even, false otherwise.
+    #
+    # @return [Boolean] true if even permutation
     def even?
       signum == 1
     end
 
     # Returns true if this permutation is odd, false otherwise.
+    #
+    # @return [Boolean] true if odd permutation
     def odd?
       signum == -1
     end
@@ -270,13 +358,23 @@ module MoreMath
 
     @@fcache = [ 1 ]
 
+    # Computes the factorial of a number using memoization for efficiency. This
+    # method is used internally by the permutation ranking system to calculate
+    # the total number of permutations for a given size.
+    #
+    # @param n [Integer] the number to calculate factorial for
+    # @return [Integer] the factorial of n
     def factorial(n)
       @@fcache.size.upto(n) { |i| @@fcache[i] =  i * @@fcache[i - 1] }
       @@fcache[n]
     end
 
     # Rank the indices of the permutation +p+. Beware that this method may
-    # change its argument +p+.
+    # change its argument +p+. Rank the indices of the permutation p. Beware
+    # that this method may change its argument p.
+    #
+    # @param p [Array<Integer>] the permutation indices to rank
+    # @return [Integer] the rank of the permutation indices
     def rank_indices(p)
       result = 0
       for i in 0...size
@@ -288,8 +386,15 @@ module MoreMath
       result
     end
 
-    # Unrank the rank +m+, that is create a permutation of the appropriate size
-    # and rank as an array of indices and return it.
+    # Unranks the given index value into an array of permutation indices.
+    #
+    # This method converts a rank value back into its corresponding permutation
+    # indices representation. It's the inverse operation of the rank_indices
+    # method and is used internally by the permutation ranking system to
+    # reconstruct permutation arrays from their rank values.
+    #
+    # @param m [Integer] The rank value to unrank
+    # @return [Array<Integer>] Array of indices representing the permutation
     def unrank_indices(m)
       result = Array.new(size, 0)
       for i in 0...size

data/lib/more_math/ranking_common.rb

@@ -1,21 +1,34 @@
 module MoreMath
+  # Common functionality for ranking systems. This module provides basic
+  # ranking operations that are shared across different ranking implementations
+  # in the MoreMath library, including permutations and subsets.
   module RankingCommon
     # Returns the size of this instance's collection, a Fixnum.
+    #
+    # @return [Integer] the size of the collection
     attr_reader :size
 
     # Returns the rank of this instance, a Fixnum in the range
     # of 0 and #last.
+    #
+    # @return [Integer] the current rank
     attr_reader :rank
 
     # Returns the rank of the last ranked instance.
+    #
+    # @return [Integer] the maximum rank value for this size
     attr_reader :last
 
     # Returns the collection the #rank applies to if any was set, otherwise
-    # retrurns nil.
+    # returns nil.
+    #
+    # @return [Object, nil] the associated collection or nil
     attr_reader :collection
 
     # Switches this instance to the next ranked instance. If this was the #last
-    # instance it wraps around the first (<code>rank == 0</code>) instance.
+    # instance it wraps around to the first (<code>rank == 0</code>) instance.
+    #
+    # @return [self] returns self after incrementing rank
     def next!
       self.rank += 1
       self
@@ -25,6 +38,8 @@ module MoreMath
 
     # Returns the next ranked instance. If this instance is the #last instance
     # it returns the first (<code>rank == 0</code>) instance again.
+    #
+    # @return [self] a new instance with incremented rank
     def next
       clone.next!
     end
@@ -33,6 +48,8 @@ module MoreMath
 
     # Switches this instance to the previously ranked instance. If this was the
     # first instance it returns the last (<code>rank == #last</code>) instance.
+    #
+    # @return [self] returns self after decrementing rank
     def pred!
       self.rank -= 1
       self
@@ -40,11 +57,15 @@ module MoreMath
 
     # Returns the previously ranked instance. If this was the first instance it
     # returns the last (<code>rank == #last</code>) instance.
+    #
+    # @return [self] a new instance with decremented rank
     def pred
       clone.pred!
     end
 
     # Switches this instance to a randomly ranked instance.
+    #
+    # @return [self] returns self after setting random rank
     def random!
       new_rank = rand(last + 1).to_i
       self.rank = new_rank
@@ -52,6 +73,8 @@ module MoreMath
     end
 
     # Returns a randomly ranked instance.
+    #
+    # @return [self] a new instance with random rank
     def random
       clone.random!
     end
@@ -63,7 +86,10 @@ module MoreMath
     # step.
     #
     # The mixed in methods from the Enumerable module rely on this method.
-    def each # :yields: perm
+    #
+    # @yield [instance] yields each instance in sequence
+    # @return [self] returns self after iteration
+    def each
       0.upto(last) do |r|
         klon = clone
         klon.rank = r
@@ -72,13 +98,15 @@ module MoreMath
       self
     end
 
-    # Does something similar to #each. It doesn't create new
-    # instances (less overhead) for every iteration step, but yields to a
-    # modified self instead. This is useful if one only wants to call a
-    # method on the yielded value and work with the result of this call. It's
-    # not a good idea to put the yielded values in a data structure because all
-    # of them will reference the same (this!) instance. If you want to do this
-    # use #each.
+    # Does something similar to #each. It doesn't create new instances (less
+    # overhead) for every iteration step, but yields to a modified self
+    # instead. This is useful if one only wants to call a method on the yielded
+    # value and work with the result of this call. It's not a good idea to put
+    # the yielded values in a data structure because all of them will reference
+    # the same (this!) instance. If you want to do this use #each.
+    #
+    # @yield [instance] yields the current instance
+    # @return [self] returns self after iteration
     def each!
       old_rank = rank
       0.upto(last) do |r|

data/lib/more_math/sequence/moving_average.rb

@@ -1,6 +1,31 @@
 module MoreMath
   class Sequence
+    # Module containing moving average calculation methods
+    #
+    # Provides simple moving average functionality for sequence analysis and
+    # time series data.
     module MovingAverage
+      # Calculates a simple moving average for the sequence
+      #
+      # A simple moving average is calculated by taking the arithmetic mean of
+      # a specified number of consecutive elements in the sequence.
+      #
+      # @example Basic usage
+      #   sequence = Sequence.new([1, 2, 3, 4, 5])
+      #   sequence.simple_moving_average(3) # => [2.0, 3.0, 4.0]
+      #
+      # @example With alias usage
+      #   sequence = Sequence.new([1, 2, 3, 4, 5])
+      #   sequence.moving_average(2) # => [1.5, 2.5, 3.5, 4.5]
+      #
+      # @param n [Integer] The window size for the moving average (must be >= 1)
+      # @return [Array<Float>] Array of moving averages, where each element is
+      #   the mean of n consecutive elements from the original sequence
+      # @raise [ArgumentError] If n < 1 or n > number of elements in the sequence
+      #
+      # @note The result array will contain (elements.size - n + 1) elements
+      # @note Each moving average is calculated as the arithmetic mean of n
+      #   consecutive elements
       def simple_moving_average(n)
         n < 1 and raise ArgumentError, 'n < 1, has to be >= 1'
         n <= @elements.size or raise ArgumentError,
@@ -15,6 +40,8 @@ module MoreMath
         end
         avg
       end
+
+      # Alias for {simple_moving_average}
       alias moving_average simple_moving_average
     end
   end

data/lib/more_math/sequence/refinement.rb

@@ -1,5 +1,31 @@
+# Refinement module that adds sequence conversion capabilities to Object.
+#
+# This refinement extends the Object class with a +to_seq+ method that
+# converts any enumerable object into a MoreMath::Sequence.
+#
+# @example Converting an array to a sequence
+#   using MoreMath::Sequence::Refinement
+#   [1, 2, 3, 4, 5].to_seq
+#   # => #<MoreMath::Sequence:0x00007f8b8c0b8a00>
+#
+# @example Converting other enumerables
+#   using MoreMath::Sequence::Refinement
+#   (1..5).to_seq
+#   # => #<MoreMath::Sequence:0x00007f8b8c0b8a00>
+#
+# @note This refinement must be activated with +using
+#   MoreMath::Sequence::Refinement+ before it can be used
+# @note The resulting sequence is frozen and cannot be modified
 module MoreMath::Sequence::Refinement
   refine ::Object do
+    # Converts this object into a MoreMath::Sequence.
+    #
+    # This method iterates over the object (assuming it's enumerable) and
+    # creates a new Sequence instance containing all elements.
+    #
+    # @return [MoreMath::Sequence] A new sequence containing all elements
+    # @note This method works with any enumerable object
+    # @note The resulting sequence is frozen and cannot be modified
     def to_seq
       ary = []
       each { |x| ary << x }