chris_lib 2.2.1 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d8fd49f3985821fec93f9e490e89fca4cbe483047cdeb8b8b794eaa246e317e
-  data.tar.gz: 726e074b5edc14e8e274b9b092a89cf92b5a39f71ecf3ba0f6ea8a245e11b430
+  metadata.gz: ed68c4652e1c8bb9171e1c6faa07dbcfd8dfacfc4ade1eefba8f64698040a367
+  data.tar.gz: 7b6e5522b4861ea44572dcee282119409383e2434bff297229ed5330b8191629
 SHA512:
-  metadata.gz: 6456985f4b3418a424c6f9bcd19bce4b9d1783b91c55730214d68b5ea259c1345b05c88115303b89df4a7720eba7d012a93887004b823c5f65e19018e08b0b75
-  data.tar.gz: 037fccb47857527464af9987b088d492f85559219d6af30c9677ad18ecbc7a0a5897b11f57cd151260998c73e091f9ed929b11efcc420187a5b338fed580bc59
+  metadata.gz: f10142175fdfbd73a02475c480ab41f6040355c00fd2e6382bd8cfc92fe8328ba34255f9bdd0a165bcf261ef58c1afff88fd73b39e1c29923df6e79b13892c61
+  data.tar.gz: 2bdda10220d21a555725f6c88d71746f5db73813c67a9f587e6ada6792c1a1817c003fbead5dae9aad481e4c5fd236c7717ab898f8172b123f3ec8bff9df936b

data/lib/chris_lib/chris_math.rb

@@ -1,30 +1,38 @@
 require 'matrix'
 require 'quaternion'
 Quaternion.class_eval do
-  # rounds each element of quaternion to n decimal places
+  # @param n [Integer] number of decimal places to retain
+  # @return [Quaternion] a new quaternion with each component rounded
   def round(n)
     q = self
     Quaternion.new(q[0].round(n), q[1].round(n), q[2].round(n), q[3].round(n))
   end
 
-  # Creates identity quaternion
+  # @return [Quaternion] the identity quaternion (1, 0, 0, 0)
   def self.identity
     Quaternion.new(1.0, 0.0, 0.0, 0.0)
   end
 
-  # Creates zero quaternion
+  # @return [Quaternion] the zero quaternion (0, 0, 0, 0)
   def self.zero
     Quaternion.new(0.0, 0.0, 0.0, 0.0)
   end
   
   # Creates quaternion using square brackets (for compatability with Matrix and Vector)
-  # see https://stackoverflow.com/questions/69155796/how-to-define-a-class-method-when-using-class-eval
+  # @see https://stackoverflow.com/questions/69155796/how-to-define-a-class-method-when-using-class-eval
+  # @param q0 [Numeric]
+  # @param q1 [Numeric]
+  # @param q2 [Numeric]
+  # @param q3 [Numeric]
+  # @return [Quaternion]
   def self.[](q0, q1, q2, q3)
     Quaternion.new(q0, q1, q2, q3)
   end
 end
 
 Integer.class_eval do
+  # @return [Integer] factorial of the number
+  # @raise [RuntimeError] when the receiver is greater than 20 to avoid overflow
   def factorial
     n = self
     if n > 20
@@ -36,49 +44,63 @@ Integer.class_eval do
 end
 
 Matrix.class_eval do
-  # right pseudo-inverse for linearly independent rows
+  # Right pseudo-inverse for linearly independent rows
+  # @return [Matrix]
+  # @raise [ExceptionForMatrix::ErrNotRegular] when the matrix is rank-deficient
   def pinv
     full_rank = (rank == [row_count, column_count].min)
     raise ExceptionForMatrix::ErrNotRegular unless full_rank
     transpose * (self * transpose).inv
   end
 
-  # for linearly independent rows
+  # Alias for {#pinv} maintained for backwards compatibility
+  # @return [Matrix]
+  # @raise [ExceptionForMatrix::ErrNotRegular] when the matrix is rank-deficient
   def pinv_right
     full_rank = (rank == [row_count, column_count].min)
     raise ExceptionForMatrix::ErrNotRegular unless full_rank
     transpose * (self * transpose).inv
   end
 
-  # for linearly independent columns
+  # Left pseudo-inverse for linearly independent columns
+  # @return [Matrix]
   def pinv_left
     (transpose * self).inv * transpose
   end
 end
 
 Array.class_eval do
-  # converts radians to degrees
-  # Also rounds to n_decimal places unless n_decimimals is nil
+  # Converts radians to degrees for each element
+  # @param n_decimals [Integer, nil] decimal places to round to, pass nil for no rounding
+  # @return [Array<Float>] converted values
   def to_deg(n_decimals = nil)
     map { |e| e.to_deg(n_decimals) }   
   end
 
-  # converts degrees to radians
-  # Also rounds to n_decimal places unless n_decimimals is nil
+  # Converts degrees to radians for each element
+  # @param n_decimals [Integer, nil] decimal places to round to, pass nil for no rounding
+  # @return [Array<Float>] converted values
   def to_rad(n_decimals = nil)
     map { |e| e.to_rad(n_decimals) }
   end
 
