finrb 1.0.1 → 1.2.0

data/lib/finrb/tvm.rb

@@ -4,123 +4,225 @@ require_relative 'config'
 require_relative 'decimal'
 require_relative 'errors'
 require_relative 'numerical/brent'
+require_relative 'numerical/rate_search'
+require_relative 'validation'
 
 module Finrb
   # Time-value-of-money calculations for periodic rates and cashflows.
   module TVM
     module_function
 
-    def discount_rate(n:, pv:, fv:, pmt:, type: 0, lower: 0.0001, upper: 100)
-      n, pv, fv, pmt, type, lower, upper = decimals(n, pv, fv, pmt, type, lower, upper)
+    UNSET_BOUND = Object.new.freeze
+    private_constant :UNSET_BOUND
+    INPUT_NAMES = { fv: 'future value', g: 'growth rate', guess: 'rate guess', lower: 'lower rate bound', n: 'period count', pmt: 'payment', pv: 'present value', r: 'periodic rate', upper: 'upper rate bound' }.freeze
+    private_constant :INPUT_NAMES
+
+    def discount_rate(n:, pv:, fv:, pmt:, type: 0, guess: nil, lower: UNSET_BOUND, upper: UNSET_BOUND)
+      n = period_count(n)
+      pv, fv, pmt = decimal_inputs(pv:, fv:, pmt:).values
+      type = payment_type(type)
       function = ->(rate) { fv_simple(r: rate, n:, pv:) + fv_annuity(r: rate, n:, pmt:, type:) - fv }
 
-      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(function, lower:, upper:)
+      bounds = rate_bounds(function, guess:, lower:, upper:)
+      return bounds.first if bounds.first == bounds.last
+
+      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(function, lower: bounds.first, upper: bounds.last)
     end
 
     def fv(r:, n:, pv: 0, pmt: 0, type: 0)
