finance 0.2.0 → 1.0.0

data/lib/finance/decimal.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'flt'
+
+class Numeric
+  def to_d
+    if self.instance_of? Flt::DecNum
+      self
+    else
+      Flt::DecNum self.to_s
+    end
+  end
+end

data/lib/finance/interval.rb

@@ -0,0 +1,19 @@
+class Integer
+  # convert an integer value representing months into months
+  # @return [Integer] the number of months
+  # @example
+  #   360.months #=> 360
+  # @api public
+  def months
+    self
+  end
+
+  # convert an integer value representing years into months
+  # @return [Integer] the number of months
+  # @example
+  #   30.years #=> 360
+  # @api public
+  def years
+    self * 12
+  end
+end

data/lib/finance/rates.rb

@@ -0,0 +1,167 @@
+require_relative 'decimal'
+
+module Finance
+  # the Rate class provides an interface for working with interest rates.
+  # {render:Rate#new}
+  # @api public
+  class Rate
+    include Comparable
+
+    # Accepted rate types
+    TYPES = { :apr       => "effective",
+              :apy       => "effective",
+              :effective => "effective",
+              :nominal   => "nominal" 
+            }
+
+    # @return [Integer] the duration for which the rate is valid, in months
+    # @api public
+    attr_accessor :duration
+    # @return [DecNum] the effective interest rate
+    # @api public
+    attr_reader :effective
+    # @return [DecNum] the nominal interest rate
+    # @api public
+    attr_reader :nominal
+
+    # compare two Rates, using the effective rate
+    # @return [Numeric] one of -1, 0, +1
+    # @param [Rate] rate the comparison Rate
+    # @example Which is better, a nominal rate of 15% compounded monthly, or 15.5% compounded semiannually?
+    #   r1 = Rate.new(0.15, :nominal) #=> Rate.new(0.160755, :apr)
+    #   r2 = Rate.new(0.155, :nominal, :compounds => :semiannually) #=> Rate.new(0.161006, :apr)
+    #   r1 <=> r2 #=> -1
+    # @api public
+    def <=>(rate)
+      @effective <=> rate.effective
+    end
+
+    # (see #effective)
+    # @api public
+    def apr
+      self.effective
+    end
+
+    # (see #effective)
+    # @api public
+    def apy
+      self.effective
+    end
+
+    # a convenience method which sets the value of @periods
+    # @return none
+    # @param [Symbol, Numeric] input the compounding frequency
+    # @raise [ArgumentError] if input is not an accepted keyword or Numeric
+    # @api private
+    def compounds=(input)
+      @periods = case input
+                 when :annually     then Flt::DecNum 1
+                 when :continuously then Flt::DecNum.infinity
+                 when :daily        then Flt::DecNum 365
+                 when :monthly      then Flt::DecNum 12
+                 when :quarterly    then Flt::DecNum 4
+                 when :semiannually then Flt::DecNum 2
+                 when Numeric       then Flt::DecNum input.to_s
+                 else raise ArgumentError
+                 end
+    end
+
+    # set the effective interest rate
+    # @return none
+    # @param [DecNum] rate the effective interest rate
+    # @api private
+    def effective=(rate)
+      @effective = rate
+      @nominal = Rate.to_nominal(rate, @periods)
+    end
+
+    # create a new Rate instance
+    # @return [Rate]
+    # @param [Numeric] rate the decimal value of the interest rate
+    # @param [Symbol] type a valid {TYPES rate type}
+    # @param [optional, Hash] opts set optional attributes
+    # @option opts [String] :duration a time interval for which the rate is valid
+    # @option opts [String] :compounds (:monthly) the number of compounding periods per year
+    # @example create a 3.5% APR rate
+    #   Rate.new(0.035, :apr) #=> Rate(0.035, :apr)
+    # @see http://en.wikipedia.org/wiki/Effective_interest_rate
+    # @see http://en.wikipedia.org/wiki/Nominal_interest_rate
+    # @api public
+    def initialize(rate, type, opts={})
+      # Default monthly compounding.
+      opts = { :compounds => :monthly }.merge opts
+
+      # Set optional attributes..
+      opts.each do |key, value|
+        send("#{key}=", value)
+      end
+
+      # Set the rate in the proper way, based on the value of type.
+      begin
+        send("#{TYPES.fetch(type)}=", rate.to_d)
+      rescue KeyError
+        raise ArgumentError, "type must be one of #{TYPES.keys.join(', ')}", caller
+      end
+    end
+
+    def inspect
+      "Rate.new(#{self.apr.round(6)}, :apr)"
+    end
+
+    # @return [DecNum] the monthly effective interest rate
+    # @example
+    #   rate = Rate.new(0.15, :nominal)
+    #   rate.apr.round(6) #=> DecNum('0.160755')
+    #   rate.monthly.round(6) #=> DecNum('0.013396')
+    # @api public
+    def monthly
+      (self.effective / 12).round(15)
+    end
+
+    # set the nominal interest rate
+    # @return none
+    # @param [DecNum] rate the nominal interest rate
+    # @api private
+    def nominal=(rate)
+      @nominal = rate
+      @effective = Rate.to_effective(rate, @periods)
+    end
+
+    # convert a nominal interest rate to an effective interest rate
+    # @return [DecNum] the effective interest rate
+    # @param [Numeric] rate the nominal interest rate
+    # @param [Numeric] periods the number of compounding periods per year
+    # @example
+    #   Rate.to_effective(0.05, 4) #=> DecNum('0.05095')
+    # @api public
+    def Rate.to_effective(rate, periods)
+      rate, periods = rate.to_d, periods.to_d
+
+      if periods.infinite?
+        rate.exp - 1
+      else
+        (1 + rate / periods) ** periods - 1
+      end
+    end
+
+    # convert an effective interest rate to a nominal interest rate
+    # @return [DecNum] the nominal interest rate
+    # @param [Numeric] rate the effective interest rate
+    # @param [Numeric] periods the number of compounding periods per year
+    # @example
+    #   Rate.to_nominal(0.06, 365) #=> DecNum('0.05827')
+    # @see http://www.miniwebtool.com/nominal-interest-rate-calculator/
+    # @api public
+    def Rate.to_nominal(rate, periods)
+      rate, periods = rate.to_d, periods.to_d
+
+      if periods.infinite?
+        (rate + 1).log
+      else
+        periods * ((1 + rate) ** (1 / periods) - 1)
+      end
+    end
+
+    private :compounds=, :effective=, :nominal=
+  end
+end

