financial_calculator 2.1.0

data/lib/financial_calculator/cashflows.rb

@@ -0,0 +1,127 @@
+require_relative 'decimal'
+require_relative 'rates'
+
+require 'bigdecimal'
+require 'bigdecimal/newton'
+include Newton
+
+module FinancialCalculator
+  # Provides methods for working with cash flows (collections of transactions)
+  # @api public
+  module Cashflow
+    # Base class for working with Newton's Method.
+    # @api private
+    class Function
+      values = {
+        eps: "1.0e-16",
+        one: "1.0",
+        two: "2.0",
+        ten: "10.0",
+        zero: "0.0"
+        }
+
+      values.each do |key, value|
+        define_method key do
+          BigDecimal(value)
+        end
+      end
+
+      def initialize(transactions, function)
+        @transactions = transactions
+        @function = function
+      end
+
+      def values(x)
+        value = @transactions.send(@function, Flt::DecNum.new(x[0].to_s))
+        [ BigDecimal(value.to_s) ]
+      end
+    end
+
+    # 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
+      # Make sure we have a valid sequence of cash flows.
+      positives, negatives = self.partition{ |i| i >= 0 }
+      if positives.empty? || negatives.empty?
+        raise ArgumentError, "Calculation does not converge."
+      end
+
+      func = Function.new(self, :npv)
+      rate = [ func.one ]
+      nlsolve( func, rate )
+      rate[0]
+    end
+
+    def method_missing(name, *args, &block)
+      return self.inject(:+) if name.to_s == "sum"
+      super
+    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| Flt::DecNum.new(entry.to_s) }
+
+      rate, total = Flt::DecNum.new(rate.to_s), Flt::DecNum.new(0.to_s)
+      self.each_with_index do |cashflow, index|
+        total += cashflow / (1 + rate) ** index
+      end
+
+      total
+    end
+
+    # calculate the internal rate of return for a sequence of cash flows with dates
+    # @return [Rate] the internal rate of return
+    # @example
+    #   @transactions = []
+    #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
+    #   @transactions.xirr(0.6) #=> Rate("0.024851", :apr, :compounds => :annually)
+    # @api public
+    def xirr(iterations=100)
+      # Make sure we have a valid sequence of cash flows.
+      positives, negatives = self.partition{ |t| t.amount >= 0 }
+      if positives.empty? || negatives.empty?
+        raise ArgumentError, "Calculation does not converge."
+      end
+
+      func = Function.new(self, :xnpv)
+      rate = [ func.one ]
+      nlsolve( func, rate )
+      Rate.new(rate[0], :apr, :compounds => :annually)
+    end
+
+    # calculate the net present value of a sequence of cash flows
+    # @return [DecNum]
+    # @example
+    #   @transactions = []
+    #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
+    #   @transactions.xnpv(0.6).round(2) #=> -937.41
+    # @api public
+    def xnpv(rate)
+      rate  = Flt::DecNum.new(rate.to_s)
+      start = self[0].date
+
+      self.inject(0) do |sum, t|
+        n = t.amount / ( (1 + rate) ** ((t.date-start) / Flt::DecNum.new(31536000.to_s))) # 365 * 86400
+        sum + n
+      end
+    end
+  end
+end
+
+class Array
+  include FinancialCalculator::Cashflow
+end

data/lib/financial_calculator/decimal.rb

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'flt'
+include Flt
+
+DecNum.context.define_conversion_from(BigDecimal) do |x, context|
+  DecNum(x.to_s)
+end
+
+DecNum.context.define_conversion_to(BigDecimal) do |x|
+  BigDecimal.new(x.to_s)
+end
+
+class Numeric
+  def to_d
+    if self.instance_of? DecNum
+      self
+    else
+      DecNum self.to_s
+    end
+  end
+end

data/lib/financial_calculator/rates.rb

@@ -0,0 +1,167 @@
+require_relative 'decimal'
+
+module FinancialCalculator
+  # 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.new(1)
+                 when :continuously then Flt::DecNum.infinity
+                 when :daily        then Flt::DecNum.new(365)
+                 when :monthly      then Flt::DecNum.new(12)
+                 when :quarterly    then Flt::DecNum.new(4)
+                 when :semiannually then Flt::DecNum.new(2)
+                 when Numeric       then Flt::DecNum.new(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)}=", Flt::DecNum.new(rate.to_s))
+      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 = Flt::DecNum.new(rate.to_s), Flt::DecNum.new(periods.to_s)
+
+      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 = Flt::DecNum.new(rate.to_s), Flt::DecNum.new(periods.to_s)
+
+      if periods.infinite?
+        (rate + 1).log
+      else
+        periods * ((1 + rate) ** (1 / periods) - 1)
+      end
+    end
+
+    private :compounds=, :effective=, :nominal=
+  end
+end

data/lib/financial_calculator/transaction.rb

@@ -0,0 +1,122 @@
+require_relative 'decimal'
+
+module FinancialCalculator
+  # 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
+    # @return [Date] the date of the transaction
+    # @api public
+    attr_accessor :date
+
+    # 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 = Flt::DecNum.new(value.to_s)
+    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/lib/financial_calculator/version.rb

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

data/lib/financial_calculator.rb

@@ -0,0 +1,15 @@
+require 'financial_calculator/decimal'
+require 'financial_calculator/cashflows'
+
+# The *FinancialCalculator* module adheres to the following conventions for
+# financial calculations:
+#
+#  * Positive values represent cash inflows (money received); negative
+#    values represent cash outflows (payments).
+#  * *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'
+end