finance_rb 0.2.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07e154f5ba5d444fe1e2c782c39a3d21a79b9fd3d413fba6e7c5285fa5f07df4
-  data.tar.gz: bef7aea3a7f54df1fc69d05619e9416637c717ce7e8b4d3a211573fbfbf5a6df
+  metadata.gz: 0abc599e1b7158a3095f3b9ac1627c54a0a85a9808a9afcc915a98fadfaff42d
+  data.tar.gz: f4417a96a3226bf76574e37fcf4c7f7e2bba9a92ea6586f43087444f4ecc239a
 SHA512:
-  metadata.gz: bf67fafbda3defb85d73581d02b3dc00b26f83c6b03e4f35bd5c2d3a0ac661a823cd737d8055c54309b8a6d6feba8be7d03675b39ddb95b2e8f7ceaa94a7e472
-  data.tar.gz: 4f429be0368ac5e986c689fcd6afd146cec1676741d149ced828ae6d03e38e2d2e1ebdfeae88fce1d76de1a31c51a08fb0809577362f07f1de0e70e761bfa8b1
+  metadata.gz: fd17e47f2b8418ef8e1e1c7b24385bb6aff9f6d4342915a901f5590a4b3dc25c0d6154bf8af273bc377fa743e5104391ce05a67c80fbd93b9509f38bbf678ec4
+  data.tar.gz: 69ed50d7d91a8b416af2796ef0232dbf32bcae226e7cc71c174de163f4ddab4169af9f09952b7b5104367848b892fcafa971c737b50384bba8019dc0c71fa6bd

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [1.0.0] - 2021-05-01
+
+### Added
+* Implement `Finance::Loan#rate`
+
 ## [0.2.2] - 2021-05-01
 
 ### Added

data/README.md

@@ -17,11 +17,19 @@ which are as follows:
 | ppmt                         |   ✅   |   Computes principal payment for a loan|
 | nper                         |    ✅   |    Computes the number of periodic payments|
 | pv                           |    ✅  |   Computes the present value of a payment|
-| rate                         |     |    Computes the rate of interest per period|
+| rate                         |   ✅ |    Computes the rate of interest per period|
 | irr                          |    ✅    |    Computes the internal rate of return|
 | npv                          |  ✅   |   Computes the net present value of a series of cash flow|
 | mirr                         |    ✅    |    Computes the modified internal rate of return|
 
+
+Things to be done:
+
+1. Xirr
+2. More specs for edge cases
+3. Fee, currency protection and other cool stuff for advanced usage
+4. Better errors
+
 ## Installation
 
 finance_rb is available as a gem, to install it just install the gem:

data/lib/finance/calculations.rb

@@ -98,6 +98,7 @@ module Finance
 
       private
 
+      # @api private
       def correct_cashflows?(values)
         inflows, outflows = values.partition{ |i| i >= 0 }
         !(inflows.empty? || outflows.empty?)
@@ -105,6 +106,7 @@ module Finance
 
       # Base class for working with Newton's Method.
       # For more details, see Bigdecimal::Newton.
+      #
       # @api private
       class Function
         def initialize(values)

data/lib/finance/loan.rb

@@ -2,7 +2,7 @@
 
 module Finance
   class Loan
-    PAYMENT_TYPE_MAPPING = { end: 0, beginning: 1 }.freeze
+    PAYMENT_TYPE_MAPPING = { end: 0.0, beginning: 1.0 }.freeze
 
     # @return [Float] The amount of loan request (I.e. a present value)
     #   You can use #pv method to calculate value if param is not defined.
@@ -88,7 +88,7 @@ module Finance
     #
     #   Required Loan arguments: period, nominal_rate, duration, amount, future_value*
     #
-    # @return [Float] Interest payment for a loan.
+    # @return [Float] The interest payment for a loan.
     #
     # @example
     #   require 'finance_rb'
@@ -116,7 +116,7 @@ module Finance
     #
     #   Required Loan arguments: period, nominal_rate, duration, amount, future_value*
     #
-    # @return [Float] Principal payment for a loan under a given period.
+    # @return [Float] The principal payment for a loan under a given period.
     #
     # @example
     #   require 'finance_rb'
@@ -137,7 +137,7 @@ module Finance
     #
     #   Required Loan arguments: payment, nominal_rate, period, amount, future_value*
     #
-    # @return [Float] Number of periodic payments.
+    # @return [Float] The number of periodic payments.
     #
     # @example
     #   require 'finance_rb'
@@ -202,8 +202,59 @@ module Finance
       -(future_value + (payment.to_f * second_factor)) / factor
     end
 
+    # Rate computes the interest rate per period
+    #   by running Newton Rapson to find an approximate value.
+    #
+    # @return [Float] The interest rate.
+    #
+    # @param tolerance [Float] Required tolerance for the solution.
+    # @param initial_guess [Float] Starting guess for solving the rate of interest.
+    # @param iterations [Integer] Maximum iterations in finding the solution.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 10, amount: -3500, payment: 0, duration: 10, future_value: 10000).rate
+    #   #=> 0.11069085371426901
+    #
+    # @see http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt
+    # @see [WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May).
+    #   Open Document Format for Office Applications (OpenDocument)v1.2,
+    #   Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version,
+    #   Pre-Draft 12. Organization for the Advancement of Structured Information
+    #   Standards (OASIS). Billerica, MA, USA. [ODT Document].
+    def rate(tolerance: 1e-6, iterations: 100, initial_guess: 0.1)
+      next_iteration_rate = nil
+      current_iteration_rate = initial_guess
+
+      (0..iterations).each do |iteration|
+        next_iteration_rate = current_iteration_rate - rate_ratio(current_iteration_rate)
+        break if (next_iteration_rate - current_iteration_rate).abs <= tolerance
+        current_iteration_rate = next_iteration_rate
+      end
+
+      next_iteration_rate
+    end
+
     private
 
+    # rate_ratio computes the ratio
+    #   that is used to find a single value that sets the non-liner equation to zero.
+    #
+    # @api private
+    def rate_ratio(rate)
+      t1 = (rate+1.0) ** duration
+      t2 = (rate+1.0) ** (duration-1.0)
+      g = future_value + t1 * amount + payment * (t1 - 1.0) * (rate * ptype + 1.0) / rate
+      derivative_g = \
+        (duration * t2 * amount)
+          - (payment * (t1 - 1.0) * (rate * ptype + 1.0) / (rate ** 2.0))
+          + (duration * payment * t2 * (rate * ptype + 1.0) / rate)
+          + (payment * (t1 - 1.0) * ptype/rate)
+      
+      g / derivative_g
+    end
+
+    # @api private
     def initialize_payment_type(ptype)
       @ptype =
         if ptype.nil? || !PAYMENT_TYPE_MAPPING.keys.include?(ptype)
@@ -213,6 +264,7 @@ module Finance
         end
     end
 
+    # @api private
     def remaining_balance
       self.class.new(
         nominal_rate: nominal_rate.to_f, duration: period - 1.0,

data/lib/finance/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Finance
-  VERSION = "0.2.2"
+  VERSION = "1.0.0"
 end

data/spec/finance/loan_spec.rb

@@ -186,4 +186,15 @@ RSpec.describe Finance::Loan do
       end
     end
   end
+
+  describe '#rate' do
+    context 'with default arguments' do
+      it 'calculates correct rate value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 10, amount: -3500, payment: 0, duration: 10, future_value: 10000
+        )
+        expect(loan.rate).to eq(0.11069085371426901)
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finance_rb
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Vlad Dyachenko