finance 0.0.1 → 0.1.0

data/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README

@@ -1,30 +1,74 @@
-= ABOUT
+_finance_ - a library for financial calculations in Ruby.
+
+= INSTALL
+
+	$ sudo gem install finance
+
+= OVERVIEW
+
+== GETTING STARTED
+
+	>> require 'finance'
+
+== AMORTIZATION
+
+You are interested in borrowing $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)
+
+Find the standard monthly payment:
 
-The goal of the _finance_ library is to provide Ruby implementations
-of common financial formulas, with a function syntax similar to most
-modern spreadsheet programs.  As the project matures, consideration will
-also be given to providing useful, but more advanced functions, which
-may not be suitable for a spreadsheet environment but are useful when
-programming.
+	>> amortization.payment
+	=> DecNum('-1229.91')
+
+Find the total cost of the loan:
+
+	>> amortization.payments.sum
+	=> DecNum('-442766.55')
+
+How much will you pay in interest?
+
+	>> amortization.interest.sum
+	=> DecNum('192766.55')
+
+How much interest in the first six months?
+
+	>> amortization.interest[0,6].sum
+	=> DecNum('5294.62')
+
+= ABOUT
 
 I began developing _finance_ while writing a Ruby script for analyzing
 mortgages.  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.
 
-= EXAMPLES
+If you have used _finance_ and find it useful, I would enjoy hearing
+about it!
 
+= FEATURES
 
+Currently implemented features include:
 
-= INSTALL
+* Fixed-rate mortgage amortization (30/360).
+* Interest rates
+* Various cash flow computations, such as NPV, IRR, and sum.
+
+Planned features include:
 
-+ $ sudo gem install finance +
+* Adjustable rate mortgage amortization.
+* Payment modifications (i.e., how does paying an additional $75 per
+month affect the amortization?)
+* Balloon payments.
+* Support for amortization methods other than 30/360.
 
 = RESOURCES
 