data/lib/finance/transaction.rb

@@ -0,0 +1,119 @@
+require_relative 'decimal'
+
+module Finance
+  # the Transaction class provides a general interface for working with individual cash flows.
+  # @api public
+  class Transaction
+    # @return [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_accessor :period
+
+    # Set the cash value of the transaction
+    # @return None
+    # @param [Numeric] value the cash value
+    # @example
+    #   t = Transaction.new(500)
+    #   t.amount = 750
+    #   t.amount #=> 750
+    # @api public
+    def amount=(value)
+      @amount = value.to_d
+    end
+
+    # @return [DecNum] the difference between the original transaction
+    #   amount and the current amount
+    # @example
+    #   t = Transaction.new(500)
+    #   t.amount = 750
+    #   t.difference #=> DecNum('250')
+    # @api public
+    def difference
+      @amount - @original
+    end
+
+    # create a new Transaction
+    # @return [Transaction]
+    # @param [Numeric] amount the cash value of the transaction
+    # @param [optional, Hash] opts sets optional attributes
+    # @option opts [String] :period the period number of the transaction
+    # @example a simple transaction
+    #   t = Transaction.new(400)
+    # @example a transaction with a period number
+    #   t = Transaction.new(400, :period => 3)
+    # @api public
+    def initialize(amount, opts={})
+      @amount = amount
+      @original = amount
+      
+      # Set optional attributes..
+      opts.each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    # @return [Boolean] whether or not the Transaction is an Interest transaction
+    # @example
+    #   pmt = Payment.new(500)
+    #   int = Interest.new(500)
+    #   pmt.interest? #=> False
+    #   int.interest? #=> True
+    # @api public
+    def interest?
+      self.instance_of? Interest
+    end
+
+    # @api public
+    def inspect
+      "Transaction(#{@amount})"
+    end
+
+    # Modify a Transaction's amount by passing a block
+    # @return none
+    # @note self is passed as the argument to the block.  This makes any public attribute available.
+    # @example add $100 to a monthly payment
+    #   pmt = Payment.new(-500)
+    #   pmt.modify { |t| t.amount-100 }
+    #   pmt.amount #=> -600
+    # @api public
+    def modify
+      @amount = yield(self)
+    end
+
+    # (see #amount)
+    # @deprecated Provided for backwards compatibility
+    def payment
+      @amount
+    end
+
+    # @return [Boolean] whether or not the Transaction is a Payment transaction
+    # @example
+    #   pmt = Payment.new(500)
+    #   int = Interest.new(500)
+    #   pmt.payment? #=> True
+    #   int.payment? #=> False
+    # @api public
+    def payment?
+      self.instance_of? Payment
+    end
+  end
+
+  # Represent an interest charge as a Transaction
+  # @see Transaction
+  class Interest < Transaction
+    def inspect
+      "Interest(#{@amount})"
+    end
+  end
+  
+  # Represent a loan payment as a Transaction
+  # @see Transaction
+  class Payment < Transaction
+    def inspect
+      "Payment(#{@amount})"
+    end
+  end
+end

