xirr 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40bfdec7ad5bfb2ae2cb80594b933c9c75d2053a
-  data.tar.gz: 196370852aa56efc624cccb7be975104722b33e9
+  metadata.gz: ac4ff922b29d910ccb51a3238c6602d0309bc685
+  data.tar.gz: 912024facef6c25c236f99f8e86fa0ee75efa496
 SHA512:
-  metadata.gz: 2af18cc9ed8157e699c2eb37eeffcee906b89c499265e552d373e0f1eba654a1cfcc236939766d34cdb42fba98dabab451e6a6b78f5225bbacd4c541fdcf8ff1
-  data.tar.gz: f2bcc8a7a251626d1d4c34cbd433be6e2d9de0d49c614cc55963836211987651f6638638f26307051722141e8401daaa758238f5827b3165b009981e247613b8
+  metadata.gz: 68610190f330d76c57f1b638d92210002400a4011387816b1cb369c502055a7e2922545cfd2dfc997abcd0c560b0db4e48e4248342d0a09ee1eb6206b7eb8be3
+  data.tar.gz: b31417b22db2501bf5547610340c38031d8d83d372832335196d286ec51893968cb62e94f03b73cb61dca813e469bca4310e671fd5e51bf7967a7347cceece36

data/lib/xirr.rb

@@ -3,6 +3,8 @@ require 'active_support/configurable'
 require 'xirr/config'
 require 'xirr/main'
 
+# @abstract adds a {Xirr::Cashflow} and {Xirr::Transaction} classes to calculate IRR of irregular transactions.
+# Calculates Xirr
 module Xirr
 
   autoload :Transaction,  'xirr/transaction'

data/lib/xirr/cashflow.rb

@@ -1,14 +1,25 @@
 module Xirr
+
+  # Expands [Array] to store a set of transactions which will be used to calculate the XIRR
+  # @note A Cashflow should consist of at least two transactions, one positive and one negative.
   class Cashflow < Array
     include Xirr::Main
 
+    # @api public
+    # @param args [Transaction]
+    # @example Creating a Cashflow
+    #   cf = Cashflow.new
+    #   cf << Transaction.new( 1000, date: '2013-01-01'.to_time(:utc))
+    #   cf << Transaction.new(-1234, date: '2013-03-31'.to_time(:utc))
+    #   Or
+    #   cf = Cashflow.new Transaction.new( 1000, date: '2013-01-01'.to_time(:utc)), Transaction.new(-1234, date: '2013-03-31'.to_time(:utc))
     def initialize(*args) # :nodoc:
       args.each { |a| self << a }
       self.flatten!
     end
 
     # Check if Cashflow is invalid and raises ArgumentError
-    # retuns [Boolean]
+    # @return [Boolean]
     def invalid?
       if positives.empty? || negatives.empty?
         raise ArgumentError, invalid_message
@@ -18,64 +29,96 @@ module Xirr
     end
 
     # Inverse of #invalid?
-    # returns [Boolean]
+    # @return [Boolean]
     def valid?
       !invalid?
     end
 
+    # @return [Float]
+    # Sums all amounts in a cashflow
+    def sum # :nodoc:
+      self.map(&:amount).sum
+    end
 
-    # calculates a simple IRR guess based on period of investment and multiples
-    # returns [Float]
-    def irr_guess
-      ((multiple ** (1 / years_of_investment)) - 1).round(3)
+    # Last investment date
+    # @return [Time]
+    def max_date # :nodoc:
+      @max_date ||= self.map(&:date).max
     end
 
-    def sum # :nodoc:
-      self.map(&:amount).sum
+    # Calculates a simple IRR guess based on period of investment and multiples.
+    # @return [Float]
+    def irr_guess
+      ((multiple ** (1 / years_of_investment)) - 1).round(3)
     end
 
     private
 
-    def first_transaction_direction # :nodoc:
-      self.sort! { |x,y| x.date <=> y.date }
+    # @api private
+    # Sorts the {Cashflow} by date ascending
+    #   and finds the signal of the first transaction.
+    # This implies the first transaction is a disembursement
+    # @return [Integer]
+    def first_transaction_direction
+      self.sort! { |x, y| x.date <=> y.date }
       self.first.amount / self.first.amount.abs
     end
 
-    # Based on the direction of the first investment we create the multiple
-    def multiple  # :nodoc:
-      if first_transaction_direction > 0
-        positives.sum(&:amount) / -negatives.sum(&:amount)
-      else
-        -negatives.sum(&:amount) / positives.sum(&:amount)
-      end
+    # Based on the direction of the first investment finds the multiple cash-on-cash
+    # @example
+    #   [100,100,-300] and [-100,-100,300] returns 1.5
+    # @api private
+    # @return [Float]
+    def multiple # :nodoc:
+      result = positives.sum(&:amount) / -negatives.sum(&:amount)
+      first_transaction_direction > 0 ? result : 1 / result
     end
 
+    # @api private
+    # Counts how many years from first to last transaction in the cashflow
+    # @return
     def years_of_investment # :nodoc:
       (max_date - min_date) / (365 * 24 * 60 * 60).to_f
     end
 
-    def max_date # :nodoc:
-      @max_date ||= self.map(&:date).max
-    end
-
+    # @api private
+    # First investment date
+    # @return [Time]
     def min_date # :nodoc:
       @min_date ||= self.map(&:date).min
     end
 
+    # @api private
+    # @return [Array]
+    # @see #negatives
+    # @see #split_transactions
+    # Finds all transactions income from Cashflow
     def positives # :nodoc:
       split_transactions
       @positives
     end
 