-  # round each element
+  # Rounds each element in-place
+  # @param decimal_points [Integer] decimal places to round to
+  # @return [Array<Numeric>] rounded values
   def round(decimal_points = 0)
     map { |e| e.round(decimal_points) }
   end
 
+  # Rounds elements using {Float#eround}
+  # @param decimal_points [Integer]
+  # @return [Array<Float>]
   def eround(decimal_points = 0)
     map { |e| e.eround(decimal_points) }
   end
   
-  # mean of array
+  # Calculates the arithmetic mean of elements
+  # @return [Numeric, Vector]
+  # @raise [RuntimeError] when the array is empty
   def mean
     raise 'chris_lib - f - Length must be greater than 0.' if length < 1
     return sum.to_f / length unless all? { |e| e.class == Vector }
@@ -86,24 +108,29 @@ Array.class_eval do
     Vector.elements ary
   end
 
-  # unbiased sample variance of array
+  # Computes the unbiased sample variance
+  # @return [Float]
+  # @raise [RuntimeError] when the array has fewer than two elements
   def var
     raise 'Length must be greater than 1' if length < 2
     mu = mean
     map { |v| (v**2 - mu**2) }.sum.to_f / (length - 1)
   end
 
-  # sample standard deviation
+  # Computes the sample standard deviation
+  # @return [Float]
   def std
     return 0 if var < 0.0 # perhaps due to rounding errors
     Math.sqrt(var)
   end
 
-  # standard error of sample mean
+  # Standard error of the sample mean
+  # @return [Float]
   def std_err
     std / Math.sqrt(size)
   end
 
+  # @return [Numeric] median value of the array
   def median
     return self[0] if length <= 1
     sorted = sort
@@ -115,16 +142,18 @@ Array.class_eval do
     end
   end
 
-  # deep dup, takes about 20 microseconds for scores arrays
-  # https://www.thoughtco.com/making-deep-copies-in-ruby-2907749
+  # Deep duplicate the array
+  # @return [Object] a deep copy of the array
+  # @see https://www.thoughtco.com/making-deep-copies-in-ruby-2907749
   def deep_dup
     Marshal.load(Marshal.dump(self))
   end
 end
 
 Float.class_eval do
-  # converts radians to degrees
-  # Also rounds to n_decimal places unless n_decimimals is nil
+  # Converts radians to degrees
+  # @param n_decimals [Integer, nil] decimal places to round to, pass nil for no rounding
+  # @return [Float]
   def to_deg(n_decimals = nil)
     include Math unless defined?(Math)
     degrees = self * 180.0 / PI
@@ -132,8 +161,9 @@ Float.class_eval do
     degrees.round(n_decimals)    
   end
 
-  # converts degrees to radians
-  # Also rounds to n_decimal places unless n_decimimals is nil
+  # Converts degrees to radians
+  # @param n_decimals [Integer, nil] decimal places to round to, pass nil for no rounding
+  # @return [Float]
   def to_rad(n_decimals = nil)
     include Math unless defined?(Math)
     radians = self * PI / 180.0
@@ -141,39 +171,57 @@ Float.class_eval do
     radians.round(n_decimals)
   end
 
-  # rounds exponential notation to n decimal places
+  # Rounds a float represented in exponential notation
+  # @param decimal_points [Integer]
+  # @return [Float]
   def eround(decimal_points = 0)
     ("%.#{decimal_points}e" % self).to_f
   end
 
+  # @param n [Integer] decimal place to round down to
+  # @return [Float]
   def round_down(n=0)
     # n is decimal place to round down at
     int,dec=self.to_s.split('.')
     "#{int}.#{dec[0...n]}".to_f
   end
 
+  # @return [Float]
   def round1
     round(1)
   end
 
+  # @return [Float]
   def round2
     round(2)
   end
 
+  # @return [Float]
   def round3
     round(3)
   end
 
+  # @return [Float]
   def round4
     round(4)
   end
 end
 
+# Numerically focused helpers and distribution utilities.
 module ChrisMath
   
   include Math
 
+  # Generates normally distributed random numbers using Box-Muller
+  # @param n [Integer] number of samples to generate
+  # @return [Array<Float>] array of N(0,1) samples
+  # @note Returns an empty array and warns when `n <= 0`.
   def gaussian_array(n = 1)
+    raise ArgumentError, 'n must be an Integer' unless n.is_a?(Integer)
+    if n <= 0
+      warn 'gaussian_array called with non-positive sample size; returning empty array'
+      return []
+    end
     (1..n).map do
       u1 = rand()
       u2 = rand()
@@ -181,6 +229,8 @@ module ChrisMath
     end
   end
   
+  # Generates a pair of independent standard normal deviates
+  # @return [Array<Float>] two-element array [z0, z1]
   def bi_gaussian_rand
     u1 = rand()
     u2 = rand()
@@ -189,7 +239,21 @@ module ChrisMath
     [z0,z1]
   end
 
+  # Generates a normally distributed random number with the provided mean and std
+  # @param mean [Numeric]
+  # @param std [Numeric]
+  # @return [Float]
+  # @note Warns when `std <= 0`, returning the mean or using the absolute value.
   def gaussian_rand(mean,std)
