finrb 0.1.12 → 1.0.0

data/lib/finrb/numerical/rate_search.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'flt'
+require_relative '../errors'
+
+module Finrb
+  module Numerical
+    # Locates the nearest sign-changing rate interval around a caller's guess.
+    # Search happens in log(1 + rate) space, which covers the entire financial
+    # domain rate > -1 without stepping across its singular boundary.
+    class RateSearch
+      DEFAULT_STEP = '0.125'
+      DEFAULT_MAX_STEPS = 256
+      private_constant :DEFAULT_STEP, :DEFAULT_MAX_STEPS
+
+      def initialize(step: DEFAULT_STEP, max_steps: DEFAULT_MAX_STEPS)
+        @step = decimal(step)
+        @max_steps = Integer(max_steps)
+
+        raise(ArgumentError, 'Search step must be positive.') unless @step.positive?
+        raise(ArgumentError, 'Maximum search steps must be positive.') unless @max_steps.positive?
+      end
+
+      def bracket(function, guess:)
+        guess = decimal(guess)
+        raise(DomainError, 'Rate guess must be greater than -1.') if guess <= -1
+
+        center_coordinate = (guess + 1).ln
+        center = [guess, evaluate(function, guess)]
+        return [guess, guess] if center.last.zero?
+
+        left = center
+        right = center
+
+        1.upto(@max_steps) do |distance|
+          next_left = point(function, center_coordinate - (@step * distance))
+          next_right = point(function, center_coordinate + (@step * distance))
+          candidates = []
+          candidates << [next_left.first, left.first] if opposite_signs?(next_left.last, left.last)
+          candidates << [right.first, next_right.first] if opposite_signs?(right.last, next_right.last)
+          return nearest(candidates, guess) unless candidates.empty?
+
+          left = next_left
+          right = next_right
+        end
+
+        raise(ConvergenceError, "Could not bracket a root near guess #{guess}.")
+      end
+
+      private
+
+      def point(function, coordinate)
+        rate = coordinate.exp - 1
+        [rate, evaluate(function, rate)]
+      end
+
+      def evaluate(function, rate)
+        result = decimal(function.call(rate))
+        raise(DomainError, "Rate function returned a non-finite value at #{rate}.") unless result.finite?
+
+        result
+      rescue Flt::Num::Exception, FloatDomainError, Math::DomainError, ZeroDivisionError => e
+        raise(DomainError, "Rate function is undefined at #{rate}: #{e.message}", e.backtrace)
+      end
+
+      def nearest(candidates, guess)
+        candidates.min_by { |lower, upper| (((lower + upper) / 2) - guess).abs }
+      end
+
+      def opposite_signs?(left, right)
+        left.negative? != right.negative?
+      end
+
+      def decimal(value)
+        Flt::DecNum.new(value.to_s)
+      end
+    end
+  end
+end

data/lib/finrb/precision.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module Finrb
+  # Explicit quantization policy for values rounded during calculations.
+  # General calculations otherwise retain the active Flt::DecNum context.
+  module Precision
+    MONEY_PLACES = 2
+    RATE_PLACES = 15
+    ROUNDING_MODE = :half_up
+    public_constant :MONEY_PLACES, :RATE_PLACES, :ROUNDING_MODE
+
+    module_function
+
+    def money(value)
+      round(value, places: MONEY_PLACES)
+    end
+
+    def rate(value)
+      round(value, places: RATE_PLACES)
+    end
+
+    def round(value, places:)
+      Validation.decimal(value, name: 'value').round(places, rounding: ROUNDING_MODE)
+    end
+    private_class_method :round
+  end
+end

data/lib/finrb/rates.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'decimal'
+require_relative 'precision'
+require_relative 'validation'
 
 module Finrb
   # the Rate class provides an interface for working with interest rates.
@@ -10,9 +11,20 @@ module Finrb
     include Comparable
 
     # Accepted rate types