-      r, n, pv, pmt, type = decimals(r, n, pv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment_type(type)
 
-      fv_simple(r:, n:, pv:) + fv_annuity(r:, n:, pmt:, type:)
+      fv_simple(r: rate, n: periods, pv:) + fv_annuity(r: rate, n: periods, pmt:, type:)
     end
 
     def fv_annuity(r:, n:, pmt:, type: 0)
-      r, n, pmt, type = decimals(r, n, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment = Validation.decimal(pmt, name: 'payment')
+      payment_timing = payment_type(type)
+      return -payment * periods if rate.zero?
 
-      (pmt / r * (((r + 1)**n) - 1)) * ((r + 1)**type) * -1
+      (payment / rate * (((rate + 1)**periods) - 1)) * ((rate + 1)**payment_timing) * -1
     end
 
     def fv_simple(r:, n:, pv:)
-      r, n, pv = decimals(r, n, pv)
-      (pv * ((r + 1)**n)) * -1
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      present_value = Validation.decimal(pv, name: 'present value')
+      (present_value * ((rate + 1)**periods)) * -1
     end
 
     def fv_uneven(r:, cf:)
-      r = Flt::DecNum(r.to_s)
-      cashflows = array(cf).map { |value| Flt::DecNum(value.to_s) }
+      rate = periodic_rate(r)
+      cashflows = cashflow_values(cf)
 
       cashflows.each_with_index.sum do |cashflow, index|
-        fv_simple(r:, n: cashflows.size - index - 1, pv: cashflow)
+        fv_simple(r: rate, n: cashflows.size - index - 1, pv: cashflow)
       end
     end
 
     def n_period(r:, pv:, fv:, pmt:, type: 0)
-      r, pv, fv, pmt, type = decimals(r, pv, fv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      values = decimal_inputs(pv:, fv:, pmt:)
+      payment_timing = payment_type(type)
+
+      return zero_rate_periods(**values) if rate.zero?
+
+      numerator = ((values[:fv] * rate) - (values[:pmt] * ((rate + 1)**payment_timing))) * -1
+      denominator = (values[:pv] * rate) + (values[:pmt] * ((rate + 1)**payment_timing))
+      periods = (numerator / denominator).log / (rate + 1).log
+      raise(DomainError, 'Inputs do not produce a finite non-negative period count.') unless periods.finite? && !periods.negative?
 
-      numerator = ((fv * r) - (pmt * ((r + 1)**type))) * -1
-      denominator = (pv * r) + (pmt * ((r + 1)**type))
-      (numerator / denominator).log / (r + 1).log
+      periods
+    rescue Flt::Num::Exception, Math::DomainError, ZeroDivisionError => e
+      raise(DomainError, "Inputs do not produce a real period count: #{e.message}", e.backtrace)
     end
 
     def npv(r:, cf:)
-      cashflows = array(cf).map { |value| Flt::DecNum(value.to_s) }
-      (pv_uneven(r:, cf: cashflows.drop(1)) * -1) + cashflows.first
+      rate = periodic_rate(r)
+      cashflows = cashflow_values(cf)
+      return cashflows.first if cashflows.one?
+
+      (pv_uneven(r: rate, cf: cashflows.drop(1)) * -1) + cashflows.first
     end
 
     def pmt(r:, n:, pv:, fv:, type: 0)
-      r, n, pv, fv, type = decimals(r, n, pv, fv, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = positive_period_count(n)
+      values = decimal_inputs(pv:, fv:)
+      payment_timing = payment_type(type)
+      return -(values[:pv] + values[:fv]) / periods if rate.zero?
 
-      (pv + (fv / ((r + 1)**n))) * r / (1 - (Flt::DecNum(1) / ((r + 1)**n))) * -1 * ((r + 1)**(type * -1))
+      (values[:pv] + (values[:fv] / ((rate + 1)**periods))) * rate / (1 - (Flt::DecNum(1) / ((rate + 1)**periods))) * -1 * ((rate + 1)**(payment_timing * -1))
     end
 
     def pv(r:, n:, fv: 0, pmt: 0, type: 0)
-      r, n, fv, pmt, type = decimals(r, n, fv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment_type(type)
 
-      pv_simple(r:, n:, fv:) + pv_annuity(r:, n:, pmt:, type:)
+      pv_simple(r: rate, n: periods, fv:) + pv_annuity(r: rate, n: periods, pmt:, type:)
     end
 
     def pv_annuity(r:, n:, pmt:, type: 0)
-      r, n, pmt, type = decimals(r, n, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment = Validation.decimal(pmt, name: 'payment')
+      payment_timing = payment_type(type)
+      return -payment * periods if rate.zero?
 
-      (pmt / r * (1 - (Flt::DecNum(1) / ((r + 1)**n)))) * ((r + 1)**type) * -1
+      (payment / rate * (1 - (Flt::DecNum(1) / ((rate + 1)**periods)))) * ((rate + 1)**payment_timing) * -1
     end
 
     def pv_perpetuity(r:, pmt:, g: 0, type: 0)
-      r, pmt, g, type = decimals(r, pmt, g, type)
-      validate_payment_type!(type)
-      raise(Error, 'Error: g is not smaller than r!') if g >= r
+      rate = periodic_rate(r)
+      payment = Validation.decimal(pmt, name: 'payment')
+      growth = periodic_rate(g, name: :g)
+      payment_timing = payment_type(type)
+      raise(DomainError, 'Growth rate must be smaller than the discount rate.') if growth >= rate
 
-      (pmt / (r - g)) * ((r + 1)**type) * -1
+      (payment / (rate - growth)) * ((rate + 1)**payment_timing) * -1
     end
 
     def pv_simple(r:, n:, fv:)
-      r, n, fv = decimals(r, n, fv)
-      (fv / ((r + 1)**n)) * -1
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      future_value = Validation.decimal(fv, name: 'future value')
+      (future_value / ((rate + 1)**periods)) * -1
     end
 
     def pv_uneven(r:, cf:)
-      r = Flt::DecNum(r.to_s)
-      array(cf).each_with_index.sum do |cashflow, index|
-        pv_simple(r:, n: index + 1, fv: cashflow)
+      rate = periodic_rate(r)
+      cashflow_values(cf).each_with_index.sum do |cashflow, index|
+        pv_simple(r: rate, n: index + 1, fv: cashflow)
       end
     end
 
     def r_perpetuity(pmt:, pv:)
-      pmt, pv = decimals(pmt, pv)
-      pmt * -1 / pv
+      payment = Validation.decimal(pmt, name: 'payment')
+      present_value = Validation.decimal(pv, name: 'present value')
+      raise(DomainError, 'Present value must be non-zero.') if present_value.zero?
+
+      payment * -1 / present_value
     end
 
-    def array(value)
-      return [] if value.nil?
-      return value.to_ary || [value] if value.respond_to?(:to_ary)
+    def cashflow_values(value)
+      values =
+        if value.nil?
+          []
+        elsif value.respond_to?(:to_ary)
+          value.to_ary || [value]
+        else
+          [value]
+        end
+      raise(ArgumentError, 'cashflows cannot be empty.') if values.empty?
+
+      values.map { |cashflow| Validation.decimal(cashflow, name: 'cashflow') }
+    end
+    private_class_method :cashflow_values
+
+    def decimal_inputs(**values)
+      values.to_h { |name, value| [name, Validation.decimal(value, name: input_name(name))] }
+    end
+    private_class_method :decimal_inputs
+
+    def payment_type(value)
+      value = Validation.decimal(value, name: 'payment timing type')
+      raise(ArgumentError, 'payment timing type must be 0 (end) or 1 (beginning).') unless [Flt::DecNum(0), Flt::DecNum(1)].include?(value)
+
+      value
+    end
+    private_class_method :payment_type
 
-      [value]
+    def period_count(value)
+      Validation.non_negative_decimal(value, name: 'period count', error: DomainError)
     end
-    private_class_method :array
+    private_class_method :period_count
 
-    def decimals(*values)
-      values.map { |value| Flt::DecNum(value.to_s) }
+    def positive_period_count(value)
+      Validation.positive_decimal(value, name: 'period count', error: DomainError)
     end
-    private_class_method :decimals
+    private_class_method :positive_period_count
+
+    def periodic_rate(value, name: :r)
+      Validation.decimal_greater_than(value, minimum: -1, name: input_name(name), error: DomainError)
+    end
+    private_class_method :periodic_rate
+
+    def input_name(name)
+      INPUT_NAMES.fetch(name, name.to_s.tr('_', ' '))
+    end
+    private_class_method :input_name
+
+    def rate_bounds(function, guess:, lower:, upper:)
+      return searched_rate_bounds(function, guess) if lower.equal?(UNSET_BOUND) && upper.equal?(UNSET_BOUND)
+
+      lower = '0.0001' if lower.equal?(UNSET_BOUND)
+      upper = 100 if upper.equal?(UNSET_BOUND)
+      lower = periodic_rate(lower, name: :lower)
+      upper = periodic_rate(upper, name: :upper)
+      raise(ArgumentError, 'lower rate bound must be less than upper rate bound.') if lower >= upper
+
+      [lower, upper]
+    end
+    private_class_method :rate_bounds
+
+    def searched_rate_bounds(function, guess)
+      guess = Finrb.config.guess if guess.nil?
+      Numerical::RateSearch.new.bracket(function, guess: periodic_rate(guess, name: :guess))
+    end
+    private_class_method :searched_rate_bounds
+
+    def zero_rate_periods(pv:, fv:, pmt:)
+      raise(DomainError, 'pmt must be non-zero when solving periods at a zero rate.') if pmt.zero?
+
+      periods = (-pv - fv) / pmt
+      raise(DomainError, 'Inputs do not produce a non-negative period count.') if periods.negative?
 
-    def validate_payment_type!(type)
-      raise(Error, 'Error: type should be 0 or 1!') unless [Flt::DecNum(0), Flt::DecNum(1)].include?(type)
+      periods
     end
-    private_class_method :validate_payment_type!
+    private_class_method :zero_rate_periods
   end
 end

data/lib/finrb/validation.rb

@@ -23,5 +23,47 @@ module Finrb
 
       value
     end
+
+    def positive_decimal(value, name:, error: ArgumentError, message: nil)
+      decimal = decimal(value, name:)
+      raise(error, message || "#{name} must be greater than zero.") unless decimal.positive?
+
+      decimal
+    end
+
+    def non_negative_decimal(value, name:, error: ArgumentError, message: nil)
+      decimal = decimal(value, name:)
+      raise(error, message || "#{name} must be greater than or equal to zero.") if decimal.negative?
+
+      decimal
+    end
+
+    def decimal_greater_than(value, minimum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be greater than #{minimum}.") if decimal <= minimum
+
+      decimal
+    end
+
+    def decimal_at_least(value, minimum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be greater than or equal to #{minimum}.") if decimal < minimum
+
+      decimal
+    end
+
+    def non_zero_decimal(value, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be non-zero.") if decimal.zero?
+
+      decimal
+    end
+
+    def decimal_between(value, minimum:, maximum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be between #{minimum} and #{maximum}, inclusive.") unless decimal.between?(minimum, maximum)
+
+      decimal
+    end
   end
 end

data/lib/finrb/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Finrb
-  VERSION = '1.0.1'
+  VERSION = '1.2.0'
   public_constant :VERSION
 end

data/lib/finrb/yields.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Money-market yield and interest-rate conversion calculations.
@@ -14,9 +15,9 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy(d=1500,f=100000,t=120)
     def self.bdy(d:, f:, t:)
-      d = Flt::DecNum(d.to_s)
-      f = Flt::DecNum(f.to_s)
-      t = Flt::DecNum(t.to_s)
+      d = Validation.decimal(d, name: 'dollar discount')
+      f = Validation.positive_decimal(f, name: 'face value', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (d * 360 / f / t)
     end
@@ -28,10 +29,12 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy2mmy(bdy=0.045,t=120)
     def self.bdy2mmy(bdy:, t:)
-      bdy = Flt::DecNum(bdy.to_s)
-      t = Flt::DecNum(t.to_s)
+      bdy = Validation.decimal(bdy, name: 'bank discount yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
+      denominator = 360 - (t * bdy)
+      raise(DomainError, 'Bank discount yield and time to maturity must imply a positive purchase price.') unless denominator.positive?
 
-      (bdy * 360 / (360 - (t * bdy)))
+      (bdy * 360 / denominator)
     end
 
     # Convert stated annual rate to the effective annual rate
@@ -44,10 +47,10 @@ module Finrb
     # @example
     #   Finrb::Yields.ear(0.04,365)
     def self.ear(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      ((((r / m) + 1)**m) - 1)
+      ((compounding_base(r, m)**m) - 1)
     end
 
     # Convert stated annual rate to the effective annual rate with continuous compounding
@@ -59,7 +62,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear_continuous(0.03)
     def self.ear_continuous(r:)
-      r = Flt::DecNum(r.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
 
       (r.exp - 1)
     end
@@ -70,7 +73,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2bey(ear=0.08)
     def self.ear2bey(ear:)
-      ear = Flt::DecNum(ear.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
 
       (((ear + 1).sqrt - 1) * 2)
     end
@@ -82,8 +85,8 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2hpr(ear=0.05039,t=150)
     def self.ear2hpr(ear:, t:)
-      ear = Flt::DecNum(ear.to_s)
-      t = Flt::DecNum(t.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((ear + 1)**(t / 365)) - 1)
     end
@@ -124,18 +127,18 @@ module Finrb
     #   # monthly proportional interest rate which is equivalent to a simple annual interest
     #   Finrb::Yields.eir(r=0.05,p=12,type='p')
     def self.eir(r:, n: 1, p: 12, type: 'e')
-      r = Flt::DecNum(r.to_s)
-      n = Flt::DecNum(n.to_s)
-      p = Flt::DecNum(p.to_s)
+      r = Validation.decimal(r, name: 'annual rate')
+      n = Validation.positive_decimal(n, name: 'source compounding periods', error: DomainError)
+      p = Validation.positive_decimal(p, name: 'target compounding periods', error: DomainError)
       type = type.to_s
 
       case type
       when 'e'
-        eir = (((r / n) + 1)**(n / p)) - 1
+        eir = (compounding_base(r, n)**(n / p)) - 1
       when 'p'
         eir = r / p
       else
-        raise(Error, "type must be 'e' or 'p'")
+        raise(ArgumentError, "conversion type must be 'e' (equivalent) or 'p' (proportional)")
       end
       eir
     end
@@ -147,8 +150,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2bey(hpr=0.02,t=3)
     def self.hpr2bey(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       ((((hpr + 1)**(6 / t)) - 1) * 2)
     end
@@ -160,8 +163,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2ear(hpr=0.015228,t=120)
     def self.hpr2ear(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((hpr + 1)**(365 / t)) - 1)
     end
@@ -173,8 +176,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2mmy(hpr=0.01523,t=120)
     def self.hpr2mmy(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal(hpr, name: 'holding period return')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (hpr * 360 / t)
     end
@@ -186,8 +189,8 @@ module Finrb
     # @example
     #   Finrb::Yields.mmy2hpr(mmy=0.04898,t=150)
     def self.mmy2hpr(mmy:, t:)
-      mmy = Flt::DecNum(mmy.to_s)
-      t = Flt::DecNum(t.to_s)
+      mmy = Validation.decimal(mmy, name: 'money market yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (mmy * t / 360)
     end
@@ -199,10 +202,10 @@ module Finrb
     # @example
     #   Finrb::Yields.r_continuous(r=0.03,m=4)
     def self.r_continuous(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'nominal rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      (m * ((r / m) + 1).log)
+      (m * compounding_base(r, m).log)
     end
 
     # Convert a given continuous compounded rate to a norminal rate
@@ -215,10 +218,18 @@ module Finrb
     # @example
     #   Finrb::Yields.r_norminal(rc=0.03,m=4)
     def self.r_norminal(rc:, m:)
-      rc = Flt::DecNum(rc.to_s)
-      m = Flt::DecNum(m.to_s)
+      rc = Validation.decimal(rc, name: 'continuously compounded rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
       (m * ((rc / m).exp - 1))
     end
+
+    def self.compounding_base(rate, periods)
+      base = (rate / periods) + 1
+      raise(DomainError, 'The rate per compounding period must be greater than -1.') unless base.positive?
+
+      base
+    end
+    private_class_method :compounding_base
   end
 end

data/sig/finrb.rbs

@@ -94,14 +94,40 @@ module Finrb
   end
 
   class Amortization
-    def self.payment: (number, number, Integer) -> decimal
+    class Entry
+      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number) -> void
+      def period: () -> Integer
+      def opening_balance: () -> decimal
+      def payment: () -> decimal
+      def interest: () -> decimal
+      def principal: () -> decimal
+      def additional_payment: () -> decimal
+      def balloon_payment: () -> decimal
+      def interest_only: () -> bool
+      def interest_only?: () -> bool
+      def closing_balance: () -> decimal
+      def ==: (untyped) -> bool
+      def eql?: (untyped) -> bool
+      def hash: () -> Integer
+      def to_h: () -> Hash[Symbol, Integer | decimal]
+    end
+
+    def self.payment: (number, number, Integer, ?balloon: number) -> decimal
 
-    def initialize: (number, *Rate) ?{ (Transaction) -> number } -> void
+    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool) ?{ (Transaction) -> number } -> void
     def ==: (untyped) -> bool
     def balance: () -> decimal
+    def balloon: () -> decimal
+    def amount_financed: () -> decimal
+    def net_proceeds: () -> decimal
+    def origination_fee: () -> decimal
+    def finance_origination_fee: () -> bool
+    def finance_origination_fee?: () -> bool
+    def interest_only_periods: () -> Integer
     def payment: () -> decimal?
     def principal: () -> decimal
     def rates: () -> Array[Rate]
+    def schedule: () -> Array[Entry]
     def additional_payments: () -> Array[decimal]
     def duration: () -> Integer
     def inspect: () -> String
@@ -111,18 +137,20 @@ module Finrb
 
   module Cashflow
     def self.irr: (Enumerable[number], ?number) -> decimal
+    def self.mirr: (Enumerable[number], finance_rate: number, reinvestment_rate: number) -> decimal
     def self.npv: (Enumerable[number], number) -> decimal
     def self.xirr: (Enumerable[Transaction], ?number) -> Rate
     def self.xnpv: (Enumerable[Transaction], number) -> decimal
 
     def irr: (?number) -> decimal
+    def mirr: (finance_rate: number, reinvestment_rate: number) -> decimal
     def npv: (number) -> decimal
     def xirr: (?number) -> Rate
     def xnpv: (number) -> decimal
   end
 
   module TVM
-    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?lower: number, ?upper: number) -> decimal
+    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?guess: number?, ?lower: number?, ?upper: number?) -> decimal
     def self.fv: (r: number, n: number, ?pv: number, ?pmt: number, ?type: Integer) -> decimal
     def self.fv_annuity: (r: number, n: number, pmt: number, ?type: Integer) -> decimal
     def self.fv_simple: (r: number, n: number, pv: number) -> decimal
@@ -141,7 +169,7 @@ module Finrb
   module Accounting
     type inventory_result = { cost_of_goods: decimal, ending_inventory: decimal }
 
-    def self.cogs: (uinv: number, pinv: number, units: number | numbers, price: number | numbers, sinv: number, ?method: String) -> inventory_result
+    def self.cogs: (uinv: number, pinv: number, units: number | numbers | nil, price: number | numbers | nil, sinv: number, ?method: String | Symbol) -> inventory_result
     def self.ddb: (cost: number, rv: number, t: Integer) -> { t: Array[Integer], ddb: Array[decimal] }
     def self.slde: (cost: number, rv: number, t: number) -> decimal
   end
@@ -163,15 +191,22 @@ module Finrb
   end
 
   module Returns
+    def self.annualize_return: (rate: number, periods_per_year: Integer) -> decimal
+    def self.annualize_volatility: (volatility: number, periods_per_year: Integer) -> decimal
+    def self.cagr: (beginning_value: number, ending_value: number, periods: Integer) -> decimal
     def self.coefficient_variation: (sd: number, avg: number) -> decimal
     def self.geometric_mean: (r: number | numbers) -> decimal
     def self.harmonic_mean: (p: number | numbers) -> decimal
     def self.hpr: (ev: number, bv: number, ?cfr: number) -> decimal
+    def self.downside_deviation: (returns: number | numbers, ?target: number) -> decimal
+    def self.max_drawdown: (values: number | numbers) -> decimal
     def self.sampling_error: (sm: number, mu: number) -> decimal
     def self.sf_ratio: (rp: number, rl: number, sd: number) -> decimal
     def self.sharpe_ratio: (rp: number, rf: number, sd: number) -> decimal
+    def self.sortino_ratio: (returns: number | numbers, ?target: number, ?periods_per_year: Integer?) -> decimal
     def self.twrr: (ev: number | numbers, bv: number | numbers, cfr: number | numbers) -> decimal
     def self.wpr: (r: number | numbers, w: number | numbers) -> decimal
+    def self.volatility: (returns: number | numbers, ?sample: bool) -> decimal
   end
 
   module Yields

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finrb
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Nadir Cohen
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -248,10 +262,12 @@ extra_rdoc_files:
 - README.md
 files:
 - CHANGELOG.md
+- CONTRIBUTING.md
 - COPYING
 - COPYING.LESSER
 - NOTICE.md
 - README.md
+- SECURITY.md
 - lib/finrb.rb
 - lib/finrb/accounting.rb
 - lib/finrb/amortization.rb