-Source code and bug tracking is available via github:
+This gem and related documentation is available through
+RubyGems[https://rubygems.org/gems/finance].
 
-Project Page:: + http://github.com/wkranec/finance +
-Repository:: + git://github.com/wkranec/finance.git +
+Source code and bug tracking is available via
+github[http://github.com/wkranec/finance].
 
 = COPYRIGHT
 

data/lib/amortization.rb

@@ -0,0 +1,91 @@
+require 'cashflows'
+
+class Period
+	attr_accessor :payment
+	attr_accessor :principal
+	attr_accessor :rate
+
+	# Return the remaining balance at the end of the period.
+	def balance
+		@principal + @payment + self.interest
+	end
+
+	def initialize(principal, rate, payment)
+		@principal = principal
+		@rate = rate
+		@payment = payment
+	end
+
+	# Return the interest charged for the period.
+	def interest
+		(@principal * @rate).round(2)
+	end
+end
+
+class Amortization
+	attr_accessor :balance
+	attr_accessor :duration
+	attr_accessor :payment
+	attr_accessor :periods
+	attr_accessor :principal
+	attr_accessor :rate
+
+	def compute(balance, rate)
+		duration = @duration - @periods.length
+		@payment = Amortization.payment balance, rate.monthly, duration
+
+		rate.duration.times do
+			if @payment > @balance
+				@payment = @balance
+			end
+
+			period = Period.new(@balance, rate.monthly, @payment)
+			@periods << period
+			@balance = period.balance
+
+			if @balance.zero?
+				break
+			end
+		end
+	end
+
+	def initialize(principal, rate)
+		@principal = principal
+		@balance   = principal
+		@rate      = rate
+		@duration  = rate.duration
+		@periods   = []
+
+		compute(@balance, @rate)
+
+		# Add any remaining balance due to rounding error to the last payment.
+		unless @balance.zero?
+			@periods[-1].payment -= @balance
+			@balance = 0
+		end
+	end
+
+	def inspect
+		"Amortization.new(#{@principal}, #{@rate}"
+	end
+
+	def interest
+		@periods.collect { |period| period.interest }
+	end
+
+  # Return the periodic payment due on a loan, based on the
+  #{http://en.wikipedia.org/wiki/Amortization_calculator amortization process}.
+	def Amortization.payment(balance, rate, periods)
+		-(balance * (rate + (rate / ((1 + rate) ** periods - 1)))).round(2)
+	end
+
+	def payments
+		@periods.collect { |period| period.payment }
+	end
+end
+
+class Numeric
+	def amortize(rate)
+		Amortization.new(self, rate)
+	end
+end

data/lib/cashflows.rb

@@ -0,0 +1,33 @@
+module Cashflow
+	# Return the {http://en.wikipedia.org/wiki/Internal_rate_of_return
+	# internal rate of return} for a given sequence of cashflows.
+	def irr(iterations=100)
+		rate = 1.0
+		investment = self[0]
+		for i in 1..iterations+1
+			rate = rate * (1 - self.npv(rate) / investment)
+		end
+		rate
+	end
+
+	# Return the {http://en.wikipedia.org/wiki/Net_present_value net present value} of a sequence of cash flows given
+	# the discount rate _rate_.
+	def npv(rate)
+		total = 0.0
+		self.each_with_index do |cashflow, index|
+			total = total + cashflow / (1+rate) ** index
+		end
+		total
+	end
+
+	def sum
+		self.inject(:+)
+	end
+
+	def xirr
+	end
+end
+
+class Array
+	include Cashflow
+end

data/lib/finance.rb

@@ -1,3 +1,8 @@
+require 'amortization'
+require 'cashflows'
+require 'rates'
+require 'timespan'
+
 # The *Finance* module adheres to the following conventions for
 # financial calculations:
 #
@@ -7,19 +12,6 @@
 #  * *rate* represents the interest rate _per period_.
 module Finance
 
-	# Return the internal rate of return for a given sequence of cashflows.
-	#
-	# References:
-	#  * http://en.wikipedia.org/wiki/Internal_rate_of_return
-	def Finance.irr(cashflows, iterations=100)
-		rate = 1.0
-		investment = cashflows[0]
-		for i in 1..iterations+1
-			rate = rate * (1 - npv(rate, cashflows) / investment)
-		end
-		rate
-	end
-
 	def Finance.payments(principal, rates)
 		p_total = rates.inject(0) { |sum, n| sum + n[0] }
 		p_current = 0
@@ -63,28 +55,6 @@ module Finance
 		payments
 	end
 
-  # Return the periodic payment due on a loan, based on the amortization
-  # process.
-	#
-	# References:
-	#  * http://en.wikipedia.org/wiki/Amortization_calculator
-	def Finance.pmt(principal, rate, periods)
-		principal * (rate + (rate / ((1 + rate) ** periods - 1)))
-	end
-
-	# Return the net present value of a sequence of cash flows given
-	# the discount rate _rate_.
-	#
-	# References:
-	#  * http://en.wikipedia.org/wiki/Net_present_value
-	def Finance.npv(rate, cashflows)
-		total = 0.0
-		cashflows.each_with_index do |cashflow, index|
-			total = total + cashflow / (1+rate) ** index
-		end
-		total
-	end
-
 	# Return the number of periods needed to pay off a loan with the
 	# given payment.
 	def Finance.nper(payment, rate, principal)

data/lib/rates.rb

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'flt'
+
+class Rate
+	attr_accessor :duration
+	attr_accessor :periods
+	attr_accessor :nominal
+
+  # Alias method for *effective*.
+	def apr=(apr)
+		self.effective = apr
+	end
+
+	def apr
+		self.effective
+	end
+
+  # Alias method for *effective*.
+	def apy=(apy)
+		self.effective = apy
+	end
+
+	def apy
+		self.effective
+	end
+
+	def effective=(rate)
+		unless @periods == Flt::DecNum.infinity
+			@nominal = @periods * ((1 + rate) ** (1 / @periods) - 1)
+		else
+			@nominal = Math.log(rate + 1)
+		end
+	end
+
+	def effective
+		unless @periods == Flt::DecNum.infinity
+			(1 + @nominal / @periods) ** @periods - 1
+		else
+			@nominal.exp - 1
+		end
+	end
+
+	def initialize(rate, type, opts={})
+		# Make sure the rate is a decimal.
+		unless rate.class == Flt::DecNum
+			rate = Flt::DecNum rate.to_s 
+		end
+
+		# Set the compounding interval.
+		compounding = opts.fetch(:compounds, :monthly)
+
+		translate = {
+			:annually => Flt::DecNum(1),
+			:continuously => Flt::DecNum.infinity,
+			:daily => Flt::DecNum(365),
+			:monthly => Flt::DecNum(12),
+			:quarterly => Flt::DecNum(4),
+			:semiannually => Flt::DecNum(2)
+			}
+
+		if translate.has_key? compounding
+			@periods = translate.fetch compounding
+		elsif compounding.kind_of? Numeric
+			@periods = Flt::DecNum compounding.to_s 
+		end
+
+		# Set the rate in the proper way, based on the value of :type:.
+		if %w{apr apy effective}.include? type.to_s
+			self.effective = rate
+		else
+			@nominal = rate
+		end
+
+		# Set the remainder of the attributes provided in :opts:.
+		opts.each do |key, value|
+			unless key == :compounds
+			  send("#{key}=", value)
+			end
+		end
+	end
+
+	def inspect
+		"Rate.new(#{self.apr.round(6)}, :apr)"
+	end
+
+	def monthly
+		(self.effective / 12).round(6)
+	end
+end