data/test/test_amortization.rb

@@ -1,156 +1,156 @@
-require 'rubygems'
-require 'finance'
+require_relative '../lib/finance/amortization.rb'
+require_relative '../lib/finance/interval.rb'
+require_relative '../lib/finance/rates.rb'
+include Finance
+
 require 'flt/d'
-require 'test/unit'
+require 'minitest/unit'
+require 'shoulda'
 
-class TestBasicAmortization < Test::Unit::TestCase
-  def interest_in_period(principal, rate, payment, period)
+# @see http://tinyurl.com/6zroqvd for detailed calculations for the
+#   examples in these unit tests.
+class TestAmortization < Test::Unit::TestCase
+  def ipmt(principal, rate, payment, period)
     -(-rate*principal*(1+rate)**(period-1) - payment*((1+rate)**(period-1)-1)).round(2)
   end
 
-  def setup
-    @rate = Rate.new(0.0375, :apr, :duration => 30.years)
-    @principal = D(200000)
-    @amortization = Amortization.new(@principal, @rate)
-  end
+  context "a fixed-rate amortization of 200000 at 3.75% over 30 years" do
+    setup do
+      @rate = Rate.new(0.0375, :apr, :duration => 30.years)
+      @principal = D(200000)
+      @std = Amortization.new(@principal, @rate)
+    end
 
-  def test_balance
-    assert @amortization.balance.zero?
-  end
+    should "have a principal of $200,000" do
+      assert_equal @principal, @std.principal
+    end
 
-  def test_duration
-    assert_equal 360, @amortization.duration
-  end
+    should "have a final balance of zero" do
+      assert @std.balance.zero?
+    end
 
-  def test_interest
-    0.upto 359 do |period|
-      assert_equal @amortization.interest[period], interest_in_period(@principal, @rate.monthly, @amortization.payment, period+1)
+    should "have a duration of 360 months" do
+      assert_equal 360, @std.duration
     end
-  end
 
-  def test_interest_sum
-    assert_equal D('133443.53'), @amortization.interest.sum
-  end
+    should "have a monthly payment of $926.23" do
+      assert_equal D('-926.23'), @std.payment
+    end
 
-  def test_payment
-    assert_equal D('-926.23'), @amortization.payment
-  end
+    should "have a final payment of $926.96 (due to rounding)" do
+      assert_equal D('-926.96'), @std.payments[-1]
+    end
 
-  def test_payments
-    payments = [ D('-926.23') ] * @rate.duration
-    # Account for rounding errors in last payment.
-    payments[-1] = D('-926.96')
-    assert_equal payments, @amortization.payments
-  end
+    should "have total payments of $333,443.53" do
+      assert_equal D('-333443.53'), @std.payments.sum
+    end
 
-  def test_payments_sum
-    assert_equal D('-333443.53'), @amortization.payments.sum
-  end
+    should "have interest charges which agree with the standard formula" do
+      0.upto 359 do |period|
+        assert_equal @std.interest[period], ipmt(@principal, @rate.monthly, @std.payment, period+1)
+      end
+    end
 
-  def test_principal
-    assert_equal @principal, @amortization.principal
+    should "have total interest charges of $133,433.33" do
+      assert_equal D('133443.53'), @std.interest.sum
+    end
   end
 
-  def test_sum
-    assert_equal D(0), @amortization.payments.sum + @amortization.interest.sum + @amortization.principal
-  end
-end
+  context "an adjustable rate amortization of 200000 starting at 3.75% and increasing by 1% every 3 years" do
+    setup do
+      @rates = []
+      0.upto 9 do |adj|
+        @rates << Rate.new(0.0375 + (D('0.01') * adj), :apr, :duration => 3.years)
+      end
+      @principal = D(200000)
+      @arm = Amortization.new(@principal, *@rates)
+    end
 
-class TestAdjustableAmortization < Test::Unit::TestCase
-  def setup
-    @rates = []
-    0.upto 9 do |adj|
-      @rates << Rate.new(0.0375 + (D('0.01') * adj), :apr, :duration => 3.years)
+    should "have a principal of $200,000" do
+      assert_equal @principal, @arm.principal
     end
-    @principal = D(200000)
-    @amortization = Amortization.new(@principal, *@rates)
-  end
 