+    # @api private
+    # @return [Array]
+    # @see #positives
+    # @see #split_transactions
+    # Finds all transactions investments from Cashflow
     def negatives # :nodoc:
       split_transactions
       @negatives
     end
 
+    # @api private
+    # @see #positives
+    # @see #negatives
+    # Uses partition to separate the investment transactions Negatives and the income transactions (Positives)
     def split_transactions # :nodoc:
       @negatives, @positives = self.partition { |x| x.amount >= 0 } # Inverted as negative amount is good
     end
 
+    # @api private
+    # @return [String]
+    # Error message depending on the missing transaction
     def invalid_message # :nodoc:
       return 'No positive transaction' if positives.empty?
       return 'No negatives transaction' if negatives.empty?

data/lib/xirr/config.rb

@@ -1,11 +1,13 @@
 module Xirr
   include ActiveSupport::Configurable
 
+  # Default values
   default_values = {
       eps: '1.0e-12',
       days_in_year: 365,
   }
 
+  # Iterates trhough default values and sets in config
   default_values.each do |key, value|
     self.config.send("#{key.to_sym}=", value)
   end

data/lib/xirr/main.rb

@@ -2,70 +2,77 @@ require 'active_support/concern'
 
 module Xirr
 
+  # Methods that will be included in Cashflow to calculate XIRR
   module Main
     extend ActiveSupport::Concern
 
     # Calculates yearly Internal Rate of Return
-    # returns [Float]
+    # @return [Float]
+    # @param guess [Float] an initial guess rate that will override the {Cashflow#irr_guess}
     def xirr(guess = nil)
 
+      # Raises error if Cashflow is not valid
       self.valid?
 
       # Bisection method finding the rate to zero nfv
 
+      # Initial values
       days_in_year = Xirr.config.days_in_year.to_f
-
       left = -0.99/days_in_year
       right = 9.99/days_in_year
       epsilon = Xirr.config.eps.to_f
-
       guess = self.irr_guess.to_f
 
+      # Loops until difference is within error margin
       while ((right-left).abs > 2 * epsilon) do
 
         midpoint = guess || (right + left)/2
         guess = nil
+        nfv_positive?(left, midpoint) ? left = midpoint : right = midpoint
 
-        if (nfv(left) * nfv(midpoint) > 0)
-
-          left = midpoint
+      end
 
-        else
+      return format_irr(left, right)
 
-          right = midpoint
+    end
 
-        end
+    private
 
-      end
+    # @param left [Float]
+    # @param midpoint [Float]
+    # @return [Bolean]
+    # Returns true if result is to the right ot the range
+    def nfv_positive?(left, midpoint)
+      (nfv(left) * nfv(midpoint) > 0)
+    end
 
+    # @param left [Float]
+    # @param right [Float]
+    # @return [Float] IRR of the Cashflow
+    def format_irr(left, right)
+      days_in_year = Xirr.config.days_in_year.to_f
       # Irr for daily cashflow (not in percentage format)
       irr = (right+left) / 2
       # Irr for daily cashflow multiplied by 365 to get yearly return
       irr = irr * days_in_year
       # Annualized yield (return) reflecting compounding effect of daily returns
       irr = (1 + irr / days_in_year) ** days_in_year - 1
-
-      return irr
-
     end
 
-    private
-
+    # Returns the Net future value of the flow given a Rate
+    # @param rate [Float]
+    # @return [Float]
     def nfv(rate) # :nodoc:
-
-      today = self.map(&:date).max.to_date
-      nfv = 0
-      self.each do |t|
-        cf, date = t.amount, t.date
-
-        datestring = date.to_s
-        formatteddate = Date.parse(datestring).to_date
-        t_in_days = (today - formatteddate).numerator / (today - formatteddate).denominator
-        nfv = nfv + cf * ((1 + rate) ** t_in_days)
-
+      self.inject(0) do |nfv,t|
+        nfv = nfv + t.amount * ((1 + rate) ** t_in_days(t.date))
       end
-      return nfv
+    end
 
+    # Calculates days until last transaction
+    # @return [Rational]
+    # @param date [Time]
+    def t_in_days(date)
+      Date.parse(max_date.to_s) - Date.parse(date.to_s)
     end
 
   end

data/lib/xirr/transaction.rb

@@ -1,12 +1,14 @@
 module Xirr
 
+  # A unit of the Cashflow.
   class Transaction
     attr_reader :amount
     attr_accessor :date
 
+    # @example
+    #   Transaction.new -1000, date: Time.now
     def initialize(amount, opts={})
       @amount = amount
-      @original = amount
 
       # Set optional attributes..
       opts.each do |key, value|
@@ -14,30 +16,18 @@ module Xirr
       end
     end
 
+    # Sets the amount
+    # @param value [Float, Integer]
+    # @return [Float]
     def amount=(value)
       @amount = value.to_f || 0
     end
 
+    # @return [String]
     def inspect
       "T(#{@amount},#{@date})"
     end
 
-    def description
-      investment ? "#{self.investment.transaction_type_name}: #{round.description}" : @description
-    end
-
-    def round
-      @investment.nil? ? nil : investment.round
-    end
-
-    def company
-      @company || investment.company
-    end
-
-    def shareholder
-      @shareholder || investment.shareholder
-    end
-
   end
 
 end

data/lib/xirr/version.rb

@@ -1,3 +1,4 @@
 module Xirr
-  VERSION = "0.1.0"
+  # Version of the Gem
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xirr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - tubedude