apy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d474dde3f7bb520eda50aecd1015bfe779a4da3e959b6fa81927c70bb4483e3
+  data.tar.gz: bdeff0d880df581d65eaa374b07467ca5e0faee4726691d65f485cf8b44c8b0d
+SHA512:
+  metadata.gz: 36c2b40cb28cb2fc0d92db3a808167d3922b249e943f0f8616bdc6b3c69a2584f3b9b749a56c66175715ec283d9056e3ed1819f90fc9f7b7d0d9f3fa85191e1c
+  data.tar.gz: d47c2cea41c2c964b5b13e9b748f5b02b1c1d8f9a702aa031f6e63858f98e59f43e25119ab0b151167674542673f29a23089692bea5d27561fdfffabf2414719

data/.github/workflows/main.yml

@@ -0,0 +1,18 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.0.1
+    - name: Run the default task
+      run: |
+        gem install bundler -v 2.2.15
+        bundle install
+        bundle exec rake

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# Ignore lockfile to catch dependency issues
+/Gemfile.lock
+
+# Development console always looks messy
+bin/console

data/CHANGELOG

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.0.1] - 2021-05-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in apy.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Trevor James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,121 @@
+# Apy
+
+Various helpers for calculating interest
+
+## TODO
+- [ ] Amortization
+- [ ] Update method signatures to only use day counts
+- [ ] Comprehensive examples w/ tests
+- [ ] Setup ci
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "apy"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install apy
+
+## Usage
+
+- [As a module](#as-a-module)
+  - [Method: `weighted_harmonic_mean`](#weighted-harmonic-mean)
+  - [Method: `compound`](#compound)
+- [Interest class](#interest)
+- [Loan class](#loan)
+
+
+### As a Module
+`Apy::Calculable` is the base module with the most exposed utility. Simply include it in a class which needs the functionality.
+
+#### `weighted_harmonic_mean`
+[Link](https://www.investopedia.com/terms/h/harmonicaverage.asp#mntl-sc-block_1-0-9)
+
+Given a series of invested amounts, this can be used to effectively calculate the average share price, or DCA (dollar cost average) price of a position.
+
+Given the following:
+| Amount invested | Share price |
+| --- | --- |
+| 1000 | 156.23 |
+| 1000 | 156.30 |
+| 1000 | 173.15 |
+| 1000 | 188.72 |
+| 1000 | 204.61 |
+| 1000 | 178.23 |
+
+Investing a total of 6000 with the above share prices results in `174.57` for the average price paid per share.
+
+Given the following:
+| Amount invested | Share price |
+| --- | --- |
+| 500 | 200.00 |
+| 1000 | 100.00 |
+
+Investing a total of 1500 with the above share prices results in `100.00` for the average price paid per share.
+
+The module method accepts a matrix, with each array in the set having the following signature `[invested_amount, share_price]`:
+```ruby
+dca = [
+  [1000, 156.23],
+  [1000, 156.30],
+  [1000, 173.15],
+  [1000, 188.72],
+  [1000, 204.61],
+  [1000, 178.23]
+]
+weighted_harmonic_mean(dca) == 174.5655590168175
+```
+
+#### `compound`
+[Link](https://www.thecalculatorsite.com/articles/finance/compound-interest-formula.php)
+
+Simple compound interest formula. Variable names correspond to the following:
+- `principal` The base amount before interest
+- `rate` The expected interest rate
+- `times` The number of times interest is calculated per term
+- `terms` The number of terms to allow the principal accrue interest
+
+Example: 1200@10% over 1y, interest paid monthly
+```ruby
+compound(1200, rate: 0.1, times: 12, terms: 1) == 1325.66
+```
+
+#### `dca_compound`
+A variant of `#compound`, wherein an amount is continually invested at varying interest rates. Similar to `weighted_harmonic_mean`, this method also accepts a matrix. The size of the matrix corresponds to the number of `terms` all funds will accrue.
+
+Example: 1200@10% over 2y, interest paid monthly
+```ruby
+dca = [
+  [1200, 0.1],
+  [1200, 0.1]
+]
+dca_compound(dca, times: 12) == 2790.125
+```
+
+### Interest
+todo
+
+### Loan
+todo
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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/fire-pls/apy.
+
+## 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 "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/apy.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/apy/version"
+require "date"
+
+Gem::Specification.new do |gemspec|
+  gemspec.name = "apy"
+  gemspec.version = Apy::VERSION
+  gemspec.authors = ["Trevor James"]
+  gemspec.email = ["trevor@osrs-stat.com"]
+
+  gemspec.summary = "Interest calculators"
+  gemspec.description = "Helpers for calculating various interest scenarios"
+  gemspec.homepage = "https://github.com/fire-pls/apy"
+  gemspec.license = "MIT"
+  gemspec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  gemspec.metadata["homepage_uri"] = gemspec.homepage
+  gemspec.metadata["source_code_uri"] = gemspec.homepage
+  gemspec.metadata["changelog_uri"] = [gemspec.homepage, "CHANGELOG"].join("/")
+
+  # 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.
+  gemspec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  gemspec.bindir = "exe"
+  gemspec.executables = gemspec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  gemspec.require_paths = ["lib"]
+
+  # Dependencies
+  # None :)
+
+  # Dev Dependencies
+  gemspec.add_development_dependency "pry-byebug", "~> 3.9"
+  gemspec.add_development_dependency "rake", "~> 13"
+  gemspec.add_development_dependency "minitest", "~> 5.0"
+  gemspec.add_development_dependency "standard", "~> 1"
+end

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/apy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "apy/calculable"
+require_relative "apy/interest"
+require_relative "apy/loan"
+require_relative "apy/version"
+
+module Apy
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/apy/calculable.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Apy
+  module Calculable
+    # Calculate the weighted harmonic mean for a set of values
+    # (∑w) / (∑w/i)
+    # @param matrix [Array<Array<(Numeric, Numeric)>>] Matrix whose size is the number of investments, with the following array elements: idx0 invested amount, idx1 purchase price of the asset
+    # @todo Can make this a bit more performant with `inject`
+    # @example Providing a set of DCA values
+    #   dca = [[1000,156.23],[1000,156.3], [1000,173.15],[1000,188.72], [1000,204.61],[1000,178.23]]
+    #   weighted_harmonic_mean(dca)
+    #   # => 174.5655590168175
+    def weighted_harmonic_mean(matrix)
+      sum = matrix.sum { |(n, _)| n }.to_f
+
+      total_weight = []
+      weighted_values = []
+
+      matrix.each do |(investment, price)|
+        weight = investment / sum
+
+        total_weight << weight
+        weighted_values << (weight / price)
+      end
+
+      total_weight.sum / weighted_values.sum
+    end
+
+    # Simple compound, assuming no additional investment over successive maturity terms
+    # @param principal [Numeric] Initial investment
+    # @param rate [Float] Expected interest rate for the length of the period
+    # @param times [Integer] Times the interest will be paid out per term
+    # @param terms [Integer] Number of terms
+    #
+    # @example Given a "10% APY", with interest paid monthly (1y maturity date):
+    #   compound(1200, rate: 0.1, times: 12, terms: 1) == 1325.66
+    #
+    # @example Given a "0.1923% WPY", with interest paid weekly (1w maturity date):
+    #   compound(1200, rate: 0.1, times: 52, terms: 1) == 1326.07
+    #   compound(1200, rate: 0.001923, times: 1, terms: 52) == 1326.07
+    #
+    # @example Given a "0.0274% DPY", with interest paid daily (1d maturity date):
+    #   compound(1200, rate: 0.1, times: 365, terms: 1) == 1326.19
+    #   compound(1200, rate: 0.000274, times: 1, terms: 365) == 1326.20
+    def compound(principal, rate:, times:, terms:)
+      total_rate = 1 + (rate / times)
+
+      principal * (total_rate**(times * terms))
+    end
+
+    # "DCA" compound, assuming a recurring investment continuously added to the principal amount, this new amount _additionally_ compounded for the next period
+    # @param matrix [Array<Array(Numeric, Numeric)>] Matrix whose size is the number of terms; Each array item has the following elements: idx0 additional investment, idx1 the expected rate for the term
+    # @param times [Integer] Times the interest will be paid out per term
+    # @example Continuously investing 1200 dollars a year into a contract with a "10% APY", interest paid out once a month
+    #   dca_compound([[1200, 0.1], [1200, 0.1]], times: 12) == 2790.125
+    #
+    # @todo Clean this up, there is most likely an optimized formula for this 🤨
+    # @see #compound
+    def dca_compound(matrix, times:)
+      result = matrix.each_with_object(
+        total: 0,
+        interest: 0,
+        data: {
+          0 => {
+            ytd: 0,
+            in: 0,
+            interest: 0
+          }
+        }
+      ).with_index do |(ary, out), i|
+        additional_investment, rate = ary
+        prev_ytd = out[:data][i][:ytd]
+
+        to_compound = prev_ytd + additional_investment
+
+        current = compound(to_compound, rate: rate, times: times, terms: 1)
+        interest_this_period = current - to_compound
+
+        out[:total] += additional_investment + interest_this_period
+        out[:interest] += interest_this_period
+        out[:data][i + 1] = {ytd: current, in: additional_investment, interest: interest_this_period}
+      end
+
+      result.fetch(:total)
+    end
+  end
+end

data/lib/apy/interest.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "calculable"
+
+module Apy
+  # An interest object; Given an apy & date range, prepares various methods to calculate with
+  class Interest
+    include Apy::Calculable
+
+    attr_reader :apy
+
+    # @param apy [Float] Annual/Average Percent Yield -- an expected pct return over the course of a _year_
+    # @param start_date [Date] The beginning of the interest period; Defaults to today
+    # @param end_date [Date] The end of the interest period; Defaults to 1y from today
+    # @param days_per_term [Integer] Days per compound interest term; Defaults to 365 days
+    #
+    # @example A 10% APY, intended to be used in calculations over 2y:
+    #   d1 = Date.parse "2020-01-01"
+    #   d2 = Date.parse "2022-01-01"
+    #   Interest.new(apy: 0.1, start_date: d1, end_date: d2)
+    # @example An interest object _yielding 10% over the course of 2y_:
+    #   d1 = Date.parse "2020-01-01"
+    #   d2 = Date.parse "2022-01-01"
+    #   Interest.new(apy: 0.1, start_date: d1, end_date: d2, days_per_term: 730)
+    # @example The above example, but instantiated with an apy of 5%:
+    #   d1 = Date.parse "2020-01-01"
+    #   d2 = Date.parse "2022-01-01"
+    #   Interest.new(apy: 0.05, start_date: d1, end_date: d2)
+    def initialize(apy:, start_date: Date.today, end_date: Date.today.next_year, days_per_term: 365)
+      fail(ArgumentError, "apy must be a positive Float") unless apy.positive? && apy.is_a?(Float)
+
+      @apy = apy
+      @terms = Interest.get_term_size(start_date, end_date, days_per_term)
+    end
+
+    class << self
+      # @param days_per_term [Integer] Number of days that pass before an entire term ends. Defaults to 365
+      # @return [Integer] The actual number of terms completed
+      def get_term_size(start_date, end_date, days_per_term)
+        ((end_date - start_date) / days_per_term).round
+      end
+    end
+
+    # Given a principal amount, return the ending balance
+    # @param principal [Numeric] Initial investment
+    # @param times [Integer] The number of times per term interest is accrued; Defaults to 1 (flat rate)
+    # @see Calculable#compound
+    def total(principal, times: 1)
+      compound(principal, rate: apy, times: times, terms: @terms)
+    end
+
+    # Given a series of investments, calculate the DCA return
+    # @param in_per_split [Numeric] Value of newly invested funds per term; Will be zipped with #apy & term size
+    # @param times [Integer] The number of times per term interest is accrued; Defaults to 1 (flat rate)
+    # @note This assumes you wish to maximize dca returns; the in_per_split is deposited before the interest is calculated
+    # @note If this method is too inflexible for your use case, you should use the {Calculable} module directly
+    # @see Calculable#dca_compound
+    # @example Investing 3.29 everyday for a year:
+    #   Apy::Interest.new(apy: 0.1).dca(3.29, times: 365) == 1263.12
+    # @example Investing 23.08 every week for a year:
+    #   Apy::Interest.new(apy: 0.1).dca(23.08, times: 52) == 1263.43
+    # @example Investing 100 every month for a year:
+    #   Apy::Interest.new(apy: 0.1).dca(23.08, times: 12) == 1267.29
+    # @example Investing 300 every quarter for a year:
+    #   Apy::Interest.new(apy: 0.1).dca(300, times: 4) == 1277.64
+    # @example Investing 600 semi-annualy for a year:
+    #   Apy::Interest.new(apy: 0.1).dca(600, times: 2) == 1292.66
+    def dca(in_per_split, times: 1)
+      split = @terms * times
+      adjusted_apy = apy / times
+      range = split.times.map { [in_per_split, adjusted_apy] }
+
+      dca_compound(range, times: times)
+    end
+  end
+end

data/lib/apy/loan.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "interest"
+
+module Apy
+  # A loan object; Provides helpers for calculating various debt-related scenarios
+  class Loan
+    attr_reader :borrow, :apy
+
+    # @param borrow [Numeric] Amount of money to be borrowed
+    # @param apy [Float] The interest rate of the borrowed money
+    def initialize(borrow, apy:)
+      fail(ArgumentError, "apy must be a positive Float") unless apy.positive? && apy.is_a?(Float)
+
+      @borrow = borrow
+      @apy = apy
+    end
+
+    # Based on the borrow amount, calculate the payment size required to pay off the principal and accrued interest
+    # @param start_date [Date] Date the loan will begin
+    # @param end_date [Date] Date the loan will be fully paid off
+    # @param times [Integer] The number of times per term interest is accrued; Defaults to 1 (flat rate)
+    # @param days_per_term [Integer] The number of days per interest term
+    # @param payments_per_term [Integer] The number of payments made towards the loan per term; Defaults to `times`
+    # @example Payment size for 1200, interest accrued once, repaid in 1 payment across 365 days:
+    #   d1 = Date.parse "2020-01-01"
+    #   d2 = Date.parse "2021-01-01"
+    #   Loan.new(1200, apy: 0.1).payment_size(start_date: d1, end_date: d2) == 1320.0
+    # @example Payment size for 1200, interest accrued once, repaid in 12 payments across 365 days:
+    #   Loan.new(1200, apy: 0.1).payment_size(start_date: d1, end_date: d2, payments_per_term: 12) == 110.0
+    # @example Payment size for 1200, interest accrued 12 times, repaid in 12 payments across 365 days:
+    #   Loan.new(1200, apy: 0.1).payment_size(start_date: d1, end_date: d2, times: 12) == 110.47
+    def payment_size(start_date:, end_date:, times: 1, days_per_term: 365, payments_per_term: times)
+      total_owed(
+        start_date: start_date,
+        end_date: end_date,
+        times: times,
+        days_per_term: days_per_term
+      ) / (payments_per_term * Interest.get_term_size(start_date, end_date, days_per_term))
+    end
+
+    # Get the total amount owed, based on the start & end date
+    # @param start_date [Date] Date the loan will begin
+    # @param end_date [Date] Date the loan will be fully paid off
+    # @param times [Integer] The number of times per term interest is accrued; Defaults to 1 (flat rate)
+    # @param days_per_term [Integer] The number of days per interest term
+    # @note Because the constructor accepts an APY for the year, an adjusted rate is used here based on days_per_term
+    # @see Interest#total
+    # @see #adjusted_apy
+    def total_owed(start_date:, end_date:, times: 1, days_per_term: 365)
+      Apy::Interest.new(
+        apy: adjusted_apy(days_per_term),
+        start_date: start_date,
+        end_date: end_date,
+        days_per_term: days_per_term
+      ).total(borrow, times: times)
+    end
+
+    # Similar to payment_size, except interest accrues based on the remaining debt
+    # @todo Finish this
+    # @todo Once finished, make #payment_size accept less args (lump-sum, _only_ accept payment count)
+    def amortized_payment_size(start_date:, end_date:, times: 1, days_per_term: 365, payments_per_term: times)
+      fail
+    end
+
+    # @todo Finish this
+    # @todo Once finished, make #total_owed accept less args (lump-sum, _only_ accept payment count)
+    def amortized_total_owed(start_date:, end_date:, times: 1, days_per_term: 365, payments_per_term: times)
+      fail
+    end
+
+    private
+
+    # `apy / (365 / days_per_term)`
+    def adjusted_apy(days_per_term)
+      apy / (365 / days_per_term)
+    end
+  end
+end

data/lib/apy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Apy
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: apy
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Trevor James
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: Helpers for calculating various interest scenarios
+email:
+- trevor@osrs-stat.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README
+- Rakefile
+- apy.gemspec
+- bin/setup
+- lib/apy.rb
+- lib/apy/calculable.rb
+- lib/apy/interest.rb
+- lib/apy/loan.rb
+- lib/apy/version.rb
+homepage: https://github.com/fire-pls/apy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fire-pls/apy
+  source_code_uri: https://github.com/fire-pls/apy
+  changelog_uri: https://github.com/fire-pls/apy/CHANGELOG
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: Interest calculators
+test_files: []