mudrat_projector 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 27f998c4d27ead6cc375a7fb9fbde9d41851189e
+  data.tar.gz: 91a01f95d654f29d459cbc94698fb0bb75997ecf
+SHA512:
+  metadata.gz: 4c8fcab59b9a618c9b9415010703ab4d1d2c8d8a13b9a221fc3eaa26d04680612b948f2588f39cc2431a33ef1f500b169fe555731a8755a7e479415e241fc1ed
+  data.tar.gz: fd954a625bd5d802c9563044a11360d4dba16e1a14e81f4d8250816bb95b577a554dbec765beed4f7e7e20e4422b76bae2218f9293a9788a96b2e75be0874838

data/.gitignore

@@ -0,0 +1,2 @@
+tags
+tmp

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p353

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0-p353

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mudrat_projector.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    mudrat_projector (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.4.3)
+    builder (3.2.2)
+    coderay (1.1.0)
+    docile (1.1.1)
+    hashie (2.0.5)
+    method_source (0.8.2)
+    minitest (5.0.8)
+    minitest-reporters (1.0.0)
+      ansi
+      builder
+      minitest (>= 5.0)
+      powerbar
+    multi_json (1.8.2)
+    powerbar (1.0.11)
+      ansi (~> 1.4.0)
+      hashie (>= 1.1.0)
+    pry (0.9.12.4)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rake (10.1.0)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    slop (3.4.7)
+    timecop (0.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  minitest
+  minitest-reporters
+  mudrat_projector!
+  pry
+  rake
+  simplecov
+  timecop

data/README.md

@@ -0,0 +1,46 @@
+[![Build Status](https://api.travis-ci.org/ntl/mudrat-projector.png)](https://travis-ci.org/ntl/mudrat-projector)
+
+# MudratProjector
+
+Simple financial projection built in ruby.
+
+```ruby
+include MudratProjector
+
+projector = Projector.new from: "1/1/2000"
+projector.add_account :checking, type: :asset
+projector.add_account :uncle_vinnie, type: :revenue
+projector.add_transaction(
+  date: "7/4/2000",
+  debit:  { amount: 6000, account_id: :checking },
+  credit: { amount: 6000, account_id: :uncle_vinnie }
+)
+projector.project to: "12/31/2000"
+assert_equal 5000, projector.account_balance(:checking)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mudrat_projector'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mudrat_projector
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,26 @@
+require "rake/testtask"
+
+ENV['COVERAGE'] = '1'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs << 'test'
+end
+
+desc "Update ctags"
+task :ctags do
+  `ctags -R --languages=Ruby --totals -f tags`
+end
+
+task :environment do
+  $LOAD_PATH.push File.expand_path('../lib', __FILE__)
+  require 'mudrat_projector'
+end
+
+desc "Open a pry console"
+task :console => :environment do
+  require 'pry'
+  MudratProjector.pry
+end
+
+task default: :test

data/bin/testrb

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+ruby -Ilib -Itest $@

data/finance_fu.txt

@@ -0,0 +1,41 @@
+
+
+
+
+
+
+
+
+
+      Scenario
+
+        Income
+          Self employed
+          Salaried
+        Expenses
+          Recurring
+          One time
+        Liabilities
+          Mortgage, student loan debt, etc.
+        Investments
+          Property
+          Stock
+          Mutual funds, etc.
+
+
+
+      Bank/Financial transaction history
+
+        Can reconcile against active scenario
+
+
+
+      Projection
+
+        Creates ledgers using bank transaction history when available, active scenario on fallback
+        Changes to active scenario immediately propogate to projection
+        Calculates taxes and adjusts for inflation
+        When scenario changes, we store 1 year, 2 year, 5 year, etc.
+
+
+

data/lib/mudrat_projector/account.rb

@@ -0,0 +1,75 @@
+module MudratProjector
+  class Account
+    TYPES = %i(asset expense liability revenue equity)
+
+    attr :open_date, :parent_id, :tags, :type
+
+    def initialize params = {}
+      @entries         = []
+      @open_date       = params[:open_date] || ABSOLUTE_START
+      @offset          = 0
+      @opening_balance = params[:opening_balance] || 0
+      @parent_id       = params[:parent_id] || nil
+      @tags            = params[:tags] || []
+      @type            = params.fetch :type
+    end
+
+    def add_entry entry
+      @entries.push entry
+      @offset += entry.delta
+    end
+
+    def balance
+      @opening_balance + @offset
+    end
+
+    def close!
+      freeze
+      return self if closed?
+      self.class.new serialize
+    end
+
+    def closed?
+      @entries.empty?
+    end
+
+    def create_child params = {}
+      new_params = serialize
+      new_params.merge!(
+        opening_balance: params[:opening_balance],
+        parent_id: params.fetch(:parent_id),
+        tags: (tags | Array(params[:tags])),
+      )
+      self.class.new new_params
+    end
+
+    def parent?
+      parent_id.nil? ? false : true
+    end
+
+    def tag? tag_name
+      tags.include? tag_name
+    end
+
+    def serialize
+      hash = { opening_balance: balance }
+      %i(open_date parent_id tags type).each do |attr|
+        value = public_send attr
+        unless default_value? attr, value
+          hash[attr] = value unless Array(value).empty?
+        end
+      end
+      hash
+    end
+
+    private
+
+    def default_value? attr, value
+      if attr == :open_date
+        value == ABSOLUTE_START
+      else
+        false
+      end
+    end
+  end
+end

data/lib/mudrat_projector/amortizer.rb

@@ -0,0 +1,103 @@
+module MudratProjector
+  class Amortizer
+    attr :balance, :projection_range
+  end
+
+  class CompoundInterestAmortizer < Amortizer
+    attr :schedule
+
+    def initialize schedule, projection_range, **params
+      @schedule         = schedule
+      @projection_range = projection_range
+      @balance, @interest, @principal = amortize
+    end
+
+    def amortize
+      balance  = initial_value * ((1 + rate) ** months_amortized)
+      interest = balance - initial_value
+      [balance, interest, 0]
+    end
+
+    def each_entry &block
+      [[:credit, interest,  schedule.interest_account ],
+       [:credit, principal, schedule.principal_account],
+       [:debit,  payment,   schedule.payment_account  ]].each &block
+    end
+
+    def initial_value
+      schedule.initial_value
+    end
+
+    def interest
+      @interest.round 2
+    end
+
+    def months_amortized
+      start  = [projection_range.begin, schedule_range.begin].max
+      finish = [projection_range.end,   schedule_range.end].min
+      DateDiff.date_diff(:month, start, finish).to_i
+    end
+
+    def next_transaction transaction, schedule
+      Transaction.new(
+        date:     projection_range.end + 1,
+        credits:  transaction.credits,
+        debits:   transaction.debits,
+        schedule: schedule,
+      )
+    end
+
+    def rate
+      schedule.rate
+    end
+
+    def principal
+      @principal.round 2
+    end
+
+    def payment
+      interest + principal
+    end
+
+    def schedule_range
+      schedule.range
+    end
+  end
+
+  class MortgageAmortizer < CompoundInterestAmortizer
+    attr :extra_principal, :monthly_payment
+
+    def initialize *args, extra_principal: 0
+      @extra_principal = extra_principal
+      super
+    end
+
+    def monthly_payment
+      schedule.monthly_payment
+    end
+
+    def each_entry &block
+      [[:credit, interest,  schedule.payment_account  ],
+       [:credit, principal, schedule.payment_account  ],
+       [:debit,  interest,  schedule.interest_account ],
+       [:debit,  principal, schedule.principal_account]].each &block
+    end
+
+    def amortize
+      interest_paid  = 0
+      principal_paid = 0
+      
+      mp = monthly_payment
+
+      new_balance = months_amortized.times.inject initial_value do |balance, _|
+        interest    = balance * rate
+        principal   = (mp - interest) + extra_principal
+        interest_paid  += interest
+        principal_paid += principal
+        balance - principal
+      end
+      
+      [new_balance, interest_paid, principal_paid]
+    end
+  end
+end

data/lib/mudrat_projector/banker_rounding.rb

@@ -0,0 +1,11 @@
+module MudratProjector
+  module BankerRounding
+    def with_banker_rounding
+      old_rounding_mode = BigDecimal.mode BigDecimal::ROUND_MODE
+      BigDecimal.mode BigDecimal::ROUND_MODE, BigDecimal::ROUND_HALF_EVEN
+      yield
+    ensure
+      BigDecimal.mode BigDecimal::ROUND_MODE, old_rounding_mode
+    end
+  end
+end

data/lib/mudrat_projector/chart_of_accounts.rb

@@ -0,0 +1,119 @@
+module MudratProjector
+  class ChartOfAccounts
+    include Enumerable
+
+    def initialize
+      @accounts = {}
+    end
+
+    def account_balance id
+      fetch(id).balance + subaccounts_balance(id)
+    end
+
+    def accounts
+      @accounts.keys
+    end
+
+    def add_account id, **params
+      @accounts[id] = Account.new params
+    end
+
+    def apply_transaction transaction
+      validate_transaction! transaction
+      transaction.entries.each do |entry| entry.calculate self; end
+      transaction.entries.each do |entry|
+        fetch(entry.account_id).add_entry entry
+      end
+      transaction
+    end
+
+    def balance
+      inject 0 do |sum, account|
+        if account.parent?
+          sum
+        else
+          method = %i(asset expense).include?(account.type) ? :+ : :-
+          sum.public_send method, account.balance
+        end
+      end
+    end
+
+    def each &block
+      @accounts.values.each &block
+    end
+
+    def exists? account_id
+      @accounts.has_key? account_id
+    end
+
+    def fetch account_id
+      @accounts.fetch account_id
+    end
+
+    def net_worth
+      @accounts.reduce 0 do |sum, (_, account)|
+        if account.type == :asset
+          sum + account.balance
+        elsif account.type == :liability
+          sum - account.balance
+        else
+          sum
+        end
+      end
+    end
+
+    def size
+      @accounts.size
+    end
+
+    def serialize
+      @accounts.reduce Hash.new do |hash, (id, account)|
+        hash[id] = account.serialize
+        hash
+      end
+    end
+
+    def split_account id, into: {}
+      parent = fetch id
+      into.map do |sub_account_id, hash|
+        @accounts[sub_account_id] = 
+          if hash
+            parent.create_child(
+              opening_balance: hash[:amount],
+              parent_id: id,
+              tags: hash[:tags],
+            )
+          else
+            parent.create_child parent_id: id
+          end
+      end
+    end
+
+    def subaccounts_balance id
+      subaccount_ids = @accounts.reduce [] do |ary, (subaccount_id, account)|
+        ary.push subaccount_id if account.parent_id == id
+        ary
+      end
+      subaccount_ids.reduce 0 do |sum, id| sum + account_balance(id); end
+    end
+
+    def validate_transaction! transaction
+      transaction.each do |entry|
+        validate_entry! transaction.date, entry
+      end
+    end
+
+    def validate_entry! transaction_date, entry
+      unless @accounts.has_key? entry.account_id
+        raise Projector::AccountDoesNotExist, "Transaction references non "\
+          "existent account #{entry.account_id.inspect}"
+      end
+      open_date = fetch(entry.account_id).open_date
+      unless open_date <= transaction_date
+        raise Projector::AccountDoesNotExist, "Transaction references account "\
+          "#{entry.account_id.inspect} which does not open until #{open_date}, "\
+          "but transaction is set for #{transaction_date}"
+      end
+    end
+  end
+end

data/lib/mudrat_projector/date_diff.rb

@@ -0,0 +1,169 @@
+module MudratProjector
+  module DateDiff
+    extend self
+
+    def advance intervals: nil, unit: nil, from: nil
+      fetch_subclass(unit).advance intervals, from: from
+    end
+
+    def date_diff *maybe_unit_from_to, unit: nil, from: nil, to: nil
+      if [unit, from, to].all? &:nil?
+        unit, from, to = maybe_unit_from_to
+      end
+      fetch_subclass(unit).new(from, to).calculate
+    end
+
+    def fetch_subclass unit
+      klass_bit = unit.to_s.capitalize.gsub(/_[a-z]/) do |dash_letter| 
+        dash_letter[1].upcase
+      end
+      klass_name = "#{klass_bit}Calculator"
+      DateDiff.const_get klass_name
+    end
+    private :fetch_subclass
+
+    Calculator = Struct.new :from, :to do
+      def calculate
+        fail
+      end
+
+      def days_between
+        (to - from).to_f + 1
+      end
+      private :days_between
+    end
+
+    class DayCalculator < Calculator
+      def calculate
+        days_between
+      end
+      
+      def self.advance intervals, from: from
+        from + intervals.round
+      end
+    end
+
+    class WeekCalculator < DayCalculator
+      def calculate
+        super / 7.0
+      end
+
+      def self.advance intervals, from: from
+        from + (intervals * 7)
+      end
+    end
+
+    class ComplexCalculator < Calculator
+      attr :first_unit, :last_unit
+
+      def initialize *args
+        super
+        @first_unit = fetch_unit from
+        @last_unit  = fetch_unit to
+      end
+
+      def calculate
+        if first_unit.begin == last_unit.begin
+          days_between / days_in_unit(first_unit)
+        else
+          calculate_unit(from, first_unit.end) +
+            units_between +
+            calculate_unit(last_unit.begin, to)
+        end
+      end
+
+      private
+
+      def calculate_unit unit_begin, unit_end
+        self.class.new(unit_begin, unit_end).calculate
+      end
+
+      def calculate_units_between start, finish
+        count = 1
+        until start == finish
+          count += 1
+          start = advance_one_unit start
+        end
+        count
+      end
+
+      def days_in_unit unit
+        ((unit.end + 1) - unit.begin).to_f
+      end
+
+      def units_between
+        start = first_unit.end + 1
+        finish = rewind_one_unit last_unit.begin
+        return 0 if start > finish
+        calculate_units_between start, finish
+      end
+    end
+
+    class YearCalculator < ComplexCalculator
+      def fetch_unit date
+        (Date.new(date.year)..Date.new(date.year, 12, 31))
+      end
+
+      def advance_one_unit date
+        date.next_year
+      end
+
+      def rewind_one_unit date
+        date.prev_year
+      end
+
+      def self.advance intervals, from: from
+        Date.new(from.year + intervals, from.month, from.day)
+      end
+    end
+
+    class QuarterCalculator < ComplexCalculator
+      def fetch_unit date
+        [1, 4, 7, 10].each do |quarter|
+          if (quarter..quarter + 2).include? date.month
+            start_of_quarter = Date.new(date.year, quarter)
+            return (start_of_quarter..(start_of_quarter.next_month.next_month.next_month - 1))
+          end
+        end
+        fail "Date month was #{date.month}"
+      end
+
+      def advance_one_unit date
+        date.next_month.next_month.next_month
+      end
+
+      def rewind_one_unit date
+        date.prev_month.prev_month.prev_month
+      end
+
+      def self.advance intervals, from: from
+        (intervals * 3).times.inject from do |date, _| date.next_month; end
+      end
+    end
+
+    class MonthCalculator < ComplexCalculator
+      def fetch_unit date
+        start_of_month = Date.new(date.year, date.month)
+        (start_of_month..(start_of_month.next_month - 1))
+      end
+
+      def advance_one_unit date
+        date.next_month
+      end
+
+      def rewind_one_unit date
+        date.prev_month
+      end
+
+      def self.advance intervals, from: from
+        if intervals < 1
+          days_in_month = Date.new(from.year, from.month, -1).day
+          days = intervals * days_in_month
+          DayCalculator.advance days, from: from
+        else
+          intervals.times.inject from do |date, _| date.next_month; end
+        end
+      end
+    end
+  end
+end