bankroll 0.1.0

data/README.md

@@ -0,0 +1,152 @@
+# Bankroll
+
+Bankroll is a set of financial calculations for mortgages and loans.
+
+The goal of this library is to make time value of money calculations
+understandable and decomposed into well written functions.
+
+I find most financial math libraries to be somewhat opaque so hopefully
+this helps when learning how to calculate mortgages and other annuity based
+investments.
+
+Features:
+- Uses safe math with BigDecimal through the Bankroll::Decimal api
+- Handles only ordinary annuities (annuities due at the END of the period)
+- Implements most excel functions using some inspiration from Exonio gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bankroll'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install bankroll
+
+## Usage
+
+```ruby
+
+# What is the monthly payment?
+payment = Bankroll.payment(
+  periods: 360, 
+  interest_rate: 0.01 / 12.0,
+  present_value: 1_000_000
+).round
+puts payment #=> Bankroll::Decimal["3_216.40"]
+
+# What was the original loan amount?
+original_amount = Bankroll.present_value(
+  periods: 360, # 30 years
+  monthly_payment: 3_216.40, 
+  interest_rate: 0.01 / 12.0, # 2.5%
+).round
+puts original_amount #=> Bankroll::Decimal["1_000_001.49"]
+
+# What does the balance look like after a single mortgage payment?
+unpaid_balance = Bankroll.unpaid_balance(
+  present_value: 1_000_000,
+  interest_rate: 0.01 / 12.0,
+  periods: 360,
+  period: 1,
+  payment: 3_216.40
+).round
+puts unpaid_balance #=> Bankroll::Decimal["997_616.94"]
+
+# What was the interest rate?
+interest_rate = Bankroll.interest_rate(
+  present_value: 1_000_000,
+  periods: 360,
+  payment: -3_216.40,
+).round(3)
+puts interest_rate #=> Bankroll::Decimal["0.833e-3"]
+
+# What is the annuity factor of a rate for n periods?
+annuity_factor = Bankroll.annuity_factor(
+  interest_rate: 0.01,
+  periods: 2
+).round(4)
+puts annuity_factor #=> Bankroll::Decimal["1.9704"]
+
+# What is the total interest paid on a 500_000 1% mortgage
+interest_paid = Bankroll.cumulative_interest(
+  periods: 360,
+  interest_rate: 0.01 / 12.0,
+  payment: 1_608.20,
+  present_value: 500_000
+).round
+puts interest_paid #=> Bankroll::Decimal["832.34"]
+
+# What is the total cost of a 500_000 1% loan with interest?
+total_amount = Bankroll.future_value(
+  present_value: 0,
+  interest_rate: 0.01 / 12.0,
+  periods: 360,
+  payment: 1_608.20
+).round
+puts total_amount #=> Bankroll::Decimal["647_846.10"]
+
+# What is the interest payment on the 17th period of a $165,000 3% mortgage?
+interest_payment = Bankroll.interest_payment(
+  interest_rate: 0.03 / 12.0,
+  periods: 360,
+  period: 17,
+  present_value: 165_000
+).round
+puts interest_payment #=> Bankroll::Decimal["400.96"]
+
+# How many periods until a -$1000 account with -$100/month reaches $10_000 with
+# 12% interest rate?
+total_periods = Bankroll.total_periods(
+  interest_rate: 0.12 / 12.0,
+  payment: -100,
+  present_value: -1_000,
+  future_value: 10_000
+)
+puts total_periods #=> Bankroll::Decimal["59.67"]
+
+# What is the amortization schedule of a $165_000 3% 30 year mortgage?
+amortization_schedule = Bankroll.amortization_schedule(
+  present_value: 165_000,
+  interest_rate: 0.03 / 12.0,
+  periods: 360
+)
+puts amortization_schedule.payments #=> [
+#   Bankroll::AmortizationSchedule::Payment.new(
+#     payment: Bankroll::Decimal["695.65"],
+#     principal: Bankroll::Decimal["283.15"],
+#     interest: Bankroll::Decimal["412.50"],
+#     total_interest: Bankroll::Decimal["412.50"],
+#     balance: Bankroll::Decimal["164_716.85"]
+#   )
+#   ... and 359 more payments
+# ]
+
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 
+Then, run `rake spec` to run the tests. You can also run `bin/console` for an 
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. 
+To release a new version, update the version number in `version.rb`, and then 
+run `bundle exec rake release`, which will create a git tag for the version, 
+push git commits and the created tag, and push the `.gem` file 
+to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nolantait/bankroll.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bankroll.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/bankroll/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bankroll"
+  spec.version = Bankroll::VERSION
+  spec.authors = ["Nolan J Tait"]
+  spec.email = ["nolanjtait@gmail.com"]
+
+  spec.summary = "Mortgage and refinance calculations for ruby"
+  spec.description = "Mortgage and refinance calculations for ruby"
+  spec.homepage = "https://github.com/nolantait/bankroll"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/nolantait/bankroll"
+  spec.metadata["changelog_uri"] = "https://github.com/nolantait/bankroll/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "dry-types"
+  spec.add_dependency "dry-initializer"
+  spec.add_dependency "dry-equalizer"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/bin/bundle

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+  module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_requirement
+    @bundler_requirement ||=
+      env_var_version || cli_arg_version ||
+        bundler_requirement_for(lockfile_version)
+  end
+
+  def bundler_requirement_for(version)
+    return "#{Gem::Requirement.default}.a" unless version
+
+    bundler_gem_version = Gem::Version.new(version)
+
+    requirement = bundler_gem_version.approximate_recommendation
+
+    return requirement unless Gem::Version.new(Gem::VERSION) < Gem::Version.new("2.7.0")
+
+    requirement += ".a" if bundler_gem_version.prerelease?
+
+    requirement
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    activate_bundler
+  end
+
+  def activate_bundler
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_requirement
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "bankroll"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/bankroll/amortization_schedule.rb

@@ -0,0 +1,69 @@
+module Bankroll
+  class AmortizationSchedule
+    extend Dry::Initializer
+    extend Callable
+
+    Payment = Struct.new(
+      :payment,
+      :principal,
+      :interest,
+      :total_interest,
+      :balance,
+      keyword_init: true
+    )
+
+    option :present_value, Types["bankroll.decimal"]
+    option :interest_rate, Types["bankroll.decimal"]
+    option :periods, Types["integer"]
+
+    def each
+      Enumerator.new do |yielder|
+        total_interest = Decimal["0"]
+        balance = @present_value
+
+        periods.times do |period|
+          interest = interest_payment(period + 1)
+          principal = payment - interest
+          total_interest += interest
+          balance -= principal
+
+          yielder << Payment.new(
+            payment: payment.round,
+            principal: principal.round,
+            interest: interest.round,
+            total_interest: total_interest.round,
+            balance: balance.round
+          )
+        end
+      end
+    end
+
+    def payments
+      @payments ||= each.to_a
+    end
+
+    def call
+      self
+    end
+
+    private
+
+    def interest_payment(period)
+      InterestPayment.call(
+        interest_rate: @interest_rate,
+        periods: @periods,
+        period: period,
+        present_value: @present_value,
+        payment: -payment
+      )
+    end
+
+    def payment
+      @payment ||= Bankroll::Payment.call(
+        present_value: @present_value,
+        interest_rate: @interest_rate,
+        periods: @periods
+      )
+    end
+  end
+end

data/lib/bankroll/annuity_factor.rb

@@ -0,0 +1,25 @@
+module Bankroll
+  class AnnuityFactor
+    extend Callable
+    extend Dry::Initializer
+
+    ONE = Decimal['1'].freeze
+
+    option :periods, Types["bankroll.decimal"]
+    option :interest_rate, Types["bankroll.decimal"]
+
+    def call
+      annuity_factor
+    end
+
+    private
+
+    def annuity_factor
+      (ONE - interest_contribution_per_period) / @interest_rate
+    end
+
+    def interest_contribution_per_period
+      (ONE + @interest_rate) ** -@periods
+    end
+  end
+end

data/lib/bankroll/callable.rb

@@ -0,0 +1,7 @@
+module Bankroll
+  module Callable
+    def call(**kwargs)
+      new(**kwargs).call
+    end
+  end
+end

data/lib/bankroll/cumulative_interest.rb

@@ -0,0 +1,36 @@
+module Bankroll
+  class CumulativeInterest
+    # Calculate the total interest paid at any period
+    #
+    extend Callable
+    extend Dry::Initializer
+
+    option :periods, Types["bankroll.decimal"]
+    option :payment, Types["bankroll.decimal"]
+    option :interest_rate, Types["bankroll.decimal"], default: -> { ZERO }
+    option :present_value, Types["bankroll.decimal"]
+
+    def call
+      payments_made + 
+        ((total_interest - @payment) * percentage_of_interest_per_period)
+    end
+
+    private
+
+    def percentage_of_interest_per_period
+      ((compound_rate - ONE) / @interest_rate)
+    end
+
+    def payments_made
+      @payment * @periods
+    end
+
+    def compound_rate
+      (ONE + @interest_rate) ** @periods
+    end
+
+    def total_interest
+      @present_value * @interest_rate
+    end
+  end
+end

data/lib/bankroll/decimal.rb

@@ -0,0 +1,59 @@
+module Bankroll
+  class Decimal < Delegator
+    include Dry::Equalizer.new(:value)
+
+    ROUNDING = :half_even
+
+    def self.[](value)
+      if value.is_a? self
+        value
+      else
+        new(value.to_s)
+      end
+    end
+
+    attr_reader :value
+    alias_method :__getobj__, :value
+
+    def initialize(value)
+      decimal = case value
+      when self.class
+        value.value.to_s
+      else
+        value.to_s
+      end
+
+      @value = BigDecimal(Types["string"][decimal])
+    end
+
+    def round(precision = 2, rounding = ROUNDING)
+      wrap @value.round(precision, rounding)
+    end
+
+    def +(other)
+      wrap super(Decimal[other].value)
+    end
+
+    def -(other)
+      wrap super(Decimal[other].value)
+    end
+
+    def *(other)
+      wrap super(Decimal[other].value)
+    end
+
+    def /(other)
+      wrap super(Decimal[other].value)
+    end
+
+    def **(other)
+      wrap super(Decimal[other].value)
+    end
+
+    private
+
+    def wrap(value)
+      Decimal[value]
+    end
+  end
+end

data/lib/bankroll/future_value.rb

@@ -0,0 +1,25 @@
+module Bankroll
+  class FutureValue
+    # Future value is the value to which an investment will grow 
+    # after one or more periods. Usage is with a fixed payment 
+
+    extend Callable
+    extend Dry::Initializer
+
+    option :periods, Types["bankroll.decimal"]
+    option :interest_rate, Types["bankroll.decimal"]
+    option :payment, Types["bankroll.decimal"], default: -> { ZERO }
+    option :present_value, Types["bankroll.decimal"], default: -> { ZERO }
+
+    def call
+      (effective_rate * present_value) +
+        (@payment * (1 + @interest_rate * 0) * (effective_rate - 1) / @interest_rate)
+    end
+
+    private
+
+    def effective_rate
+      (ONE + @interest_rate) ** @periods
+    end
+  end
+end

data/lib/bankroll/interest_payment.rb

@@ -0,0 +1,37 @@
+module Bankroll
+  class InterestPayment
+    # The interest portion of a payment at period N
+
+    extend Callable
+    extend Dry::Initializer
+
+    option :interest_rate, Types["bankroll.decimal"]
+    option :periods, Types["bankroll.decimal"]
+    option :period, Types["integer"]
+    option :present_value, Types["bankroll.decimal"]
+    option :payment, Types["bankroll.decimal"] | Types["nil"], default: -> { nil }
+
+    def call
+      future_loan_balance * @interest_rate
+    end
+
+    private
+
+    def future_loan_balance
+      FutureValue.call(
+        periods: @period - 1,
+        payment: payment,
+        present_value: @present_value,
+        interest_rate: @interest_rate
+      )
+    end
+
+    def payment
+      @payment ||= -Payment.call(
+        present_value: @present_value,
+        interest_rate: @interest_rate,
+        periods: @periods
+      )
+    end
+  end
+end

data/lib/bankroll/interest_rate.rb

@@ -0,0 +1,47 @@
+module Bankroll
+  class InterestRate
+    extend Dry::Initializer
+    extend Callable
+
+    # Uses the method in the Exonio library:
+    # https://github.com/noverde/exonio/blob/master/lib/exonio/financial.rb
+
+    option :periods, Types["integer"]
+    option :payment, Types["bankroll.decimal"]
+    option :present_value, Types["bankroll.decimal"]
+    option :future_value, Types["bankroll.decimal"], default: -> { Decimal[0] }
+
+    def call(guess = 0.1)
+      significance_required = 1e-6
+      stop = false
+
+      begin
+        temp = newton_iteration(
+          guess,
+          @periods,
+          @payment,
+          @present_value,
+          @future_value,
+          0
+        )
+        next_guess = (guess - temp).round(20)
+        difference = (next_guess - guess).abs
+        stop = difference < significance_required
+        guess = next_guess
+      end while !stop
+
+      next_guess
+    end
+
+    private
+
+
+    # This method was borrowed from the NumPy rate formula
+    # which was generated by Sage
+    def newton_iteration(r, n, p, x, y, w)
+      t1 = (r+1)**n
+      t2 = (r+1)**(n-1)
+      ((y + t1*x + p*(t1 - 1)*(r*w + 1)/r) / (n*t2*x - p*(t1 - 1)*(r*w + 1)/(r**2) + n*p*t2*(r*w + 1)/r + p*(t1 - 1)*w/r))
+    end
+  end
+end