finrb 1.0.1 → 1.2.0

data/lib/finrb/ratios.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Financial-statement, leverage, and per-share ratios.
@@ -25,9 +26,9 @@ module Finrb
     # @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 = Validation.decimal(cash, name: 'cash')
+      ms = Validation.decimal(ms, name: 'marketable securities')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       ((cash + ms) / cl)
     end
@@ -39,8 +40,8 @@ module Finrb
     # @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 = Validation.decimal(ca, name: 'current assets')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       (ca / cl)
     end
@@ -52,8 +53,8 @@ module Finrb
     # @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 = Validation.decimal(td, name: 'total debt')
+      ta = Validation.non_zero_decimal(ta, name: 'total assets', error: DomainError)
 
       (td / ta)
     end
@@ -81,15 +82,15 @@ module Finrb
     # @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)
+      ni = Validation.decimal(ni, name: 'net income')
+      pd = Validation.decimal(pd, name: 'preferred dividends')
+      w = Validation.positive_decimal(w, name: 'weighted average common shares', error: DomainError)
+      cpd = Validation.non_negative_decimal(cpd, name: 'convertible preferred dividends')
+      cdi = Validation.non_negative_decimal(cdi, name: 'convertible debt interest')
+      tax = Validation.decimal_between(tax, minimum: 0, maximum: 1, name: 'tax rate')
+      cps = Validation.non_negative_decimal(cps, name: 'convertible preferred shares')
+      cds = Validation.non_negative_decimal(cds, name: 'convertible debt shares')
+      iss = Validation.non_negative_decimal(iss, name: 'incremental option shares')
 
       basic = (ni - pd) / w
       diluted = (ni - pd + cpd + (cdi * (1 - tax))) / (w + cps + cds + iss)
@@ -105,9 +106,9 @@ module Finrb
     # @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 = Validation.decimal(ni, name: 'net income')
+      pd = Validation.decimal(pd, name: 'preferred dividends')
+      w = Validation.positive_decimal(w, name: 'weighted average common shares', error: DomainError)
 
       ((ni - pd) / w)
     end
@@ -119,8 +120,8 @@ module Finrb
     # @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)
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
+      ta = Validation.decimal(ta, name: 'total assets')
 
       (ta / te)
     end
@@ -132,8 +133,8 @@ module Finrb
     # @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 = Validation.decimal(gp, name: 'gross profit')
+      rv = Validation.non_zero_decimal(rv, name: 'revenue', error: DomainError)
 
       (gp / rv)
     end
@@ -146,14 +147,14 @@ module Finrb
     # @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)
+      amp = Validation.positive_decimal(amp, name: 'average market price', error: DomainError)
+      ep = Validation.non_negative_decimal(ep, name: 'exercise price')
+      n = Validation.non_negative_decimal(n, name: 'option shares')
 
       if amp > ep
         ((amp - ep) * n / amp)
       else
-        raise(Error, 'amp must larger than ep')
+        raise(DomainError, 'Average market price must be greater than exercise price.')
       end
     end
 
@@ -164,8 +165,8 @@ module Finrb
     # @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 = Validation.decimal(ltd, name: 'long-term debt')
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
 
       (ltd / te)
     end
@@ -177,8 +178,8 @@ module Finrb
     # @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 = Validation.decimal(ni, name: 'net income')
+      rv = Validation.non_zero_decimal(rv, name: 'revenue', error: DomainError)
 
       (ni / rv)
     end
@@ -192,10 +193,10 @@ module Finrb
     # @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 = Validation.decimal(cash, name: 'cash')
+      ms = Validation.decimal(ms, name: 'marketable securities')
+      rc = Validation.decimal(rc, name: 'receivables')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       ((cash + ms + rc) / cl)
     end
@@ -207,8 +208,8 @@ module Finrb
     # @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 = Validation.decimal(td, name: 'total debt')
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
 
       (td / te)
     end
@@ -223,8 +224,8 @@ module Finrb
     # @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) }
+      ns = wrap_array(ns).map { |value| Validation.decimal(value, name: 'share change') }
+      nm = wrap_array(nm).map { |value| Validation.decimal_between(value, minimum: 0, maximum: 12, name: 'months outstanding') }
 
       m = ns.size
       n = nm.size
@@ -234,7 +235,7 @@ module Finrb
           sum += (ns[i] * nm[i])
         end
       else
-        raise(Error, 'length of ns and nm must be equal')
+        raise(ArgumentError, 'Share changes and months outstanding must have equal lengths.')
       end
       sum /= 12
       sum

data/lib/finrb/returns.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Investment return and risk-adjusted performance calculations.
@@ -17,6 +18,102 @@ module Finrb
     end
     private_class_method :wrap_array
 