-    TYPES = { apr: 'effective', apy: 'effective', effective: 'effective', nominal: 'nominal' }.freeze
+    TYPES = { apr: 'nominal', apy: 'effective', effective: 'effective', nominal: 'nominal' }.freeze
     public_constant :TYPES
 
+    def self.compounding_periods(value)
+      infinite = value.infinite? if value.respond_to?(:infinite?)
+      return Flt::DecNum.infinity if [true, 1].include?(infinite)
+
+      periods = Validation.decimal(value, name: 'compounding periods')
+      raise(ArgumentError, 'compounding periods must be positive.') unless periods.positive?
+
+      periods
+    end
+    private_class_method :compounding_periods
+
     # convert a nominal interest rate to an effective interest rate
     # @return [Flt::DecNum] the effective interest rate
     # @param [Numeric] rate the nominal interest rate
@@ -21,8 +33,8 @@ module Finrb
     #   Rate.to_effective(0.05, 4) #=> Flt::DecNum('0.05095')
     # @api public
     def self.to_effective(rate, periods)
-      rate = Flt::DecNum.new(rate.to_s)
-      periods = Flt::DecNum.new(periods.to_s)
+      rate = Validation.decimal(rate, name: 'rate')
+      periods = compounding_periods(periods)
 
       if periods.infinite?
         rate.exp - 1
@@ -40,13 +52,15 @@ module Finrb
     # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
     # @api public
     def self.to_nominal(rate, periods)
-      rate = Flt::DecNum.new(rate.to_s)
-      periods = Flt::DecNum.new(periods.to_s)
+      rate = Validation.decimal(rate, name: 'rate')
+      raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
+
+      periods = compounding_periods(periods)
 
       if periods.infinite?
         (rate + 1).log
       else
-        periods * (((rate + 1)**(1.to_f / periods)) - 1)
+        periods * (((rate + 1)**(Flt::DecNum.new(1) / periods)) - 1)
       end
     end
 
@@ -63,6 +77,9 @@ module Finrb
     # @see https://en.wikipedia.org/wiki/Nominal_interest_rate
     # @api public
     def initialize(rate, type, opts = {})
+      raise(ArgumentError, 'options must be a Hash.') unless opts.is_a?(Hash)
+      raise(ArgumentError, 'options may only contain compounds and duration.') unless (opts.keys - %i[compounds duration]).empty?
+
       # Default monthly compounding.
       opts = { compounds: :monthly }.merge(opts)
 
@@ -73,7 +90,7 @@ module Finrb
 
       # Set the rate in the proper way, based on the value of type.
       begin
-        __send__(:"#{TYPES.fetch(type)}=", Flt::DecNum.new(rate.to_s))
+        __send__(:"#{TYPES.fetch(type)}=", Validation.decimal(rate, name: 'rate'))
       rescue KeyError
         raise(ArgumentError, "type must be one of #{TYPES.keys.join(', ')}", caller)
       end
@@ -81,7 +98,7 @@ module Finrb
 
     # @return [Integer] the duration for which the rate is valid, in months
     # @api public
-    attr_accessor :duration
+    attr_reader :duration
     # @return [Flt::DecNum] the effective interest rate
     # @api public
     attr_reader :effective
@@ -101,13 +118,15 @@ module Finrb
       @effective <=> other.effective
     end
 
-    # (see #effective)
+    # Return the nominal annual percentage rate for the configured compounding frequency.
+    # @return [Flt::DecNum] the nominal annual percentage rate
     # @api public
     def apr
-      effective
+      nominal
     end
 
-    # (see #effective)
+    # Return the effective annual percentage yield.
+    # @return [Flt::DecNum] the effective annual percentage yield
     # @api public
     def apy
       effective
@@ -127,16 +146,22 @@ module Finrb
         when :monthly      then Flt::DecNum.new(12)
         when :quarterly    then Flt::DecNum.new(4)
         when :semiannually then Flt::DecNum.new(2)
-        when Numeric       then Flt::DecNum.new(input.to_s)
-        else raise(ArgumentError)
+        when Numeric       then self.class.__send__(:compounding_periods, input)
+        else raise(ArgumentError, 'compounds must be a known frequency or a positive number.')
         end
     end
 
