more_math 1.5.0 → 1.6.0

data/lib/more_math/histogram.rb

@@ -1,11 +1,37 @@
 require 'tins'
 
 module MoreMath
-  # A histogram gives an overview of a sequence's elements.
+  # Represents a histogram for visualizing data distributions
+  #
+  # The Histogram class provides functionality to create and display histograms
+  # from sequences of numerical data. It divides the data into bins and counts
+  # how many elements fall into each bin, then displays this information in a
+  # readable format with optional UTF-8 bar characters.
+  #
+  # @example Creating a histogram
+  #   sequence = [1, 2, 3, 4, 5, 1]
+  #   hist = Histogram.new(sequence, bins: 3)
+  #
+  # @example Displaying a histogram
+  #   hist.display($stdout, 80)
   class Histogram
+    # Represents a single bin in a histogram with left boundary, right
+    # boundary, and count.
+    #
+    # @!attribute [r] left
+    #   @return [Float] The left boundary of the bin
+    # @!attribute [r] right
+    #   @return [Float] The right boundary of the bin
+    # @!attribute [r] count
+    #   @return [Integer] The number of elements in this bin
     Bin = Struct.new(:left, :right, :count)
 
     # Create a Histogram for the elements of +sequence+ with +bins+ bins.
+    #
+    # @param sequence [Enumerable] The sequence to build the histogram from
+    # @param arg [Integer, Hash] Number of bins or hash with options like `:bins` and `:with_counts`
+    # @option arg [Integer] :bins (10) Number of bins to use
+    # @option arg [Boolean] :with_counts (false) Whether to display counts in output
     def initialize(sequence, arg = 10)
       @with_counts = false
       if arg.is_a?(Hash)
@@ -20,23 +46,39 @@ module MoreMath
     end
 
     # Number of bins for this Histogram.
+    #
+    # @return [Integer]
     attr_reader :bins
 
     # Return the computed histogram as an array of Bin objects.
+    #
+    # @return [Array<Bin>]
     def to_a
       @result
     end
 
+    # Iterate over each bin in the histogram.
+    #
+    # @yield [Bin] each bin
+    # @return [Array<Bin>]
     def each_bin(&block)
       @result.each(&block)
     end
 
+    # Get an array of counts from each bin.
+    #
+    # @return [Array<Integer>]
     def counts
       each_bin.map(&:count)
     end
 
-    # Display this histogram to +output+, +width+ is the parameter for
-    # +prepare_display+
+    # Display this histogram to +output+ using +width+ columns. Raises
+    # ArgumentError if width < 15.
+    #
+    # @param output [IO] The output stream to write to (default: $stdout)
+    # @param width [Integer, String] Width of the display; can be a percentage string like "90%"
+    # @raise [ArgumentError] If width is less than 15
+    # @return [self]
     def display(output = $stdout, width = 65)
       if width.is_a?(String) && width =~ /(.+)%\z/
         percentage = Float($1).clamp(0, 100)
@@ -50,16 +92,26 @@ module MoreMath
       self
     end
 
+    # Get terminal width using Tins::Terminal.
+    #
+    # @return [Integer]
     def terminal_width
       Tins::Terminal.columns
     end
 
+    # Get the maximum count in any bin.
+    #
+    # @return [Integer]
     def max_count
       counts.max
     end
 
     private
 
+    # Generate UTF-8 bar character representation based on width.
+    #
+    # @param bar_width [Float] Width of the bar
+    # @return [String]
     def utf8_bar(bar_width)
       fract = bar_width - bar_width.floor
       bar   = ?⣿ * bar_width.floor
@@ -71,14 +123,26 @@ module MoreMath
       bar
     end
 
+    # Generate ASCII bar character representation based on width.
+    #
+    # @param bar_width [Float] Width of the bar
+    # @return [String]
     def ascii_bar(bar_width)
       ?* * bar_width
     end
 
+    # Determine if UTF-8 is enabled in the environment.
+    #
+    # @return [Boolean]
     def utf8?
       ENV['LANG'] =~ /utf-8\z/i
     end
 
+    # Format a single row of histogram data for output.
+    #
+    # @param row [Array] A tuple containing [left, right, count]
+    # @param width [Integer] Width of the bar display area
+    # @return [String]
     def output_row(row, width)
       left, right, count = row
       if @with_counts
@@ -88,6 +152,13 @@ module MoreMath
       end
     end
 
+    # Output a row with counts.
+    #
+    # @param left [Float] Left boundary of bin
+    # @param right [Float] Right boundary of bin
+    # @param count [Integer] Count in bin
+    # @param width [Integer] Width of bar display area
+    # @return [String]
     def output_row_with_count(left, right, count, width)
       width -= 15
       c = utf8? ? 2 : 1
