finance 0.2.0 → 1.0.0

data/COPYING

@@ -1,3 +1,5 @@
+ # @title COPYING
+ # @markup none
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 

data/COPYING.LESSER

@@ -1,3 +1,5 @@
+# @title COPYING.LESSER
+# @markup none
                    GNU LESSER GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 

data/HISTORY

@@ -0,0 +1,26 @@
+= Version 1.0.0 
+20 Jul 2011
+
+* Moved to Ruby 1.9.
+* All classes are now contained within the +Finance+ namespace.  
+* LOTS of additional documentation and examples.
+* Introduced _shoulda_ for unit tests, to make things a little more readable.
+* Bugfix: The +amortize+ Numeric method now accepts a variable number of rates.
+* Some code refactoring and clean-up for a small performance increase.
+
+= Version 0.2.0
+28 Jun 2011
+
+* Added support for adjustable rate mortgages.
+* Added support for additional payments.
+
+= Version 0.1.1
+21 Jun 2011
+
+* Code examples in README now display correctly in the online documentation.
+
+= Version 0.1.0
+21 Jun 2011
+
+* Support for fixed-rate mortgage amortization.
+* NPV, IRR array methods for cash flow analysis.

data/README

@@ -1,16 +1,25 @@
-_finance_ - a library for financial calculations in Ruby.
+= FINANCE
 
-= INSTALL
+a library for financial modelling in Ruby.
+
+== INSTALL
 
   $ sudo gem install finance
 
-= OVERVIEW
+== OVERVIEW
 
-== GETTING STARTED
+=== GETTING STARTED
 
   >> require 'finance'
 
-== AMORTIZATION
+*Note:* As of version 1.0.0, the entire library is contained under the
+Finance namespace.  Existing code will not work unless you add:
+
+  >> include Finance
+
+for all of the examples below, we'll assume that you have done this.
+
+=== AMORTIZATION
 
 You are interested in borrowing $250,000 under a 30 year, fixed-rate
 loan with a 4.25% APR.
@@ -55,7 +64,7 @@ Since we are looking at an ARM, there is no longer a single "payment" value.
 But we can look at the different payments over time.
 
   >> arm.payments.uniq
-  => [DecNum('-1229.85'), DecNum('-1360.41'), DecNum('-1475.65'), DecNum('-1571.07'), DecNum('-1641.34'), ... snipped ... ]
+  => [DecNum('-1229.85'), DecNum('-1360.41'), DecNum('-1475.65'), DecNum('-1571.07'), ... snipped ... ]
 
 The other methods previously discussed can be accessed in the same way:
 
@@ -83,14 +92,11 @@ example.  Notice the difference in the results:
   >> extra_payments.interest.sum
   => DecNum('150566.24')
 
-*Note*: you are _not_ allowed to modify a payment to pay _less_ than the
-normally calculated payment.
-
 You can also increase your payment to a specific amount:
 
   >> extra_payments_2 = 250000.amortize(rate){ -1500 }
 
-= ABOUT
+== ABOUT
 
 I started developing _finance_ while analyzing mortgages as a personal
 project.  Spreadsheets have convenient formulas for doing this type of
@@ -110,29 +116,25 @@ of open, tested tools to fill this gap.
 If you have used _finance_ and find it useful, I would enjoy hearing
 about it!
 