+    def duration=(value)
+      @duration = Validation.positive_integer(value, name: 'duration')
+    end
+
     # set the effective interest rate
     # @return none
     # @param [Flt::DecNum] rate the effective interest rate
     # @api private
     def effective=(rate)
+      raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
+
       @effective = rate
       @nominal = Rate.to_nominal(rate, @periods)
     end
@@ -145,14 +170,15 @@ module Finrb
       "Rate.new(#{apr.round(6)}, :apr)"
     end
 
-    # @return [Flt::DecNum] the monthly effective interest rate
+    # @return [Flt::DecNum] the equivalent monthly effective interest rate
     # @example
     #   rate = Rate.new(0.15, :nominal)
-    #   rate.apr.round(6) #=> Flt::DecNum('0.160755')
-    #   rate.monthly.round(6) #=> Flt::DecNum('0.013396')
+    #   rate.apr.round(6) #=> Flt::DecNum('0.15')
+    #   rate.apy.round(6) #=> Flt::DecNum('0.160755')
+    #   rate.monthly.round(6) #=> Flt::DecNum('0.0125')
     # @api public
     def monthly
-      (effective / 12).round(15)
+      @monthly ||= Precision.rate(Rate.to_nominal(effective, 12) / 12)
     end
 
     # set the nominal interest rate
@@ -160,6 +186,8 @@ module Finrb
     # @param [Flt::DecNum] rate the nominal interest rate
     # @api private
     def nominal=(rate)
+      raise(ArgumentError, 'nominal rate must keep every compounded period greater than -100%.') if !@periods.infinite? && rate <= -@periods
+
       @nominal = rate
       @effective = Rate.to_effective(rate, @periods)
     end

