refinance 1.0.0 → 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2b891ac8019babc3e1e7dddeeca467eab9d4b23f
+  data.tar.gz: c1afcdc0ac1014dee2e3f0bc11621f5308caa28b
+SHA512:
+  metadata.gz: 118220872ce33ab4b8d3d5a16b690c78af2d90d907021fb7ddbf57b8e7965abd67f99ff58b781a4e06ac12e998e56a845d217d7e48c754ec1c02aa36a9c7a592
+  data.tar.gz: f2b738e5e698945af6219359d62da8274e5826b8448860915ee608c1da4f026584b442a894c08d8d3b6adbf880d0975dedfe40affc0a2c5b79436feb19145a05

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2013 reInteractive Pty Ltd
+Copyright (c) 2012-2014 reInteractive Pty Ltd
 
 MIT License
 

data/README.md

@@ -5,17 +5,178 @@ Currently, it contains algorithms for calculating the properties of ordinary
 annuities: principal, interest rate, number of payment periods, and payment
 amount.
 
-The algorithms are simple rather than fast and numerically robust. Thanks to
-duck typing, they work with both BigDecimals and Floats. At present, they deal
-only with _annuities immediate_ (in which the interest is accumulated _before_
-the payment), not _annuities due_ (in which the interest is accumulated _after_
-the payment). There are many opportunities for extension and improvement.
+## Introduction
+
+Refinance does calculations related to
+[annuities](http://en.wikipedia.org/wiki/Annuity_%28finance_theory%29) in
+finance theory. In general, an annuity is a finite series of regular payments;
+an installment loan for a car is an example that might be familiar to you.
+
+Refinance allows you to answer questions like these:
+
+1. Say you have a car loan and are paying a fixed amount each month to pay it
+off. If you got a reduced interest rate, exactly how much lower would your
+monthly payments be?
+
+2. If you get a reduced interest rate but continue to pay the same monthly
+payments, exactly how much shorter will the loan duration be?
+
+3. Say you want to borrow money to buy a car. If your bank will lend you money
+at an X% annual interest rate, and you're willing to make monthly payments as
+high as $Y, how expensive of a car can you buy?
+
+4. Say you're making monthly payments of $X to pay off a $Y loan. What interest
+rate are you being charged?
+
+5. Say your loan has an interest rate of X% per month. What is its effective
+_annual_ interest rate?
+
+Annuities have four defining properties (at least for our purposes), and the
+first four questions above provide examples of each: The first question is
+asking for the annuity's _periodic payment amount_. The second is asking for
+the _number of remaining payments_. The third is asking for the _principal_.
+And the fourth is asking for the _interest rate_.
+
+In general, if you know three of those properties, Refinance can calculate
+the fourth.
+
+The fifth question is about converting an interest rate. Perhaps you think this
+is trivial: if you're paying 1% per month, then it's equivalent to paying 12%
+per year, right? Wrong. It's more like 12.68%. You need to account for the
+effects of [compound interest](http://en.wikipedia.org/wiki/Compound_interest).
+
+
+## Usage example
+
+I'll use [Example 2 from Stan Brown's paper](http://oakroadsystems.com/math/loan.htm#Sample2):
+
+> You are buying a $250,000 house, with 10% down, on a 30-year mortgage at a
+> fixed rate of 7.8%. What is the monthly payment?
+
+We want to calculate the monthly payment, so we'll use the method
+Refinance::Annuities.payment. That method requires three arguments: the
+interest rate (per month, since we're calculating the monthly payment), the
+total number of monthly payments, and the principal. These are easy to
+determine from the example:
+
+* The interest rate is 7.8%, but there are two things to note here. First, 7.8%
+is a [nominal annual rate](http://en.wikipedia.org/wiki/Nominal_interest_rate),
+and we want the monthly interest rate. So we divide 7.8% by 12 (because there
+are 12 months in a year) and get 0.65%. Second, the method wants the argument
+in decimal form, not percent form, so 0.65% becomes 0.0065.
+
+* The loan lasts 30 years, and we want the number of payment periods -- that
+is, the number of months. 30 years is 360 months.
+
+* The house's purchase price is $250,000, and we're making a 10% down payment,
+so the loan's principal will be 90% of $250,000, or $225,000.
+
+Now we can call the method:
+
+    Refinance::Annuities.payment 0.0065, 360.0, 225000.0
+
+(You can name the arguments "interest rate", "periods", and "principal". For
+this and related methods, the arguments go in alphabetical order.)
+
+The return value is 1619.7086268909618. So the monthly payment is about
+$1,619.71.
+
+
+## API
+
+Here's a summary of the public-facing methods provided by this library. They
+are all stateless "functions".
+
+Arguments to these methods are not directly converted to a particular numeric
+type; they can be any objects that support the necessary mathematical methods.
+Instances of Float and BigDecimal will work for real-valued arguments.
+
+Interest rates must be in decimal form, not percent form.
+
+
+### Refinance::Annuities.interest_rate
+
+This method calculates an annuity's interest rate over its payment period. The
+result will be given as a decimal number, not as a percent. There is no
+closed-form solution for this, so the answer is iteratively approximated with
+the
+[Newton-Raphson method](http://en.wikipedia.org/wiki/Newton-raphson_method).
+
+Arguments:
+
+1. The periodic payment amount.
+2. The total number of payment periods.
+3. The principal.
+4. (Optional) The initial guess at the interest rate.
+5. (Optional) The precision; the algorithm will stop if the magnitude of the
+last improvement was less than this.
+6. (Optional) The maximum number of decimal places. After each iteration, the
+guess will be rounded to this many decimal places.
+7. (Optional) The maximum number of iterations to allow.
+
+
+### Refinance::Annuities.payment
+
+This method calculates an annuity's periodic payment amount.
+
+Arguments:
+
+1. The interest rate over one payment period.
+2. The total number of payment periods.
+3. The principal.
+
+
+### Refinance::Annuities.periods
+
+This method calculates the total number of payment periods for an annuity.
+
+Arguments:
+
+1. The interest rate over one payment period.
+2. The periodic payment amount.
+3. The principal.
+
+
+### Refinance::Annuities.principal
+
+This method calculates the principal of an annuity.
+
+Arguments:
+
+1. The interest rate over one payment period.
+2. The periodic payment amount.
+3. The total number of payment periods.
+
+
+### Refinance::Annuities.effective_interest_rate
+
+This method calculates the effective annual interest rate.
+
+Arguments:
+
+1. The nominal annual interest rate.
+2. The number of compounding periods per year.
+
+
+## Implementation
+
+The algorithms are simple rather than fast and
+[numerically stable](http://en.wikipedia.org/wiki/Numerical_stability). At
+present, they deal only with _annuities immediate_ (in which the interest is
+accumulated _before_ the payment), not _annuities due_ (in which the interest
+is accumulated _after_ the payment).
+
 
 ## Requirements
 
-This library is tested with versions 1.9.3 and 2.0.0 of MRI (Matz's Ruby
-Interpreter). It also works with version 1.9.2 if you only use Float, not
-BigDecimal, for floating-point values.
+This library is tested with the following versions of MRI (Matz's Ruby
+Interpreter): 1.9.3, 2.0.0, 2.1.0, 2.1.1, and 2.1.2.
+
+If you wish you to use BigDecimal, we recommend using the
+[bigdecimal gem](https://rubygems.org/gems/bigdecimal) instead of the version
+of BigDecimal that ships in the standard library. Refinance's test suite does
+not pass with the version of BigDecimal that ships with MRI 2.1.0.
+
 
 ## Installation
 
@@ -31,6 +192,7 @@ Or install it yourself as:
 
     $ gem install refinance
 
+
 ## Contributing
 
 1. Fork it
@@ -39,15 +201,17 @@ Or install it yourself as:
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
+
 ## Authorship and copyright information
 
 This software was written by [reInteractive](http://reinteractive.net/), a
 software consulting company in Sydney, Australia. It is distributed under the
 MIT License; see LICENSE.txt for details.
 
+
 ## Acknowledgements
 
-Thanks to Stan Brown for his paper _[Loan or Investment
-Formulas](http://oakroadsystems.com/math/loan.htm)_. It is an excellent
-introduction to the mathematics of annuities, and we used some of its examples
-as test cases.
+Thanks to Stan Brown for his paper
+_[Loan or Investment Formulas](http://oakroadsystems.com/math/loan.htm)_. It is
+an excellent introduction to the mathematics of annuities, and we used some of
+its examples as test cases.

data/lib/refinance/version.rb

@@ -1,3 +1,3 @@
 module Refinance
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/refinance.gemspec

@@ -1,24 +1,26 @@
-# -*- encoding: utf-8 -*-
+# coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'refinance/version'
 
-Gem::Specification.new do |gem|
-  gem.name = "refinance"
-  gem.version = Refinance::VERSION
-  gem.authors = ["reInteractive"]
-  gem.email = ["enquiries@reinteractive.net"]
-  gem.description = %q{A collection of finance algorithms related to annuities.}
-  gem.summary = %q{Simple annuity algorithms}
-  gem.homepage = "https://github.com/reinteractive-open/refinance"
-  gem.license = "MIT"
-  gem.required_ruby_version = ">= 1.9.3"
+Gem::Specification.new do |spec|
+  spec.name = 'refinance'
+  spec.version = Refinance::VERSION
+  spec.author = 'reInteractive'
+  spec.email = 'enquiries@reinteractive.net'
+  spec.description = %q{A collection of finance algorithms related to annuities.}
+  spec.summary = %q{Simple annuity algorithms}
+  spec.homepage = 'https://github.com/reinteractive-open/refinance'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 1.9.3'
+  spec.platform = Gem::Platform::RUBY
 
-  gem.files = `git ls-files`.split($/)
-  gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
-  gem.require_paths = ["lib"]
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
 
-  gem.add_development_dependency 'rake', '10.0.4'
-  gem.add_development_dependency 'minitest', '4.7.4'
+  spec.add_development_dependency 'rake', '10.3.2'
+  spec.add_development_dependency 'minitest', '5.3.5'
+  spec.add_development_dependency 'bigdecimal', '1.2.5'
 end

data/test/annuities_helper.rb

@@ -0,0 +1,57 @@
+module AnnuitiesHelper
+  def assert_improve_interest_rate options
+    actual = Refinance::Annuities.improve_interest_rate(
+      options.fetch(:payment),
+      options.fetch(:periods),
+      options.fetch(:principal),
+      options.fetch(:guess))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_interest_rate_stops_if_improvement_is_small options
+    actual = Refinance::Annuities.interest_rate(options.fetch(:payment),
+      options.fetch(:periods), options.fetch(:principal),
+      options.fetch(:guess), options.fetch(:precision))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_interest_rate_does_multiple_iterations options
+    actual = Refinance::Annuities.interest_rate(options.fetch(:payment),
+      options.fetch(:periods), options.fetch(:principal),
+      options.fetch(:guess), options.fetch(:precision),
+      options.fetch(:max_decimals), options.fetch(:max_iterations))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_payment options
+    actual = Refinance::Annuities.payment(options.fetch(:interest_rate),
+      options.fetch(:periods), options.fetch(:principal))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_periods options
+    actual = Refinance::Annuities.periods(options.fetch(:interest_rate),
+      options.fetch(:payment), options.fetch(:principal))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_principal options
+    actual = Refinance::Annuities.principal(options.fetch(:interest_rate),
+      options.fetch(:payment), options.fetch(:periods))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+
+  def assert_effective_interest_rate options
+    actual = Refinance::Annuities.effective_interest_rate(
+      options.fetch(:nominal_annual_interest_rate),
+      options.fetch(:compounding_periods_per_year))
+
+    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
+  end
+end

data/test/bigdecimal_annuities_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
-require 'bigdecimal'
 
-class BigDecimalAnnuitiesTest < AnnuitiesTest
+class BigDecimalAnnuitiesTest < Minitest::Test
+  include AnnuitiesHelper
 
   def test_improve_interest_rate
     # Based on Example 6 in http://oakroadsystems.com/math/loan.htm .
@@ -31,6 +31,13 @@ class BigDecimalAnnuitiesTest < AnnuitiesTest
       delta: BigDecimal.new('0.0000000001')
   end
 
+  def test_interest_rate_stops_if_max_iterations_reached
+    expected = BigDecimal.new('0.42')
+    actual = Refinance::Annuities.interest_rate(0, 0, 0, expected, 0, 1, 0)
+
+    assert_equal expected, actual
+  end
+
   def test_payment
     # Based on Example 2 in http://oakroadsystems.com/math/loan.htm .
     assert_payment interest_rate: BigDecimal.new('0.0065'),

data/test/float_annuities_test.rb

@@ -1,6 +1,7 @@
 require 'test_helper'
 
-class FloatAnnuitiesTest < AnnuitiesTest
+class FloatAnnuitiesTest < Minitest::Test
+  include AnnuitiesHelper
 
   def test_improve_interest_rate
     # Based on Example 6 in http://oakroadsystems.com/math/loan.htm .
@@ -24,7 +25,15 @@ class FloatAnnuitiesTest < AnnuitiesTest
       delta: 0.0000000001
   end
 
+  def test_interest_rate_stops_if_max_iterations_reached
+    expected = 0.42
+    actual = Refinance::Annuities.interest_rate(0, 0, 0, expected, 0, 1, 0)
+
+    assert_equal expected, actual
+  end
+
   def test_payment
+    # Based on Example 2 in http://oakroadsystems.com/math/loan.htm .
     assert_payment interest_rate: 0.0065, periods: 360.0, principal: 225000.0,
       expected: 1619.708627, delta: 0.000001
   end

data/test/refinance_test.rb

@@ -1,18 +1,11 @@
 require 'test_helper'
 
-class RefinanceTest < Minitest::Unit::TestCase
+class RefinanceTest < Minitest::Test
   def test_refinance_is_a_module
-    assert_kind_of Module, ::Refinance
+    assert_kind_of ::Module, ::Refinance
   end
 
   def test_version_is_a_string
-    assert_kind_of String, ::Refinance::VERSION
-  end
-
-  def test_interest_rate_stops_if_max_iterations_reached
-    expected = 0.42
-    actual = Refinance::Annuities.interest_rate(0, 0, 0, expected, 0, 1, 0)
-
-    assert_equal expected, actual
+    assert_kind_of ::String, ::Refinance::VERSION
   end
 end

data/test/test_helper.rb

@@ -1,60 +1,4 @@
 require 'minitest/autorun'
+require 'bigdecimal'
 require 'refinance'
-
-class AnnuitiesTest < Minitest::Unit::TestCase
-  def assert_improve_interest_rate options
-    actual = Refinance::Annuities.improve_interest_rate(
-      options.fetch(:payment),
-      options.fetch(:periods),
-      options.fetch(:principal),
-      options.fetch(:guess))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_interest_rate_stops_if_improvement_is_small options
-    actual = Refinance::Annuities.interest_rate(options.fetch(:payment),
-      options.fetch(:periods), options.fetch(:principal),
-      options.fetch(:guess), options.fetch(:precision))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_interest_rate_does_multiple_iterations options
-    actual = Refinance::Annuities.interest_rate(options.fetch(:payment),
-      options.fetch(:periods), options.fetch(:principal),
-      options.fetch(:guess), options.fetch(:precision),
-      options.fetch(:max_decimals), options.fetch(:max_iterations))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_payment options
-    actual = Refinance::Annuities.payment(options.fetch(:interest_rate),
-      options.fetch(:periods), options.fetch(:principal))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_periods options
-    actual = Refinance::Annuities.periods(options.fetch(:interest_rate),
-      options.fetch(:payment), options.fetch(:principal))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_principal options
-    actual = Refinance::Annuities.principal(options.fetch(:interest_rate),
-      options.fetch(:payment), options.fetch(:periods))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-
-  def assert_effective_interest_rate options
-    actual = Refinance::Annuities.effective_interest_rate(
-      options.fetch(:nominal_annual_interest_rate),
-      options.fetch(:compounding_periods_per_year))
-
-    assert_in_delta options.fetch(:expected), actual, options.fetch(:delta)
-  end
-end
+require 'annuities_helper'

metadata

@@ -1,56 +1,64 @@
 --- !ruby/object:Gem::Specification
 name: refinance
 version: !ruby/object:Gem::Version
-  version: 1.0.0
-  prerelease: 
+  version: 1.0.1
 platform: ruby
 authors:
 - reInteractive
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-03 00:00:00.000000000 Z
+date: 2014-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 10.0.4
+        version: 10.3.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 10.0.4
+        version: 10.3.2
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 4.7.4
+        version: 5.3.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 4.7.4
+        version: 5.3.5
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.5
 description: A collection of finance algorithms related to annuities.
-email:
-- enquiries@reinteractive.net
+email: enquiries@reinteractive.net
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -59,6 +67,7 @@ files:
 - lib/refinance/annuities.rb
 - lib/refinance/version.rb
 - refinance.gemspec
+- test/annuities_helper.rb
 - test/bigdecimal_annuities_test.rb
 - test/float_annuities_test.rb
 - test/refinance_test.rb
@@ -66,32 +75,29 @@ files:
 homepage: https://github.com/reinteractive-open/refinance
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 1916847891747794597
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Simple annuity algorithms
 test_files:
+- test/annuities_helper.rb
 - test/bigdecimal_annuities_test.rb
 - test/float_annuities_test.rb
 - test/refinance_test.rb