-  def test_balance
-    assert @amortization.balance.zero?
-  end
+    should "have a final balance of zero" do
+      assert @arm.balance.zero?
+    end
 
-  def test_duration
-    assert_equal 360, @amortization.duration
-  end
+    should "have a duration of 360 months" do
+      assert_equal 360, @arm.duration
+    end
 
-  def test_interest_sum
-    assert_equal D('277505.92'), @amortization.interest.sum
-  end
+    should "not have a fixed monthly payment (since it changes)" do
+      assert_nil @arm.payment
+    end
 
-  def test_payment
-    assert_nil @amortization.payment
-  end
+    should "have payments which increase every three years" do
+      values = %w{926.23 1033.73 1137.32 1235.39 1326.30 1408.27 1479.28 1537.03 1578.84 1601.66 }
+      values.collect!{ |v| -D(v) }
+      
+      payments = []
+      values[0,9].each do |v|
+        36.times do
+          payments << v
+        end
+      end
+
+      35.times { payments << values[9] }
 
-  def test_payments
-    values = %w{926.23 1033.73 1137.32 1235.39 1326.30 1408.27 1479.28 1537.03 1578.84 1601.66 1601.78}
-    values.collect!{ |v| -D(v) }
-    
-    payments = []
-    values[0,9].each do |v|
-      36.times do
-        payments << v
+      payments[0..-2].each_with_index do |payment, index|
+        assert_equal payment, @arm.payments[index]
       end
     end
 
-    35.times { payments << values[9] }
-    payments << values[10]
-
-    payments.each_with_index do |payment, index|
-      assert_equal payment, @amortization.payments[index]
+    should "have a final payment of $1601.78 (due to rounding)" do
+      assert_equal D('-1601.78'), @arm.payments[-1]
     end
-  end
 
-  def test_payment_sum
-    assert_equal D('-477505.92'), @amortization.payments.sum
-  end
+    should "have total payments of $47,505.92" do
+      assert_equal D('-477505.92'), @arm.payments.sum
+    end
 
-  def test_principal
-    assert_equal @principal, @amortization.principal
+    should "have total interest charges of $277,505.92" do
+      assert_equal D('277505.92'), @arm.interest.sum
+    end
   end
 
-  def test_sum
-    assert_equal D(0), @amortization.payments.sum + @amortization.interest.sum + @amortization.principal
-  end
-end
+  context "a fixed-rate amortization of 200000 at 3.75% over 30 years, where an additional 100 is paid each month" do
+    setup do
+      @rate = Rate.new(0.0375, :apr, :duration => 30.years)
+      @principal = D(200000)
+      @exp = Amortization.new(@principal, @rate){ |period| period.payment - 100 }
+    end
 
-class TestExtraPaymentAmortization < Test::Unit::TestCase
-  def setup
-    @rate = Rate.new(0.0375, :apr, :duration => 30.years)
-    @principal = D(200000)
-    @amortization = Amortization.new(@principal, @rate){ |period| period.payment - 100 }
-  end
+    should "have a principal of $200,000" do
+      assert_equal @principal, @exp.principal
+    end
 
-  def test_additional_payments_sum
-    assert_equal D('-30084.86'), @amortization.additional_payments.sum
-  end
-  
-  def test_balance
-    assert @amortization.balance.zero?
-  end
+    should "have a final balance of zero" do
+      assert @exp.balance.zero?
+    end
 
-  def test_duration
-    assert_equal 301, @amortization.duration
-  end
+    should "have a duration of 301 months" do
+      assert_equal 301, @exp.duration
+    end
 
-  def test_interest_sum
-    assert_equal D('108880.09'), @amortization.interest.sum
-  end
+    should "have a monthly payment of $1026.23" do
+      assert_equal D('-1026.23'), @exp.payment
+    end
 
-  def test_payment
-    assert_equal D('-1026.23'), @amortization.payment
-  end
+    should "have a final payment of $1011.09" do
+      assert_equal D('-1011.09'), @exp.payments[-1]
+    end
 
-  def test_payment_sum
-    assert_equal D('-308880.09'), @amortization.payments.sum
-  end
+    should "have total payments of $308,880.09" do
+      assert_equal D('-308880.09'), @exp.payments.sum
+    end
 
-  def test_principal
-    assert_equal @principal, @amortization.principal
-  end
+    should "have total additional payments of $30,084.86" do
+      assert_equal D('-30084.86'), @exp.additional_payments.sum
+    end
 
-  def test_sum
-    assert_equal D(0), @amortization.payments.sum + @amortization.interest.sum + @amortization.principal
+    should "have total interest charges of $108880.09" do
+      assert_equal D('108880.09'), @exp.interest.sum
+    end
   end
 end