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:

gem 'bankroll'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install bankroll

Usage

# 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, # 1% APR
).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.

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.