data/lib/finrb/ratios.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+require_relative 'errors'
+
+module Finrb
+  # Financial-statement, leverage, and per-share ratios.
+  module Ratios
+    def self.wrap_array(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary || [object]
+      else
+        [object]
+      end
+    end
+    private_class_method :wrap_array
+
+    # cash ratio -- Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+    #
+    # @param cash cash
+    # @param ms   marketable securities
+    # @param cl   current liabilities
+    # @example
+    #   Finrb::Ratios.cash_ratio(cash=3000,ms=2000,cl=2000)
+    def self.cash_ratio(cash:, ms:, cl:)
+      cash = Flt::DecNum(cash.to_s)
+      ms = Flt::DecNum(ms.to_s)
+      cl = Flt::DecNum(cl.to_s)
+
+      ((cash + ms) / cl)
+    end
+
+    # current ratio -- Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+    #
+    # @param ca current assets
+    # @param cl current liabilities
+    # @example
+    #   Finrb::Ratios.current_ratio(ca=8000,cl=2000)
+    def self.current_ratio(ca:, cl:)
+      ca = Flt::DecNum(ca.to_s)
+      cl = Flt::DecNum(cl.to_s)
+
+      (ca / cl)
+    end
+
+    # debt ratio -- Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+    #
+    # @param td total debt
+    # @param ta total assets
+    # @example
+    #   Finrb::Ratios.debt_ratio(td=6000,ta=20000)
+    def self.debt_ratio(td:, ta:)
+      td = Flt::DecNum(td.to_s)
+      ta = Flt::DecNum(ta.to_s)
+
+      (td / ta)
+    end
+
+    # diluted Earnings Per Share
+    #
+    # @param ni     net income
+    # @param pd     preferred dividends
+    # @param cpd    dividends on convertible preferred stock
+    # @param cdi    interest on convertible debt
+    # @param tax    tax rate
+    # @param w      weighted average number of common shares outstanding
+    # @param cps    shares from conversion of convertible preferred stock
+    # @param cds    shares from conversion of convertible debt
+    # @param iss    shares issuable from stock options
+    # @example
+    #   Finrb::Ratios.diluted_eps(ni=115600,pd=10000,cdi=42000,tax=0.4,w=200000,cds=60000)
+    #
+    # @example
+    #   Finrb::Ratios.diluted_eps(ni=115600,pd=10000,cpd=10000,w=200000,cps=40000)
+    #
+    # @example
+    #   Finrb::Ratios.diluted_eps(ni=115600,pd=10000,w=200000,iss=2500)
+    #
+    # @example
+    #   Finrb::Ratios.diluted_eps(ni=115600,pd=10000,cpd=10000,cdi=42000,tax=0.4,w=200000,cps=40000,cds=60000,iss=2500)
+    def self.diluted_eps(ni:, pd:, w:, cpd: 0, cdi: 0, tax: 0, cps: 0, cds: 0, iss: 0)
+      ni = Flt::DecNum(ni.to_s)
+      pd = Flt::DecNum(pd.to_s)
+      w = Flt::DecNum(w.to_s)
+      cpd = Flt::DecNum(cpd.to_s)
+      cdi = Flt::DecNum(cdi.to_s)
+      tax = Flt::DecNum(tax.to_s)
+      cps = Flt::DecNum(cps.to_s)
+      cds = Flt::DecNum(cds.to_s)
+      iss = Flt::DecNum(iss.to_s)
+
+      basic = (ni - pd) / w
+      diluted = (ni - pd + cpd + (cdi * (1 - tax))) / (w + cps + cds + iss)
+      diluted = (ni - pd + cpd) / (w + cps + iss) if diluted > basic
+      diluted
+    end
+
+    # Basic Earnings Per Share
+    #
+    # @param ni net income
+    # @param pd preferred dividends
+    # @param w  weighted average number of common shares outstanding
+    # @example
+    #   Finrb::Ratios.eps(ni=10000,pd=1000,w=11000)
+    def self.eps(ni:, pd:, w:)
+      ni = Flt::DecNum(ni.to_s)
+      pd = Flt::DecNum(pd.to_s)
+      w = Flt::DecNum(w.to_s)
+
+      ((ni - pd) / w)
+    end
+
+    # financial leverage -- Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+    #
+    # @param te total equity
+    # @param ta total assets
+    # @example
+    #   Finrb::Ratios.financial_leverage(te=16000,ta=20000)
+    def self.financial_leverage(te:, ta:)
+      te = Flt::DecNum(te.to_s)
+      ta = Flt::DecNum(ta.to_s)
+
+      (ta / te)
+    end
+
+    # gross profit margin -- Evaluate a company's financial performance
+    #
+    # @param gp gross profit, equal to revenue minus cost of goods sold (cogs)
+    # @param rv revenue (sales)
+    # @example
+    #   Finrb::Ratios.gpm(gp=1000,rv=20000)
+    def self.gpm(gp:, rv:)
+      gp = Flt::DecNum(gp.to_s)
+      rv = Flt::DecNum(rv.to_s)
+
+      (gp / rv)
+    end
+
+    # calculate the net increase in common shares from the potential exercise of stock options or warrants
+    #
+    # @param amp average market price over the year
+    # @param ep  exercise price of the options or warrants
+    # @param n   number of common shares that the options and warrants can be convened into
+    # @example
+    #   Finrb::Ratios.iss(amp=20,ep=15,n=10000)
+    def self.iss(amp:, ep:, n:)
+      amp = Flt::DecNum(amp.to_s)
+      ep = Flt::DecNum(ep.to_s)
+      n = Flt::DecNum(n.to_s)
+
+      if amp > ep
+        ((amp - ep) * n / amp)
+      else
+        raise(Error, 'amp must larger than ep')
+      end
+    end
+
+    # long-term debt-to-equity -- Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+    #
+    # @param ltd long-term debt
+    # @param te  total equity
+    # @example
+    #   Finrb::Ratios.lt_d2e(ltd=8000,te=20000)
+    def self.lt_d2e(ltd:, te:)
+      ltd = Flt::DecNum(ltd.to_s)
+      te = Flt::DecNum(te.to_s)
+
+      (ltd / te)
+    end
+
+    # net profit margin -- Evaluate a company's financial performance
+    #
+    # @param ni net income
+    # @param rv revenue (sales)
+    # @example
+    #   Finrb::Ratios.npm(ni=8000,rv=20000)
+    def self.npm(ni:, rv:)
+      ni = Flt::DecNum(ni.to_s)
+      rv = Flt::DecNum(rv.to_s)
+
+      (ni / rv)
+    end
+
+    # quick ratio -- Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+    #
+    # @param cash cash
+    # @param ms   marketable securities
+    # @param rc   receivables
+    # @param cl   current liabilities
+    # @example
+    #   Finrb::Ratios.quick_ratio(cash=3000,ms=2000,rc=1000,cl=2000)
+    def self.quick_ratio(cash:, ms:, rc:, cl:)
+      cash = Flt::DecNum(cash.to_s)
+      ms = Flt::DecNum(ms.to_s)
+      rc = Flt::DecNum(rc.to_s)
+      cl = Flt::DecNum(cl.to_s)
+
+      ((cash + ms + rc) / cl)
+    end
+
+    # total debt-to-equity -- Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+    #
+    # @param td total debt
+    # @param te total equity
+    # @example
+    #   Finrb::Ratios.total_d2e(td=6000,te=20000)
+    def self.total_d2e(td:, te:)
+      td = Flt::DecNum(td.to_s)
+      te = Flt::DecNum(te.to_s)
+
+      (td / te)
+    end
+
+    # calculate weighted average shares -- weighted average number of common shares
+    #
+    # @param ns n x 1 vector vector of number of shares
+    # @param nm n x 1 vector vector of number of months relate to ns
+    # @example
+    #   s=[10000,2000];m=[12,6];Finrb::Ratios.was(ns=s,nm=m)
+    #
+    # @example
+    #   s=[11000,4400,-3000];m=[12,9,4];Finrb::Ratios.was(ns=s,nm=m)
+    def self.was(ns:, nm:)
+      ns = wrap_array(ns).map { |value| Flt::DecNum(value.to_s) }
+      nm = wrap_array(nm).map { |value| Flt::DecNum(value.to_s) }
+
+      m = ns.size
+      n = nm.size
+      sum = 0
+      if m == n
+        (0...m).each do |i|
+          sum += (ns[i] * nm[i])
+        end
+      else
+        raise(Error, 'length of ns and nm must be equal')
+      end
+      sum /= 12
+      sum
+    end
+  end
+end

data/lib/finrb/returns.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+require_relative 'errors'
+
+module Finrb
+  # Investment return and risk-adjusted performance calculations.
+  module Returns
+    def self.wrap_array(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary || [object]
+      else
+        [object]
+      end
+    end
+    private_class_method :wrap_array
+
+    # Computing Coefficient of variation
+    #
+    # @param sd standard deviation
+    # @param avg average value
+    # @example
+    #   Finrb::Returns.coefficient_variation(sd=0.15,avg=0.39)
+    def self.coefficient_variation(sd:, avg:)
+      sd = Flt::DecNum(sd.to_s)
+      avg = Flt::DecNum(avg.to_s)
+
+      (sd / avg)
+    end
+
+    # Geometric mean return
+    #
+    # @param r returns over multiple periods
+    # @example
+    #   Finrb::Returns.geometric_mean(r=[-0.0934, 0.2345, 0.0892])
+    def self.geometric_mean(r:)
+      r = wrap_array(r).map { |value| Flt::DecNum(value.to_s) }
+
+      rs = r.map { |value| value + 1 }
+      ((rs.reduce(:*)**(Flt::DecNum(1) / rs.size)) - 1)
+    end
+
+    # harmonic mean, average price
+    # @param p price over multiple periods
+    # @example
+    #   Finrb::Returns.harmonic_mean(p=[8,9,10])
+    def self.harmonic_mean(p:)
+      p = wrap_array(p).map { |value| Flt::DecNum(value.to_s) }
+
+      (Flt::DecNum(1) / (p.sum { |val| Flt::DecNum(1) / val } / p.size))
+    end
+
+    # Computing HPR, the holding period return
+    #
+    # @param ev ending value
+    # @param bv beginning value
+    # @param cfr cash flow received
+    # @example
+    #   Finrb::Returns.hpr(ev=33,bv=30,cfr=0.5)
+    def self.hpr(ev:, bv:, cfr: 0)
+      ev = Flt::DecNum(ev.to_s)
+      bv = Flt::DecNum(bv.to_s)
+      cfr = Flt::DecNum(cfr.to_s)
+
+      ((ev - bv + cfr) / bv)
+    end
+
+    # Computing Sampling error
+    #
+    # @param sm sample mean
+    # @param mu population mean
+    # @example
+    #   Finrb::Returns.sampling_error(sm=0.45, mu=0.5)
+    def self.sampling_error(sm:, mu:)
+      sm = Flt::DecNum(sm.to_s)
+      mu = Flt::DecNum(mu.to_s)
+
+      (sm - mu)
+    end
+
+    # Computing Roy's safety-first ratio
+    #
+    # @param rp portfolio return
+    # @param rl threshold level return
+    # @param sd standard deviation of portfolio retwns
+    # @example
+    #   Finrb::Returns.sf_ratio(rp=0.09,rl=0.03,sd=0.12)
+    def self.sf_ratio(rp:, rl:, sd:)
+      rp = Flt::DecNum(rp.to_s)
+      rl = Flt::DecNum(rl.to_s)
+      sd = Flt::DecNum(sd.to_s)
+
+      ((rp - rl) / sd)
+    end
+
+    # Computing Sharpe Ratio
+    #
+    # @param rp portfolio return
+    # @param rf risk-free return
+    # @param sd standard deviation of portfolio retwns
+    # @example
+    #   Finrb::Returns.sharpe_ratio(rp=0.038,rf=0.015,sd=0.07)
+    def self.sharpe_ratio(rp:, rf:, sd:)
+      rp = Flt::DecNum(rp.to_s)
+      rf = Flt::DecNum(rf.to_s)
+      sd = Flt::DecNum(sd.to_s)
+
+      ((rp - rf) / sd)
+    end
+
+    # Computing TWRR, the time-weighted rate of return
+    #
+    # @param ev ordered ending value list
+    # @param bv ordered beginning value list
+    # @param cfr ordered cash flow received list
+    # @example
+    #   Finrb::Returns.twrr(ev=[120,260],bv=[100,240],cfr=[2,4])
+    def self.twrr(ev:, bv:, cfr:)
+      ev = wrap_array(ev).map { |value| Flt::DecNum(value.to_s) }
+      bv = wrap_array(bv).map { |value| Flt::DecNum(value.to_s) }
+      cfr = wrap_array(cfr).map { |value| Flt::DecNum(value.to_s) }
+
+      r = ev.size
+      s = bv.size
+      t = cfr.size
+      wr = Flt::DecNum(1)
+      if r != s || r != t || s != t
+        raise(Error, 'Different number of values!')
+      else
+        (0...r).each do |i|
+          wr *= (Finrb::Returns.hpr(ev: ev[i], bv: bv[i], cfr: cfr[i]) + 1)
+        end
+        ((wr**(Flt::DecNum(1) / r)) - 1)
+      end
+    end
+
+    # Weighted mean as a portfolio return
+    #
+    # @param r returns of the individual assets in the portfolio
+    # @param w corresponding weights associated with each of the individual assets
+    # @example
+    #   Finrb::Returns.wpr(r=[0.12, 0.07, 0.03],w=[0.5,0.4,0.1])
+    def self.wpr(r:, w:)
+      r = wrap_array(r).map { |value| Flt::DecNum(value.to_s) }
+      w = wrap_array(w).map { |value| Flt::DecNum(value.to_s) }
+
+      # TODO: need to change
+      puts('sum of weights is NOT equal to 1!') if w.sum != 1
+
+      r.zip(w).sum { |arr| arr.reduce(:*) }
+    end
+  end
+end