financial_calculator 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89354ba8e6670b27b4848b7ba3e1ab400b79b847177d9f31cac035b0993dc2c9
-  data.tar.gz: 972ceb6f53f670b63896732364fa4b1291d51d85316779a28a517fa9f13d8deb
+  metadata.gz: 5f0d684ffcf8cd34cdad09576834da2057e6879b45af1484123474b6e151baad
+  data.tar.gz: eccae432dc2cca2470cf1023871c0d9cb58620b080715c8ed00c818a62e4d2b4
 SHA512:
-  metadata.gz: 1ef6f4907275ece9ea20f046394a10c62484ac991b5b3a8bc69d9a7b7b8dee6fa2ee470a316b6f9348a5fa5b36b99e315fab4ec67c003b6e2639e35d5049a203
-  data.tar.gz: e02169325a2c0f08e3f7379b9944cdf5374b7f055338a41e7862d6321a942d69d4f9e9d24943fc833e7d5a22d2532fb035b387d6ca5a842fea855458caf42a57
+  metadata.gz: 5715ae679ff1cc465004bf136989bdee35ce1d60c3c1a21cf6daac07ec4ecbe71f1db8f04ff26d8b3e57a525394e7508601c96be5c5923e443b6504014c94325
+  data.tar.gz: 449cdc6640b282aea1e34a3de372717986232474310101bcf4097ecbbfac6021087aa26d1b4b429ab017239f40bd337c993f91675f3f7f9823920a1243c7bc70

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+All notable changes to this project will be documented in this file
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.0] - 2018-05-12
+### Added
+- New class for Present Value calculation (FinancialCalculator::PV)
+
+### Removed
+- Monkey patched cashflow methods on Array
+- Fork relationship with Ruby [finance](https://github.com/marksweston/finance) gem
+
+### Changed
+- Calculations for IRR
+- IRR, XIRR, NPV, and XNPV now belong to their own classes
+- Method for calculating IRR. The finance gem used Newton's method, this gem now uses the Secant method.
+- Significant changes now captured in README.md instead of HISTORY
+
+## [2.1.0]
+### Added
+- Code coverage and build status badges to README
+
+### Removed
+
+### Changed
+- Gem name from finance to financial_calculator
+- Replaced minitest with rspec

data/README.md

@@ -10,10 +10,7 @@ A library for financial modelling in Ruby.
 
 ## IMPORTANT CHANGES
 
-This is a fork of the [finance](https://github.com/marksweston/finance) library.
-The fork was made at version 2.0 of the original library. The first release of
-this library will not introduce any feature changes, it will only update the tests
-and documentation.
+This project started as a fork of the [finance](https://github.com/marksweston/finance) gem. The fork occured at version 2.0 of the finance library, and the first version of this gem is version 2.1. Version 2.1 is designed to be a drop in replacement for the finance gem, having only updated tests and documentation. However, starting with version 3.0, several significant changes have been made to the strucuture of the library as well as the underlying calculations.
 
 Since there are many additional calculations that can be included in this gem, I am
 working on developing a roadmap of which ones I will be adding and in what order. However,
@@ -109,25 +106,12 @@ You can also increase your payment to a specific amount:
 
     >> extra_payments_2 = 250000.amortize(rate){ -1500 }
 
-## ABOUT
-
-I started developing `finance` while analyzing mortgages as a personal
-project.  Spreadsheets have convenient formulas for doing this type of
-work, until you want to do something semi-complex (like ARMs or extra
-payments), at which point you need to create your own amortization
-table.  I thought I could create a better interface for this type of
-work in Ruby, and since I couldn't find an existing resource for these
-tools, I am hoping to save other folks some time by releasing what I
-have as a gem.
-
-More broadly, I believe there are many calculations that are necessary
-for the effective management of personal finances, but are difficult
-(or impossible) to do with spreadsheets or other existing open source
-tools.  My hope is that the `finance` library will grow to provide a set
-of open, tested tools to fill this gap.
-
-If you have used `finance` and find it useful, I would enjoy hearing
-about it!
+## SUPPORTED STANDARD CALCUALTIONS
+- PV
+- NPV
+- XNPV
+- IRR
+- XIRR
 
 ## FEATURES
 

data/financial_calculator.gemspec

@@ -24,11 +24,12 @@ SPEC = Gem::Specification.new do |s|
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec', '>= 3.4.0'
   s.add_development_dependency 'simplecov', '>= 0.16.0'
+  s.add_development_dependency 'yard'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = ['lib']
 
   s.has_rdoc = true
-  s.extra_rdoc_files = ['README.md', 'COPYING', 'COPYING.LESSER', 'HISTORY']
-end
+  s.extra_rdoc_files = ['README.md', 'COPYING', 'COPYING.LESSER', 'CHANGELOG.md']
+end

data/lib/financial_calculator.rb

@@ -1,6 +1,5 @@
-require 'financial_calculator/decimal'
-require 'financial_calculator/cashflows'
-
+require 'flt'
+require 'flt/d'
 # The *FinancialCalculator* module adheres to the following conventions for
 # financial calculations:
 #
@@ -9,7 +8,12 @@ require 'financial_calculator/cashflows'
 #  * *principal* represents the outstanding balance of a loan or annuity.
 #  * *rate* represents the interest rate _per period_.
 module FinancialCalculator
-  autoload :Amortization, 'financial_calculator/amortization'
-  autoload :Rate,         'financial_calculator/rates'
-  autoload :Transaction,  'financial_calculator/transaction'
+  require 'financial_calculator/amortization'
+  require 'financial_calculator/rates'
+  require 'financial_calculator/transaction'
+  require 'financial_calculator/irr'
+  require 'financial_calculator/pv'
+  require 'financial_calculator/npv'
+  require 'financial_calculator/xnpv'
+  require 'financial_calculator/xirr'
 end

data/lib/financial_calculator/amortization.rb

@@ -1,5 +1,3 @@
-require_relative 'cashflows'
-require_relative 'decimal'
 require_relative 'transaction'
 
 module FinancialCalculator

data/lib/financial_calculator/irr.rb

@@ -0,0 +1,100 @@
+module FinancialCalculator
+  class Irr
+    # @return [Numeric] The internal rate of return 
+    # @example
+    #   FinancialCalculator::Irr.new([-123400, 36200, 54800, 48100]).result.round(4) #=> Flt::DecNum('0.0596')
+    attr_reader :result
+
+    # The number of iterations to perform while attempting to minimize the root.
+    NUM_ITERATIONS = 1_000
+
+    # Creates a new Irr instance
+    # @param [Array<Numeric>] values An array of cash flows.
+    # @param [Numeric] r_1 An optional first guess to use for the secant method.
+    # @param [Numeric] r_2 An optional second guess to use for the secant method.
+    # @return [FinancialClaculator::Irr] An Irr instance 
+    # @see http://en.wikipedia.org/wiki/Internal_rate_of_return
+    # @api public
+    def initialize(values, r_1 = nil, r_2 = nil)
+      unless (values[0].positive? ^ values[1].positive?) & values[0].nonzero?
+        raise ArgumentError.new('The values do not converge') 
+      end
+      @eps = 1e-7
+      @values = values.map { |val| Flt::DecNum(val.to_s) }
+
+      r_1 ||= initial_r_1
+      r_2 ||= initial_r_2
+
+      @result = solve(@values, r_1, r_2)
+    end
+
+    def inspect
+      "IRR(#{@result})"
+    end
+
+    private
+
+    # Perform a single iteration
+    # @param [Array<Numeric>] values
+    # @param [DecNum] r_1
+    # @param [DecNum] r_2
+    # @return [DecNum] A rate of return that is closer to the actual internal rate of return
+    #   than the previous iteration
+    def iterate(values, r_1, r_2)
+      fn_1 = Npv.new(r_1, values).result
+      fn_2 = Npv.new(r_2, values).result
+
+      r_1 - (fn_1 * (r_1 - r_2)) / (fn_1 - fn_2)
+    end
+
+    # Solve the IRR
+    # @param [Array<Numeric>] values
+    # @param [DecNum] r_1
+    # @param [DecNum] r_2
+    # @return [DecNum] The internal rate of return
+    def solve(values, r_1, r_2)
+      NUM_ITERATIONS.times do
+        break if r_1.infinite? || converged?(r_1, r_2)
+        r_2, r_1 = [r_1, iterate(values, r_1, r_2)]
+      end
+
+      r_1.infinite? ? r_2 : r_1
+    end
+
+    # Default first guess for use in the secant method
+    # @see https://en.wikipedia.org/wiki/Internal_rate_of_return#Numerical_solution_for_single_outflow_and_multiple_inflows
+    def initial_r_1
+      @initial_r_1 ||= cap_a_over_abs_cap_c_0 ** (2 / Flt::DecNum(@values.length.to_s)) - 1
+    end
+
+    # Default second guess for use in the secant method
+    # @see https://en.wikipedia.org/wiki/Internal_rate_of_return#Numerical_solution_for_single_outflow_and_multiple_inflows
+    def initial_r_2
+      (1 + initial_r_1) ** p - 1
+    end
+
+    def cap_a_over_abs_cap_c_0
+      cap_a / abs_c_0
+    end
+    
+    def cap_a
+      @cap_a ||= @values[1..-1].sum
+    end
+
+    def abs_c_0
+      @values[0].abs
+    end
+
+    def p
+      Flt::DecNum(Math.log(cap_a_over_abs_cap_c_0).to_s) / Flt::DecNum(Math.log(cap_a / npv_1_in(initial_r_1)).to_s)
+    end
+
+    def npv_1_in(rate)
+      @flows ||= Npv.new(rate, [0] + @values[1..-1].flatten).result
+    end
+
+    def converged?(r_1, r_2)
+      (r_1 - r_2).abs < @eps
+    end
+  end
+end

data/lib/financial_calculator/npv.rb

@@ -0,0 +1,44 @@
+module FinancialCalculator
+  # Calculates the present value of a series of equally spaced cashflows of unequal amounts
+  class Npv
+
+    # @return [Numeric] The rates used for calculating the present value
+    # @api public
+    attr_reader :rate
+
+    # @return [Arrray<Numeric>] An array of cashflow amounts
+    # @api public
+    attr_reader :cashflows
+
+    # @return [DecNum] Result of the XNPV calculation
+    # @api public
+    attr_reader :result
+
+    # Create a new net present value calculation
+    # @see https://en.wikipedia.org/wiki/Net_present_value
+    # @param [Numeric] rate The discount (interest) rate
+    # @param [Array<Numeric>] cashflows An array of cashflows 
+    # @return [FinancialCalculator::Npv] An instance of a Net Present Value calculation
+    def initialize(rate, cashflows)
+      raise ArgumentError.new("Rate must be a Numeric. Got #{rate.class} instead") unless rate.is_a? Numeric
+
+      @rate     = rate
+      @cashflows = cashflows
+      @result   = solve(rate, cashflows)
+    end
+
+    def inspect
+      "NPV(#{result})"
+    end
+
+    private
+
+    def solve(rate, cashflows)
+      cashflows.each_with_index.reduce(0) do |total, (payment, index)|
+        total += payment / (1 + rate) ** (index + 1)
+      end 
+    end
+  end
+
+  NetPresentValue = Npv
+end

data/lib/financial_calculator/pv.rb

@@ -0,0 +1,85 @@
+module FinancialCalculator
+  # Calculate the future value of a series of equal of payments
+  class Pv
+
+    # @return [Numeric] The discount rate used in the calculation
+    attr_reader :rate
+
+    # @return [Numeric] The number of periodic payments
+    attr_reader :num_periods
+
+    # @return [Numeric] The amount of the periodic payment
+    attr_reader :payment
+
+    # @return [Numeric] The value remaining after the final payment has been made
+    attr_reader :future_value
+
+    # @return [Numeric] The result of the present value calculation
+    attr_reader :result
+
+    # Create a new present value calculation
+    #
+    # @see https://en.wikipedia.org/wiki/Present_value
+    # @example
+    #   FinancialCalculator::Pv.new(0.02, 10, -100) #=> PresentValue(898.2585006242236)
+    # @param [Numeric] rate The discount (interest) rate to use
+    # @param [Numeric] num_periods The number of periodic payments
+    # @param [Numeric] payment The amount of the periodic payment
+    # @param [Numeric] future_value The value remaining after the final payment has been made
+    # @param [Boolean] pay_at_beginning Whether the payments are made at the beginning or end of each period
+    # @return [FinancialCalculator::Pv] A Pv object
+    # @raise [ArgumentError] Raises an ArgumentError if num_periods is less than 0 or a required numeric
+    #   field is given a non-numeric value
+    def initialize(rate, num_periods, payment, future_value = 0, pay_at_beginning = false)
+      validate_numerics(rate: rate, num_periods: num_periods, payment: payment, future_value: future_value)
+
+      if num_periods < 0
+        raise ArgumentError.new('Cannot calculate present value with negative periods. Use future value instead.')
+      end
+
+      @rate             = Flt::DecNum(rate.to_s)
+      @num_periods      = Flt::DecNum(num_periods.to_s)
+      @payment          = Flt::DecNum(payment.to_s)
+      @future_value     = Flt::DecNum(future_value.to_s)
+      @pay_at_beginning = pay_at_beginning
+      @result           = solve(@rate, @num_periods, @payment, @future_value, pay_at_beginning)
+    end
+
+    def inspect
+      "PV(#{result})"
+    end
+
+    # @return [Boolean] Whether the payments are made at the beginning of each period
+    def pays_at_beginning?
+      @pay_at_beginning
+    end
+
+    private
+
+    def solve(rate, num_periods, payment, future_value, pay_at_beginning)
+      start_period  = pay_at_beginning ? 0 : 1
+      end_period    = pay_at_beginning ? num_periods - 1 : num_periods
+
+      present_value = (start_period..end_period.abs).reduce(0) do |total, t|
+        total += discount(payment, rate, t)
+      end
+
+      -(present_value + discount(future_value, rate, num_periods))
+    end
+
+    def discount(amount, rate, periods)
+      return 0 if amount.zero?
+      amount / (1 + rate) ** periods 
+    end
+
+    def validate_numerics(numerics)
+      numerics.each do |key, value|
+        unless value.is_a? Numeric
+          raise ArgumentError.new("#{key} must be a type of Numeric. Got #{value.class} instead.")
+        end
+      end
+    end
+  end
+
+  PresentValue = Pv
+end

data/lib/financial_calculator/rates.rb

@@ -1,5 +1,3 @@
-require_relative 'decimal'
-
 module FinancialCalculator
   # the Rate class provides an interface for working with interest rates.
   # {render:Rate#new}

data/lib/financial_calculator/transaction.rb

@@ -1,5 +1,3 @@
-require_relative 'decimal'
-
 module FinancialCalculator
   # the Transaction class provides a general interface for working with individual cash flows.
   # @api public

data/lib/financial_calculator/version.rb

@@ -1,3 +1,3 @@
 module FinancialCalculator
-  VERSION = '2.1.0'
+  VERSION = '3.0.0'
 end

data/lib/financial_calculator/xirr.rb

@@ -0,0 +1,124 @@
+module FinancialCalculator
+  class Xirr
+    # @return [DecNum] The internal rate of return 
+    # @example
+    #   transactions = []
+    #   transactions << Transaction.new(-1000, :date => Date.new(1985,01,01))
+    #   transactions << Transaction.new(  600, :date => Date.new(1990,01,01))
+    #   transactions << Transaction.new(  600, :date => Date.new(1995,01,01))
+    #   Xirr.with_transactions(transactions).result #=> 0.0249 
+    attr_reader :result
+
+    # The number of iterations to perform while attempting to minimize the root.
+    NUM_ITERATIONS = 1_000
+
+    # Factory method for creating an Xirr instance from an array of transactions
+    # @param [Array<Transaction>] transactions An array of transactions
+    # @param [Numeric] /_1 An optional first guess to use when calculating the secant method
+    # @param [Numeric] r_2 An optional second guess to use when calculating the secant method
+    # @return [FinancialCalculator::Xirr] An Xirr instance 
+    # @api public
+    def self.with_transactions(transactions, r_1 = nil, r_2 = nil)
+      unless transactions.all? { |t| t.is_a? Transaction }
+        raise ArgumentError.new("Argument \"transactions\" must be an array of Transaction")
+      end
+
+      cashflows  = transactions.map(&:amount)
+      dates      = transactions.map(&:date)
+
+      self.new(cashflows, dates, r_1, r_2)
+    end
+
+    # Creates a new Xirr instance
+    # @param [Array<Numeric>] cashflows An array of cash flows.
+    # @param [Numeric] r_1 An optional first guess to use for the secant method.
+    # @param [Numeric] r_2 An optional second guess to use for the secant method.
+    # @return [FinancialClaculator::Xirr] An Xirr instance 
+    # @see http://en.wikipedia.org/wiki/Internal_rate_of_return
+    # @api public
+    def initialize(cashflows, dates, r_1 = nil, r_2 = nil)
+      unless (cashflows[0].positive? ^ cashflows[1].positive?) & cashflows[0].nonzero?
+        raise ArgumentError.new('The cashflows do not converge') 
+      end
+      @eps = 1e-7
+      @cashflows = cashflows.map { |val| Flt::DecNum(val.to_s) }
+      @dates  = dates
+
+      r_1 = r_1 ? Flt::DecNum(r_1.to_s) : initial_r_1
+      r_2 = r_2 ? Flt::DecNum(r_2.to_s) : initial_r_2
+
+      @result = solve(@cashflows, @dates, r_1, r_2)
+    end
+
+    # @return [String]
+    # @api public
+    def inspect
+      "XIRR(#{@result})"
+    end
+
+    private
+
+    # Perform a single iteration
+    # @param [Array<Numeric>] cashflows
+    # @param [Numeric] r_1
+    # @param [Numeric] r_2
+    # @return [Numeric] A rate of return that is closer to the actual internal rate of return
+    #   than the previous iteration
+    def iterate(cashflows, dates, r_1, r_2)
+      fn_1 = Xnpv.new(r_1, cashflows, dates).result
+      fn_2 = Xnpv.new(r_2, cashflows, dates).result
+
+      r_1 - (fn_1 * (r_1 - r_2)) / (fn_1 - fn_2)
+    end
+
+    # Solve the Xirr
+    # @param [Array<Numeric>] cashflows
+    # @param [Numeric] r_1
+    # @param [Numeric] r_2
+    # @return [DecNum] The internal rate of return
+    def solve(cashflows, dates, r_1, r_2)
+      NUM_ITERATIONS.times do
+        break if r_1.infinite? || converged?(r_1, r_2)
+        r_2, r_1 = [r_1, iterate(cashflows, dates, r_1, r_2)]
+      end
+
+      r_1.infinite? ? r_2 : r_1
+    end
+
+    # Default first guess for use in the secant method
+    # @see https://en.wikipedia.org/wiki/Internal_rate_of_return#Numerical_solution_for_single_outflow_and_multiple_inflows
+    def initial_r_1
+      @initial_r_1 ||= cap_a_over_abs_cap_c_0 ** (2 / Flt::DecNum(@cashflows.length.to_s)) - 1
+    end
+
+    # Default second guess for use in the secant method
+    # @see https://en.wikipedia.org/wiki/Internal_rate_of_return#Numerical_solution_for_single_outflow_and_multiple_inflows
+    def initial_r_2
+      (1 + initial_r_1) ** p - 1
+    end
+
+    def cap_a_over_abs_cap_c_0
+      cap_a / abs_c_0
+    end
+    
+    def cap_a
+      @cap_a ||= @cashflows[1..-1].sum
+    end
+
+    def abs_c_0
+      @cashflows[0].abs
+    end
+
+    def p
+      Flt::DecNum(Math.log(cap_a_over_abs_cap_c_0).to_s) / Flt::DecNum(Math.log(cap_a / npv_1_in(initial_r_1)).to_s)
+    end
+
+    def npv_1_in(rate)
+      @flows ||= Xnpv.new(rate, [0] + @cashflows[1..-1].flatten, @dates).result
+    end
+
+    def converged?(r_1, r_2)
+      (r_1 - r_2).abs < @eps
+    end
+  end
+end