-= FEATURES
+== FEATURES
 
 Currently implemented features include:
 
 * Uses the {http://flt.rubyforge.org/ flt} library to ensure precision decimal arithmetic in all calculations.
 * Fixed-rate mortgage amortization (30/360).
 * Interest rates
-* Various cash flow computations, such as NPV, IRR, and sum.
+* Various cash flow computations, such as NPV and IRR.
 * Adjustable rate mortgage amortization.
 * Payment modifications (i.e., how does paying an additional $75 per month affect the amortization?)
 
-= RESOURCES
-
-This gem and related documentation is available through
-{https://rubygems.org/gems/finance RubyGems}.
-
-Source code and bug tracking is available via
-{http://github.com/wkranec/finance github}.
+== RESOURCES
 
-Additional documentation is available on the
-{https://github.com/wkranec/finance/wiki wiki}.
+[RubyGems Page] {https://rubygems.org/gems/finance}
+[Source Code] {http://github.com/wkranec/finance}
+[Bug Tracker] {https://github.com/wkranec/finance/issues}
+[Google Group] {http://groups.google.com/group/finance-gem/topics?pli=1}
 
-= COPYRIGHT
+== COPYRIGHT
 
 This library is released under the terms of the LGPL license.
 

data/lib/finance.rb

@@ -1,7 +1,5 @@
-require 'amortization'
-require 'cashflows'
-require 'rates'
-require 'timespan'
+require 'finance/cashflows'
+require 'finance/interval'
 
 # The *Finance* module adheres to the following conventions for
 # financial calculations:
@@ -11,53 +9,7 @@ require 'timespan'
 #  * *principal* represents the outstanding balance of a loan or annuity.
 #  * *rate* represents the interest rate _per period_.
 module Finance
-
-  def Finance.payments(principal, rates)
-    p_total = rates.inject(0) { |sum, n| sum + n[0] }
-    p_current = 0
-    payments = []
-
-    rates.each do |periods, rate|
-      payment = Finance.pmt(principal, rate, p_total-p_current)
-
-      begin
-        payment = payment.round(2)
-      rescue ArgumentError
-        payment = (payment * 100.0).round / 100.0
-      end
-
-      if block_given?
-        payment = yield(payment)
-      end
-
-      periods.times do
-        interest = principal * rate
-
-        if payment > principal + interest
-          payment = principal + interest
-        end
-
-        principal = principal + interest - payment
-
-        begin
-          principal = principal.round(2)
-        rescue ArgumentError
-          principal = (principal * 100.0).round / 100.0
-        end
-
-        payments << payment
-        break if principal == 0
-        
-        p_current = p_current + 1
-      end
-    end
-
-    payments
-  end
-
-  # Return the number of periods needed to pay off a loan with the
-  # given payment.
-  def Finance.nper(payment, rate, principal)
-    -(Math.log(1-((principal/payment)*rate))) / Math.log(1+rate)
-  end
+  autoload :Amortization, 'finance/amortization'
+  autoload :Rate,         'finance/rates'
+  autoload :Transaction,  'finance/transaction'
 end

data/lib/finance/amortization.rb

@@ -0,0 +1,196 @@
+require_relative 'cashflows'
+require_relative 'decimal'
+require_relative 'transaction'
+
+module Finance
+  # the Amortization class provides an interface for working with loan amortizations.
+  # @note There are _two_ ways to create an amortization.  The first
+  #   example uses the amortize method for the Numeric class.  The second
+  #   calls Amortization.new directly.
+  # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR
+  #   rate = Rate.new(0.0425, :apr, :duration => 30.years)
+  #   amortization = 250000.amortize(rate)
+  # @example Borrow $250,000 under a 30 year, adjustable rate loan, with an APR starting at 4.25%, and increasing by 1% every five years
+  #   values = %w{ 0.0425 0.0525 0.0625 0.0725 0.0825 0.0925 }
+  #   rates = values.collect { |value| Rate.new( value, :apr, :duration = 5.years ) }
+  #   arm = Amortization.new(250000, *rates)
+  # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR, but pay $150 extra each month
+  #   rate = Rate.new(0.0425, :apr, :duration => 30.years)
+  #   extra_payments = 250000.amortize(rate){ |period| period.payment - 150 }
+  # @api public
+  class Amortization
+    # @return [DecNum] the balance of the loan at the end of the amortization period (usually zero)
+    # @api public
+    attr_reader :balance
+    # @return [DecNum] the required monthly payment.  For loans with more than one rate, returns nil
+    # @api public
+    attr_reader :payment
+    # @return [DecNum] the principal amount of the loan
+    # @api public
+    attr_reader :principal
+    # @return [Array] the interest rates used for calculating the amortization
+    # @api public
+    attr_reader :rates
+
+    # compare two Amortization instances
+    # @return [Numeric] -1, 0, or +1
+    # @param [Amortization]
+    # @api public
+    def ==(amortization)
+      self.principal == amortization.principal and self.rates == amortization.rates and self.payments == amortization.payments
+    end
+
+    # @return [Array] the amount of any additional payments in each period
+    # @example
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt.additional_payments #=> [DecNum('-100.00'), DecNum('-100.00'), ... ]
+    # @api public
+    def additional_payments
+      @transactions.find_all(&:payment?).collect{ |p| p.difference }
+    end
+
+    # amortize the balance of loan with the given interest rate
+    # @return none
+    # @param [Rate] rate the interest rate to use in the amortization
+    # @api private
+    def amortize(rate)
+      # For the purposes of calculating a payment, the relevant time
+      # period is the remaining number of periods in the loan, not
+      # necessarily the duration of the rate itself.
+      periods = @periods - @period
+      amount = Amortization.payment @balance, rate.monthly, periods
+
+      pmt = Payment.new(amount, :period => @period)
+      if @block then pmt.modify(&@block) end
+        
+      rate.duration.times do
+        # Do this first in case the balance is zero already.
+        if @balance.zero? then break end
+
+        # Compute and record interest on the outstanding balance.
+        int = (@balance * rate.monthly).round(2)
+        interest = Interest.new(int, :period => @period)
+        @balance += interest.amount
+        @transactions << interest.dup
+
+        # Record payment.  Don't pay more than the outstanding balance.
+        if pmt.amount.abs > @balance then pmt.amount = -@balance end
+        @transactions << pmt.dup
+        @balance += pmt.amount
+        
+        @period += 1
+      end
+    end
+
+    # compute the amortization of the principal
+    # @return none
+    # @api private
+    def compute
+      @balance = @principal
+      @transactions = []
+
+      @rates.each do |rate|
+        amortize(rate)
+      end
+
+      # Add any remaining balance due to rounding error to the last payment.
+      unless @balance.zero?
+        @transactions.find_all(&:payment?)[-1].amount -= @balance
+        @balance = 0
+      end
+
+      if @rates.length == 1
+        @payment = self.payments[0]
+      else
+        @payment = nil
+      end
+
+      @transactions.freeze
+    end
+
+    # @return [Integer] the time required to pay off the loan, in months
+    # @example In most cases, the duration is equal to the total duration of all rates
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate)
+    #   amt.duration #=> 360
+    # @example Extra payments may reduce the duration
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt.duration #=> 319
+    # @api public
+    def duration
+      self.payments.length
+    end
+
+    # create a new Amortization instance
+    # @return [Amortization]
+    # @param [DecNum] principal the initial amount of the loan or investment
+    # @param [Rate] rates the applicable interest rates
+    # @param [Proc] block
+    # @api public
+    def initialize(principal, *rates, &block)
+      @principal = principal.to_d
+      @rates     = rates
+      @block     = block
+      
+      # compute the total duration from all of the rates.
+      @periods = (rates.collect { |r| r.duration }).sum
+      @period  = 0
+
+      compute
+    end
+
+    # @api public
+    def inspect
+      "Amortization.new(#{@principal})"
+    end
+
+    # @return [Array] the amount of interest charged in each period
+    # @example find the total cost of interest for a loan
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate)
+    #   amt.interest.sum #=> DecNum('200163.94')
+    # @example find the total interest charges in the first six months
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate)
+    #   amt.interest[0,6].sum #=> DecNum('5603.74')
+    # @api public
+    def interest
+      @transactions.find_all(&:interest?).collect{ |p| p.amount }
+    end
+
+    # @return [DecNum] the periodic payment due on a loan
+    # @param [DecNum] principal the initial amount of the loan or investment
+    # @param [Rate] rate the applicable interest rate (per period)
+    # @param [Integer] periods the number of periods needed for repayment
+    # @note in most cases, you will probably want to use rate.monthly when calling this function outside of an Amortization instance.
+    # @example
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   rate.duration #=> 360
+    #   Amortization.payment(200000, rate.monthly, rate.duration) #=> DecNum('-926.23')
+    # @see http://en.wikipedia.org/wiki/Amortization_calculator
+    # @api public
+    def Amortization.payment(principal, rate, periods)
+      -(principal * (rate + (rate / ((1 + rate) ** periods - 1)))).round(2)
+    end
+
+    # @return [Array] the amount of the payment in each period
+    # @example find the total payments for a loan
+    #   rate = Rate.new(0.0375, :apr, :duration => 30.years)
+    #   amt = 300000.amortize(rate)
+    #   amt.payments.sum #=> DecNum('-500163.94')
+    # @api public
+    def payments
+      @transactions.find_all(&:payment?).collect{ |p| p.amount }
+    end
+  end
+end
+
+class Numeric
+  # @see Amortization#new
+  # @api public
+  def amortize(*rates, &block)
+    amortization = Amortization.new(self, *rates, &block)
+  end
+end

data/lib/finance/cashflows.rb

@@ -0,0 +1,55 @@
+require_relative 'decimal'
+
+module Finance
+  # Provides methods for working with cash flows (collections of transactions)
+  # @api public
+  module Cashflow
+    # calculate the internal rate of return for a sequence of cash flows
+    # @return [DecNum] the internal rate of return
+    # @example
+    #   [-4000,1200,1410,1875,1050].irr #=> 0.143
+    # @see http://en.wikipedia.org/wiki/Internal_rate_of_return
+    # @api public
+    def irr(iterations=100)
+      self.collect! { |entry| entry.to_d }
+
+      rate, investment = 1.to_d, self[0]
+      iterations.times do
+        rate *= (1 - self.npv(rate) / investment)
+      end
+      
+      rate
+    end
+
+    # calculate the net present value of a sequence of cash flows
+    # @return [DecNum] the net present value
+    # @param [Numeric] rate the discount rate to be applied
+    # @example
+    #   [-100.0, 60, 60, 60].npv(0.1) #=> 49.211
+    # @see http://en.wikipedia.org/wiki/Net_present_value
+    # @api public
+    def npv(rate)
+      self.collect! { |entry| entry.to_d }
+
+      rate, total = rate.to_d, 0.to_d
+      self.each_with_index do |cashflow, index|
+        total += cashflow / (1 + rate) ** index
+      end
+
+      total
+    end
+
+    # @return [Numeric] the total value of a sequence of cash flows
+    # @api public
+    def sum
+      self.inject(:+)
+    end
+
+    def xirr
+    end
+  end
+end
+
+class Array
+  include Finance::Cashflow
+end