+    raise ArgumentError, 'mean must be Numeric' unless mean.is_a?(Numeric)
+    raise ArgumentError, 'std must be Numeric' unless std.is_a?(Numeric)
+    if std.negative?
+      warn 'std supplied to gaussian_rand was negative; using absolute value'
+      std = std.abs
+    elsif std.zero?
+      warn 'std supplied to gaussian_rand was zero; returning mean'
+      return mean
+    end
     u1 = rand()
     u2 = rand()
     z0 = sqrt(-2*log(u1))*cos(2*PI*u2)
@@ -197,7 +261,12 @@ module ChrisMath
   end
   
   
+  # Sample standard deviation for raw values
+  # @param values [Array<Numeric>]
+  # @return [Float]
+  # @raise [RuntimeError] when fewer than two observations are provided
   def std(values)
+    raise ArgumentError, 'values must respond to #length and #inject' unless values.respond_to?(:length) && values.respond_to?(:inject)
     n = values.length
     raise 'n = #{n} but must be greater than 1' if n < 2
     m = mean(values)
@@ -206,7 +275,16 @@ module ChrisMath
   end
   
 
+  # Cumulative probability of at least r successes in n Bernoulli trials
+  # @param n [Integer]
+  # @param r [Integer]
+  # @param p [Float] probability of success per trial
+  # @return [Float]
+  # @raise [RuntimeError] when r is outside 0..n
   def combinatorial_distribution(n,r,p)
+    raise ArgumentError, 'n must be a non-negative Integer' unless n.is_a?(Integer) && n >= 0
+    raise ArgumentError, 'r must be a non-negative Integer' unless r.is_a?(Integer) && r >= 0
+    raise ArgumentError, 'p must be between 0 and 1' unless p.is_a?(Numeric) && p.between?(0.0,1.0)
     # probability that r out n or greater hits with the 
     # probability of one hit is p.
     if r <= n && r >= 0
@@ -220,13 +298,29 @@ module ChrisMath
     end
   end
   
+  # Factorial without overflow protection
+  # @param n [Integer]
+  # @return [Integer]
+  # @note Warns and returns `nil` when `n` is negative.
   def factorial(n)
     #from rosetta code
+    raise ArgumentError, 'n must be an Integer' unless n.is_a?(Integer)
+    if n.negative?
+      warn 'factorial called with negative n; returning nil'
+      return nil
+    end
     (1..n).inject {|prod, i| prod * i}
   end
   
+  # Binomial coefficient "n choose k"
+  # @param n [Integer]
+  # @param k [Integer]
+  # @return [Integer]
   def combinatorial(n, k)
     #from rosetta code
+    raise ArgumentError, 'n must be a non-negative Integer' unless n.is_a?(Integer) && n >= 0
+    raise ArgumentError, 'k must be a non-negative Integer' unless k.is_a?(Integer) && k >= 0
+    raise ArgumentError, 'k must be <= n' if k > n
     (0...k).inject(1) do |m,i| (m * (n - i)) / (i + 1) end
   end
   

data/lib/chris_lib/date_ext.rb

@@ -1,4 +1,6 @@
-# extensions to Date
+# Extensions to {Date} for friendly formatting helpers.
+require 'date'
+
 module DateExt
   # To format a date, use <tt>date.charmians_format</tt>
   # on any Date object.
@@ -10,23 +12,28 @@ module DateExt
   # If using a DateTime object, need to convert to date i.e.
   # <tt>datetime.to_date.charmians_format</tt>.
   Date.class_eval do
+    # @return [String] Month day, year (e.g. "January 3, 2025")
     def us_format
       "#{strftime('%B')} #{day}, #{year}"
     end
 
+    # @return [String] Short month name day, year (e.g. "Jan 3, 2025")
     def short_format
       "#{strftime('%b')} #{day}, #{year}"
     end
 
+    # @return [String] Weekday, Month day, year (e.g. "Monday, January 3, 2025")
     def us_format_with_weekday
       "#{strftime('%A')}, #{strftime('%B')} #{day}, #{year}"
     end
 
+    # @return [String] "Weekday, Day<sup>suffix</sup> Month, Year" with textual suffix
     def charmians_format
       d = cardinalation(day)
       "#{strftime('%A')}, #{d} #{strftime('%B')}, #{year}"
     end
 
+    # @return [String] HTML-safe string with ordinal suffix wrapped in `<sup>`
     def charmians_format_sup
       d = cardinalation(day, true)
       "#{strftime('%A')}, #{d} #{strftime('%B')}, #{year}"
@@ -34,12 +41,17 @@ module DateExt
 
     private
 
+    # @param day [Integer]
+    # @param html_sup [Boolean]
+    # @return [String]
     def cardinalation(day, html_sup = false)
       s = suffix day
       s = "<sup>#{s}</sup>" if html_sup
       "#{day}#{s}"
     end
 
+    # @param day [Integer]
+    # @return [String] ordinal suffix for the provided day of month
     def suffix(day)
       case day
       when 1, 21, 31