+    # Compound annual growth rate over a positive number of periods.
+    #
+    # Beginning value must be positive. Ending value may be zero, representing
+    # a total loss, but cannot be negative because a fractional growth root
+    # would not have a generally meaningful real-valued result.
+    #
+    # @param beginning_value [Numeric] value at the start of the measurement
+    # @param ending_value [Numeric] value at the end of the measurement
+    # @param periods [Integer] number of equal annual periods
+    # @return [Flt::DecNum] compound growth rate per period
+    def self.cagr(beginning_value:, ending_value:, periods:)
+      beginning_value = Validation.positive_decimal(beginning_value, name: 'beginning value')
+      ending_value = Validation.non_negative_decimal(ending_value, name: 'ending value')
+      periods = Validation.positive_integer(periods, name: 'period count')
+
+      ((ending_value / beginning_value)**(Flt::DecNum(1) / periods)) - 1
+    end
+
+    def self.risk_values(values, name:)
+      values = wrap_array(values)
+      raise(ArgumentError, "#{name} cannot be empty.") if values.empty?
+
+      values.map { |value| Validation.decimal(value, name:) }
+    end
+    private_class_method :risk_values
+
+    # Compound a periodic return into an annual return.
+    def self.annualize_return(rate:, periods_per_year:)
+      rate = Validation.decimal_at_least(rate, minimum: -1, name: 'periodic rate')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
+
+      ((rate + 1)**periods_per_year) - 1
+    end
+
+    # Scale periodic volatility by the square root of periods per year.
+    def self.annualize_volatility(volatility:, periods_per_year:)
+      volatility = Validation.non_negative_decimal(volatility, name: 'volatility')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
+
+      volatility * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
+    end
+
+    # Standard deviation of periodic returns. Sample volatility uses n - 1;
+    # population volatility uses n.
+    def self.volatility(returns:, sample: true)
+      raise(ArgumentError, 'sample must be true or false.') unless [true, false].include?(sample)
+
+      returns = risk_values(returns, name: 'return')
+      raise(ArgumentError, 'sample volatility requires at least two returns.') if sample && returns.size < 2
+
+      mean = returns.sum / returns.size
+      denominator = sample ? returns.size - 1 : returns.size
+      variance = returns.sum { |value| (value - mean)**2 } / denominator
+      variance**Flt::DecNum('0.5')
+    end
+
+    # Root-mean-square return shortfall below a target return. The denominator
+    # includes every observation, including returns at or above the target.
+    def self.downside_deviation(returns:, target: 0)
+      returns = risk_values(returns, name: 'return')
+      target = Validation.decimal(target, name: 'target')
+      squared_shortfalls =
+        returns.sum do |value|
+          shortfall = [value - target, Flt::DecNum(0)].min
+          shortfall**2
+        end
+
+      (squared_shortfalls / returns.size)**Flt::DecNum('0.5')
+    end
+
+    # Sortino ratio using arithmetic mean excess return and downside deviation.
+    def self.sortino_ratio(returns:, target: 0, periods_per_year: nil)
+      returns = risk_values(returns, name: 'return')
+      target = Validation.decimal(target, name: 'target')
+      downside = downside_deviation(returns:, target:)
+      raise(ArgumentError, 'downside deviation must be greater than zero.') if downside.zero?
+
+      ratio = ((returns.sum / returns.size) - target) / downside
+      return ratio if periods_per_year.nil?
+
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
+      ratio * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
+    end
+
+    # Largest peak-to-trough decline as a non-negative fraction.
+    def self.max_drawdown(values:)
+      values = risk_values(values, name: 'value')
+      raise(ArgumentError, 'values must be greater than zero.') unless values.all?(&:positive?)
+
+      peak = values.first
+      values.reduce(Flt::DecNum(0)) do |maximum, value|
+        peak = value if value > peak
+        [maximum, (peak - value) / peak].max
+      end
+    end
+
     # Computing Coefficient of variation
     #
     # @param sd standard deviation
@@ -24,8 +121,9 @@ module Finrb
     # @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 = Validation.non_negative_decimal(sd, name: 'standard deviation')
+      avg = Validation.decimal(avg, name: 'average')
+      raise(DomainError, 'Average must be non-zero.') if avg.zero?
 
       (sd / avg)
     end
@@ -36,10 +134,13 @@ module Finrb
     # @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) }
+      returns = risk_values(r, name: 'return')
+      returns.each do |value|
+        raise(DomainError, 'Returns must be greater than or equal to -1.') if value < -1
+      end
 
-      rs = r.map { |value| value + 1 }
-      ((rs.reduce(:*)**(Flt::DecNum(1) / rs.size)) - 1)
+      growth_factors = returns.map { |value| value + 1 }
+      ((growth_factors.reduce(:*)**(Flt::DecNum(1) / growth_factors.size)) - 1)
     end
 
     # harmonic mean, average price
@@ -47,9 +148,10 @@ module Finrb
     # @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) }
+      prices = risk_values(p, name: 'price')
+      raise(DomainError, 'Prices must be greater than zero.') unless prices.all?(&:positive?)
 
-      (Flt::DecNum(1) / (p.sum { |val| Flt::DecNum(1) / val } / p.size))
+      (Flt::DecNum(1) / (prices.sum { |price| Flt::DecNum(1) / price } / prices.size))
     end
 
     # Computing HPR, the holding period return
@@ -60,9 +162,9 @@ module Finrb
     # @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 = Validation.decimal(ev, name: 'ending value')