@@ -103,6 +174,13 @@ module MoreMath
         [ (left + right) / 2.0, bar, count ]
     end
 
+    # Output a row without counts.
+    #
+    # @param left [Float] Left boundary of bin
+    # @param right [Float] Right boundary of bin
+    # @param count [Integer] Count in bin
+    # @param width [Integer] Width of bar display area
+    # @return [String]
     def output_row_without_count(left, right, count, width)
       width -= 15
       left_width = width
@@ -113,6 +191,9 @@ module MoreMath
       "%11.5f -|%#{-width}s\n" % [ (left + right) / 2.0, bar ]
     end
 
+    # Returns rows for display.
+    #
+    # @return [Array<Array>]
     def rows
       @result.reverse_each.map { |bin|
         [ bin.left, bin.right, bin.count ]
@@ -120,6 +201,8 @@ module MoreMath
     end
 
     # Computes the histogram and returns it as an array of tuples (l, c, r).
+    #
+    # @return [Array<Bin>]
     def compute
       @sequence.empty? and return []
       last_r = -Infinity

data/lib/more_math/linear_regression.rb

@@ -1,7 +1,48 @@
 module MoreMath
   # This class computes a linear regression for the given image and domain data
   # sets.
+  #
+  # Linear regression is a statistical method that models the relationship
+  # between a dependent variable (image) and one or more independent variables
+  # (domain). It fits a linear equation to observed data points to make
+  # predictions or understand relationships.
+  #
+  # The implementation uses the least squares method to find the best-fit line
+  # y = ax + b, where 'a' is the slope and 'b' is the y-intercept.
+  #
+  # @example Basic usage
+  #   # Create a linear regression from data points
+  #   image_data = [2, 4, 6, 8, 10]
+  #   domain_data = [1, 2, 3, 4, 5]
+  #   lr = LinearRegression.new(image_data, domain_data)
+  #
+  #   # Access the fitted line parameters
+  #   puts lr.a  # slope
+  #   puts lr.b  # y-intercept
+  #
+  #   # Make predictions
+  #   predicted_y = lr.a * 6 + lr.b  # Predict y for x=6
+  #
+  # @example Statistical analysis
+  #   # Check if the slope is significantly different from zero
+  #   lr.slope_zero?(0.05)  # Returns true if slope is not statistically significant
+  #
+  #   # Calculate coefficient of determination (R²)
+  #   puts lr.r2  # R-squared value indicating model fit
   class LinearRegression
+    # Creates a new LinearRegression instance with image and domain data.
+    #
+    # Initializes the linear regression model using the provided data points.
+    # The domain data represents independent variables (x-values) and the image
+    # data represents dependent variables (y-values).
+    #
+    # @param image [Array<Numeric>] Array of dependent variable values (y-coordinates)
+    # @param domain [Array<Numeric>] Array of independent variable values (x-coordinates)
+    # @raise [ArgumentError] If image and domain arrays have unequal sizes
+    # @example Creating a linear regression
+    #   image = [1, 2, 3, 4, 5]
+    #   domain = [0, 1, 2, 3, 4]
+    #   lr = LinearRegression.new(image, domain)
     def initialize(image, domain = (0...image.size).to_a)
       image.size != domain.size and raise ArgumentError,
         "image and domain have unequal sizes"
@@ -10,30 +51,67 @@ module MoreMath
     end
 
     # The image data as an array.
+    #
+    # Returns the dependent variable values used in the regression.
+    #
+    # @return [Array<Numeric>] Array of y-values from the original data
     attr_reader :image
 
     # The domain data as an array.
+    #
+    # Returns the independent variable values used in the regression.
+    #
+    # @return [Array<Numeric>] Array of x-values from the original data
     attr_reader :domain
 
     # The slope of the line.
+    #
+    # Returns the calculated slope (a) of the best-fit line y = ax + b.
+    #
+    # @return [Float] The slope coefficient of the linear regression
     attr_reader :a
 
     # The offset of the line.
+    #
+    # Returns the calculated y-intercept (b) of the best-fit line y = ax + b.
+    #
+    # @return [Float] The y-intercept coefficient of the linear regression
     attr_reader :b
 
-    # Return true if the slope of the underlying data (not the sample data
-    # passed into the constructor of this LinearRegression instance) is likely
-    # (with alpha level _alpha_) to be zero.
+    # Checks if the slope is significantly different from zero.
+    #
+    # Performs a t-test to determine whether the slope coefficient is
+    # statistically significant at the given significance level (alpha).
+    # This test helps determine if there's a meaningful linear relationship
+    # between the independent and dependent variables.
+    #
+    # @param alpha [Float] The significance level (default: 0.05, or 5%)
+    # @return [Boolean] true if the slope is not significantly different from zero,
+    #   false otherwise
+    # @raise [ArgumentError] If alpha is not in the range 0..1
+    # @example Testing slope significance
+    #   lr = LinearRegression.new([1, 2, 3, 4, 5], [2, 4, 6, 8, 10])
+    #   lr.slope_zero?  # => false (slope is significantly different from zero)
+    #   lr.slope_zero?(0.1)  # => false (still significant at 10% level)
     def slope_zero?(alpha = 0.05)
+      (0..1) === alpha or raise ArgumentError, 'alpha should be in 0..100'
       df = @image.size - 2
       return true if df <= 0 # not enough values to check
-      t = tvalue(alpha)
+      t = tvalue
       td = TDistribution.new df
       t.abs <= td.inverse_probability(1 - alpha.abs / 2.0).abs
     end
 
-    # Returns the residuals of this linear regression in relation to the given
-    # domain and image.
+    # Returns the residuals of this linear regression.
+    #
+    # Residuals are the differences between observed values and predicted
+    # values from the regression line. They represent the error in prediction
+    # for each data point.
+    #
+    # @return [Array<Float>] Array of residual values (observed - predicted)
+    # @example Calculating residuals
+    #   lr = LinearRegression.new([1, 2, 3], [0, 1, 2])
+    #   puts lr.residuals  # [0.0, 0.0, 0.0] for perfect fit
     def residuals
       result = []
       @domain.zip(@image) do |x, y|
@@ -42,6 +120,16 @@ module MoreMath
       result
     end
 
+    # Returns the coefficient of determination (R²).
+    #
+    # R² measures the proportion of the variance in the dependent variable that is
+    # predictable from the independent variable(s). It ranges from 0 to 1, where
+    # higher values indicate better fit.
+    #
+    # @return [Float] The R-squared value (0.0 to 1.0)
+    # @example Checking model fit
+    #   lr = LinearRegression.new([1, 2, 3], [0, 1, 2])
+    #   puts lr.r2  # 1.0 for perfect linear relationship
     def r2
       image_seq = MoreMath::Sequence.new(@image)
       sum_res   = residuals.inject(0.0) { |s, r| s + r ** 2 }
@@ -53,6 +141,13 @@ module MoreMath
 
     private
 
+    # Computes the linear regression parameters using least squares method.
+    #
+    # This internal method calculates the slope (a) and intercept (b)
+    # coefficients by solving the normal equations derived from minimizing the
+    # sum of squared residuals.
+    #
+    # @return [self] Returns self to allow method chaining
     def compute
       size = @image.size
       sum_xx = sum_xy = sum_x = sum_y = 0.0
@@ -67,7 +162,13 @@ module MoreMath
       self
     end
 
-    def tvalue(alpha = 0.05)
+    # Calculates the t-value for testing slope significance.
+    #
+    # This internal method computes the t-statistic used in hypothesis testing
+    # to determine if the slope differs significantly from zero.
+    #
+    # @return [Float] The calculated t-value for the test
+    def tvalue
       df = @image.size - 2
       return 0.0 if df <= 0
       sse_y = 0.0

data/lib/more_math/newton_bisection.rb

@@ -3,21 +3,68 @@ require 'more_math/exceptions'
 module MoreMath
   # This class is used to find the root of a function with Newton's bisection
   # method.
+  #
+  # The NewtonBisection class implements a hybrid root-finding algorithm that
+  # combines elements of both Newton-Raphson and bisection methods. It starts
+  # by attempting to bracket a root using a scaling factor, then uses a
+  # bisection approach to converge on the solution.
+  #
+  # @example Finding a root using Newton's bisection method
+  #   # Define a function to find roots for (e.g., x^2 - 4 = 0)
+  #   func = ->(x) { x ** 2 - 4 }
+  #
+  #   # Create a NewtonBisection instance
+  #   solver = MoreMath::NewtonBisection.new(&func)
+  #
+  #   # Find the root in a given range
+  #   root = solver.solve(1..3)
+  #   puts root  # => 2.0 (approximately)
+  #
+  # @example Finding a root with automatic bracketing
+  #   func = ->(x) { Math.sin(x) }
+  #   solver = MoreMath::NewtonBisection.new(&func)
+  #
+  #   # Let the solver automatically find a bracket
+  #   root = solver.solve
+  #   puts root  # => approximately 3.14159 (π)
   class NewtonBisection
     include MoreMath::Exceptions
 
     # Creates a NewtonBisection instance for +function+, a one-argument block.
+    #
+    # @param function [Proc] A one-argument block that represents the function
+    #   to find roots for. The function should return a numeric value.
+    # @example Creating a solver with a lambda
+    #   func = ->(x) { x**2 - 4 }
+    #   solver = MoreMath::NewtonBisection.new(&func)
     def initialize(&function)
       @function = function
     end
 
     # The function, passed into the constructor.
+    #
+    # @return [Proc] The function used for root finding
     attr_reader :function
 
-    # Return a bracket around a root, starting from the initial +range+. The
-    # method returns nil, if no such bracket around a root could be found after
-    # +n+ tries with  the scaling +factor+.
-    def bracket(range = -1..1, n = 50, factor =  1.6)
+    # Return a bracket around a root, starting from the initial +range+.
+    #
+    # This method attempts to find an interval that brackets a root by
+    # expanding the initial range using a scaling factor. It uses the property
+    # that if f(x1) and f(x2) have opposite signs, there must be at least one
+    # root in the interval [x1, x2].
+    #
+    # @param range [Range] Initial range to search for a bracket (default: -1..1)
+    # @param n [Integer] Maximum number of iterations to attempt bracketing (default: 50)
+    # @param factor [Float] Scaling factor for expanding the search range (default: 1.6)
+    # @return [Range, nil] A range that brackets a root, or nil if no bracket
+    #   could be found within the specified iterations and factor
+    # @raise [ArgumentError] If the initial range is invalid (x1 >= x2)
+    # @example Finding a bracket for sin(x) function
+    #   func = ->(x) { Math.sin(x) }
+    #   solver = MoreMath::NewtonBisection.new(&func)
+    #   bracket = solver.bracket(2..4)
+    #   # Returns range that brackets root near π ≈ 3.14
+    def bracket(range = -1..1, n = 50, factor = 1.6)
       x1, x2 = range.first.to_f, range.last.to_f
       x1 >= x2 and raise ArgumentError, "bad initial range #{range}"
       f1, f2 = @function[x1], @function[x2]
@@ -29,12 +76,28 @@ module MoreMath
           f2 = @function[x2 += factor * (x2 - x1)]
         end
       end
-      return
+      nil
     end
 
-    # Find the root of function in +range+ and return it. The method raises a
-    # DivergentException, if no such root could be found after +n+ tries and in
-    # the +epsilon+ environment.
+    # Find the root of function in +range+ and return it.
+    #
+    # This method implements a bisection algorithm to find the root within
+    # the specified range. It uses a binary search approach, repeatedly halving
+    # the interval until convergence is achieved or maximum iterations are reached.
+    #
+    # @param range [Range] The range in which to search for a root (optional)
+    #   If nil, attempts to automatically bracket the root first
+    # @param n [Integer] Maximum number of iterations (default: 2^16)
+    # @param epsilon [Float] Convergence threshold (default: 1E-16)
+    # @return [Float] The approximate root value
+    # @raise [ArgumentError] If the initial range is invalid or no bracket is found
+    # @raise [MoreMath::Exceptions::DivergentException] If no root can be found
+    #   within the specified iterations or if convergence fails
+    # @example Solving x^2 - 4 = 0 with explicit range
+    #   func = ->(x) { x**2 - 4 }
+    #   solver = MoreMath::NewtonBisection.new(&func)
+    #   root = solver.solve(1..3)  # Finds root near +2.0
+    #   puts root  # => 2.0
     def solve(range = nil, n = 1 << 16, epsilon = 1E-16)
       if range
         x1, x2 = range.first.to_f, range.last.to_f

data/lib/more_math/numberify_string_function.rb

@@ -1,11 +1,52 @@
 module MoreMath
+  # Provides functions for converting between strings and numbers using a
+  # base-N numeral system.
+  #
+  # This module implements Gödel numbering, where strings are encoded into
+  # unique natural numbers and decoded back. It's particularly useful for
+  # applications requiring ordered enumeration of strings or mathematical
+  # operations on textual data.
+  #
+  # The encoding follows a positional numeral system where each character
+  # position represents a power of the alphabet size.
+  #
+  # @example Basic usage
+  #   # Convert string to number
+  #   MoreMath::NumberifyStringFunction.numberify_string("abc") # => 731
+  #
+  #   # Convert number back to string
+  #   MoreMath::NumberifyStringFunction.stringify_number(731) # => "abc"
+  #
+  # @example With custom alphabet
+  #   alphabet = ['a', 'b', 'c']
+  #   MoreMath::NumberifyStringFunction.numberify_string("abc", alphabet) # => 18
+  #   MoreMath::NumberifyStringFunction.stringify_number(18, alphabet) # => "abc"
   module NumberifyStringFunction
-    Functions = MoreMath::Functions
+    include Functions
 
     module_function
 
+    # Converts a string into a unique natural number using the specified
+    # alphabet.
+    #
+    # This method implements a base-N numeral system where N is the size of the
+    # alphabet. Each character in the string contributes to the final number
+    # based on its position and value within the alphabet.
+    #
+    # @example Basic usage
+    #   MoreMath::NumberifyStringFunction.numberify_string("hello") # => 123456789
+    #
+    # @example With custom alphabet
+    #   alphabet = ['a', 'b', 'c']
+    #   MoreMath::NumberifyStringFunction.numberify_string("abc", alphabet) # => 18
+    #
+    # @param string [String] The input string to convert to a number
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use for conversion.
+    #   Defaults to 'a'..'z' (lowercase English letters)
+    # @return [Integer] A unique natural number representing the input string
+    # @raise [ArgumentError] If any character in the string is not found in the alphabet
     def numberify_string(string, alphabet = 'a'..'z')
-      alphabet = NumberifyStringFunction.convert_alphabet alphabet
+      alphabet = NumberifyStringFunction.convert_alphabet(alphabet)
       s, k = string.size, alphabet.size
       result = 0
       for i in 0...s
@@ -17,6 +58,24 @@ module MoreMath
       result
     end
 
+    # Converts a natural number back into its corresponding string
+    # representation.
+    #
+    # This is the inverse operation of {numberify_string}. It reconstructs the
+    # original string by reversing the positional numeral system encoding.
+    #
+    # @example Basic usage
+    #   MoreMath::NumberifyStringFunction.stringify_number(731) # => "abc"
+    #
+    # @example With custom alphabet
+    #   alphabet = ['a', 'b', 'c']
+    #   MoreMath::NumberifyStringFunction.stringify_number(18, alphabet) # => "abc"
+    #
+    # @param number [Integer] The natural number to convert back to a string
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use for conversion.
+    #   Defaults to 'a'..'z' (lowercase English letters)
+    # @return [String] The original string representation of the number
+    # @raise [ArgumentError] If the number is negative
     def stringify_number(number, alphabet = 'a'..'z')
       case
       when number < 0
@@ -24,7 +83,7 @@ module MoreMath
       when number == 0
         return ''
       end
-      alphabet = NumberifyStringFunction.convert_alphabet alphabet
+      alphabet = NumberifyStringFunction.convert_alphabet(alphabet)
       s = NumberifyStringFunction.compute_size(number, alphabet.size)
       k, m = alphabet.size, number
       result = ' ' * s
@@ -38,25 +97,42 @@ module MoreMath
       result
     end
 
-    class << self
-      memoize function:
-      def compute_size(n, b)
-        i = 0
-        while n > 0
-          i += 1
-          n -= b ** i
-        end
-        i
+    # Calculates the minimum number of digits needed to represent a number in
+    # base N.
+    #
+    # This helper method is used internally to determine how many characters
+    # are needed when converting a number back to its string representation.
+    #
+    # @api private
+    # @param n [Integer] The number to calculate size for
+    # @param b [Integer] The base of the numeral system
+    # @return [Integer] The minimum number of digits required
+    def compute_size(n, b)
+      i = 0
+      while n > 0
+        i += 1
+        n -= b ** i
       end
+      i
+    end
 
-      def convert_alphabet(alphabet)
-        if alphabet.respond_to?(:to_ary)
-          alphabet.to_ary
-        elsif alphabet.respond_to?(:to_str)
-          alphabet.to_str.split(//)
-        else
-          alphabet.to_a
-        end
+    # Converts various alphabet representations into a consistent Array format.
+    #
+    # This method handles different input types for the alphabet:
+    # - Range: converts to array of characters
+    # - String: splits into individual characters
+    # - Array: returns as-is
+    #
+    # @api private
+    # @param alphabet [Object] The alphabet in various formats (Range, String, or Array)
+    # @return [Array<String>] Standardized array representation of the alphabet
+    def convert_alphabet(alphabet)
+      if alphabet.respond_to?(:to_ary)
+        alphabet.to_ary
+      elsif alphabet.respond_to?(:to_str)
+        alphabet.to_str.split(//)
+      else
+        alphabet.to_a
       end
     end
   end