+      bv = Validation.positive_decimal(bv, name: 'beginning value', error: DomainError)
+      cfr = Validation.decimal(cfr, name: 'cashflow received')
 
       ((ev - bv + cfr) / bv)
     end
@@ -74,8 +176,8 @@ module Finrb
     # @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 = Validation.decimal(sm, name: 'sample mean')
+      mu = Validation.decimal(mu, name: 'population mean')
 
       (sm - mu)
     end
@@ -88,9 +190,9 @@ module Finrb
     # @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 = Validation.decimal(rp, name: 'portfolio return')
+      rl = Validation.decimal(rl, name: 'threshold return')
+      sd = Validation.positive_decimal(sd, name: 'standard deviation', error: DomainError)
 
       ((rp - rl) / sd)
     end
@@ -103,9 +205,9 @@ module Finrb
     # @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 = Validation.decimal(rp, name: 'portfolio return')
+      rf = Validation.decimal(rf, name: 'risk-free return')
+      sd = Validation.positive_decimal(sd, name: 'standard deviation', error: DomainError)
 
       ((rp - rf) / sd)
     end
@@ -118,22 +220,20 @@ module Finrb
     # @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)
+      ending_values = risk_values(ev, name: 'ending value')
+      beginning_values = risk_values(bv, name: 'beginning value')
+      cashflows_received = risk_values(cfr, name: 'cashflow received')
+      sizes = [ending_values.size, beginning_values.size, cashflows_received.size]
+      raise(ArgumentError, 'Ending values, beginning values, and cashflows received must have equal lengths.') unless sizes.uniq.one?
+
+      wealth_relative =
+        ending_values.each_index.reduce(Flt::DecNum(1)) do |product, index|
+          period_growth = hpr(ev: ending_values[index], bv: beginning_values[index], cfr: cashflows_received[index]) + 1
+          raise(DomainError, 'Each subperiod wealth relative must be greater than or equal to zero.') if period_growth.negative?
+
+          product * period_growth
         end
-        ((wr**(Flt::DecNum(1) / r)) - 1)
-      end
+      (wealth_relative**(Flt::DecNum(1) / ending_values.size)) - 1
     end
 
     # Weighted mean as a portfolio return
@@ -143,13 +243,12 @@ module Finrb
     # @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
+      returns = risk_values(r, name: 'return')
+      weights = risk_values(w, name: 'weight')
+      raise(ArgumentError, 'Returns and weights must have equal lengths.') unless returns.size == weights.size
+      raise(ArgumentError, 'Weights must sum to 1.') unless weights.sum == 1
 
-      r.zip(w).sum { |arr| arr.reduce(:*) }
+      returns.zip(weights).sum { |rate, weight| rate * weight }
     end
   end
 end

data/lib/finrb/transaction.rb

@@ -4,17 +4,13 @@ require_relative 'validation'
 
 module Finrb
   # the Transaction class provides a general interface for working with individual cash flows.
-  # @api public
   class Transaction
     # @return [Flt::DecNum] the cash value of the transaction
-    # @api public
     attr_reader :amount
     # @return [Integer] the period number of the transaction
     # @note this attribute is mainly used in the case of mortgage amortization with no dates
-    # @api public
     attr_reader :period
     # @return [Date] the date of the transaction
-    # @api public
     attr_reader :date
 
     # create a new Transaction
@@ -26,7 +22,6 @@ module Finrb
     #   t = Transaction.new(400)
     # @example a transaction with a period number
     #   t = Transaction.new(400, :period => 3)
-    # @api public
     def initialize(amount, opts = {})
       raise(ArgumentError, 'options must be a Hash.') unless opts.is_a?(Hash)
       raise(ArgumentError, 'options may only contain date and period.') unless (opts.keys - %i[date period]).empty?
@@ -47,7 +42,6 @@ module Finrb
     #   t = Transaction.new(500)
     #   t.amount = 750
     #   t.amount #=> 750
-    # @api public
     def amount=(value)
       @amount = Validation.decimal(value, name: 'amount')
     end
@@ -71,7 +65,6 @@ module Finrb
     #   t = Transaction.new(500)
     #   t.amount = 750
     #   t.difference #=> Flt::DecNum('250')
-    # @api public
     def difference
       @amount - @original
     end
@@ -82,12 +75,10 @@ module Finrb
     #   int = Interest.new(500)
     #   pmt.interest? #=> False
     #   int.interest? #=> True
-    # @api public
     def interest?
       instance_of?(Interest)
     end
 
-    # @api public
     def inspect
       "Transaction(#{@amount.round(2)}, date: #{@date})"
     end
@@ -99,7 +90,6 @@ module Finrb
     #   pmt = Payment.new(-500)
     #   pmt.modify { |t| t.amount-100 }
     #   pmt.amount #=> -600
-    # @api public
     def modify
       self.amount = yield(self)
     end
@@ -116,7 +106,6 @@ module Finrb
     #   int = Interest.new(500)
     #   pmt.payment? #=> True
     #   int.payment? #=> False
-    # @api public
     def payment?
       instance_of?(Payment)
     end