finance_rb 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c8d72b54d7c7342331cf06086b5e5b1c5ec7c9fe9e3f60315fc78a94254885
-  data.tar.gz: a5ce132889634c03e72dc3c884e3549071867e3a297de2ab1a040c2627b876bd
+  metadata.gz: 0abc599e1b7158a3095f3b9ac1627c54a0a85a9808a9afcc915a98fadfaff42d
+  data.tar.gz: f4417a96a3226bf76574e37fcf4c7f7e2bba9a92ea6586f43087444f4ecc239a
 SHA512:
-  metadata.gz: 8938c6f7d84419716cc1ee728a372388f1956f9ab1be75c80bbbed70e744711a505aa252b19269c3655db04c1f73884280cf11cc1a483f2d4a24b64d231fbbcf
-  data.tar.gz: a75066c79654c3eb3812db62f5e59bd130c12b87de2229da69a3ad6ba82d116089e95807c3a204c9c93780c243cc21b92953d224c4c532a400c4e30e22986af1
+  metadata.gz: fd17e47f2b8418ef8e1e1c7b24385bb6aff9f6d4342915a901f5590a4b3dc25c0d6154bf8af273bc377fa743e5104391ce05a67c80fbd93b9509f38bbf678ec4
+  data.tar.gz: 69ed50d7d91a8b416af2796ef0232dbf32bcae226e7cc71c174de163f4ddab4169af9f09952b7b5104367848b892fcafa971c737b50384bba8019dc0c71fa6bd

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [1.0.0] - 2021-05-01
+
+### Added
+* Implement `Finance::Loan#rate`
+
+## [0.2.2] - 2021-05-01
+
+### Added
+* Implement `Finance::Loan#pv`
+
+## [0.2.1] - 2021-05-01
+
+### Added
+* Implement `Finance::Loan#nper`
+
+## [0.2.0] - 2021-04-30
+
+### Added
+* Implement `Finance::Loan#ppmt`
+
+### Changed
+* By default `Finance::Loan#pmt` returns negative values.
+
+## [0.1.2] - 2021-04-05
+
+### Added
+* Implement `Finance::Loan#ipmt`
+
 ## [0.1.1] - 2021-03-30
 
 ### Added

data/README.md

@@ -12,16 +12,24 @@ which are as follows:
 | numpy-financial function     | ruby native function ported?   | info|
 |:------------------------:    |:------------------:  | :------------------|
 | fv                           |   ✅    |   Computes the  future value|
-| ipmt                         |       |   Computes interest payment for a loan|
+| ipmt                         |   ✅   |   Computes interest payment for a loan|
 | pmt                          |  ✅    |   Computes the fixed periodic payment(principal + interest) made against a loan amount|
-| 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|
+| 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|
 | 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.
@@ -25,6 +25,7 @@ module Finance
 
     # @return [Float] The number of periods to be compounded for. (I.e. Nper())
     #   Defaults to 1.
+    #   You can use #nper method to calculate value if param is not defined.
     attr_accessor :duration
 
     # @return [Float] Future value.
@@ -36,6 +37,9 @@ module Finance
     #   You can use #pmt method to calculate value if param is not defined.
     attr_accessor :payment
 
+    # @return [Float] Period under consideration.
+    attr_accessor :period
+
     # Create a new Loan instance.
     def initialize(**options)
       initialize_payment_type(options[:ptype])
@@ -43,6 +47,7 @@ module Finance
       @duration      = options.fetch(:duration, 1).to_f
       @amount        = options.fetch(:amount, 0).to_f
       @future_value  = options.fetch(:future_value, 0).to_f
+      @period        = options[:period]
       @payment       = options[:payment]
       @monthly_rate  = @nominal_rate / 12
     end
@@ -76,7 +81,72 @@ module Finance
           (factor - 1) * (1 + monthly_rate * ptype) / monthly_rate
         end
 
-      (-future_value + amount * factor) / second_factor
+      -((future_value + amount * factor) / second_factor)
+    end
+
+    # IPmt computes interest payment for a loan under a given period.
+    #
+    #   Required Loan arguments: period, nominal_rate, duration, amount, future_value*
+    #
+    # @return [Float] The interest payment for a loan.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.0824, duration: 12, amount: 2500, period: 1).ipmt
+    #   #=> -17.166666666666668
+    #
+    # @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 ipmt
+      raise ArgumentError, 'no period given' if period.nil?
+
+      ipmt_val = remaining_balance * monthly_rate
+      if ptype == PAYMENT_TYPE_MAPPING[:beginning]
+        period == 1 ? 0.0 : (ipmt_val / 1 + monthly_rate)
+      else
+        ipmt_val
+      end
+    end
+
+    # PPmt computes principal payment for a loan under a given period.
+    #
+    #   Required Loan arguments: period, nominal_rate, duration, amount, future_value*
+    #
+    # @return [Float] The principal payment for a loan under a given period.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.0824, duration: 12, amount: 2500, period: 1).ppmt
+    #   #=> -200.58192368678277
+    #
+    # @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 ppmt
+      pmt - ipmt
+    end
+
+    # Nper computes the number of periodic payments.
+    #
+    #   Required Loan arguments: payment, nominal_rate, period, amount, future_value*
+    #
+    # @return [Float] The number of periodic payments.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.07, amount: 8000, payment: -150).nper
+    #   #=> 64.0733487706618586
+    def nper
+      z = payment * (1.0 + monthly_rate * ptype) / monthly_rate
+
+      Math.log(-future_value + z / (amount + z)) / Math.log(1.0 + monthly_rate)
     end
 
     # Fv computes future value at the end of some periods (duration).
@@ -109,8 +179,82 @@ module Finance
       -((amount * factor) + (final_payment.to_f * second_factor))
     end
 
+    # Pv computes present value.
+    #   Required Loan arguments: nominal_rate, duration, payment, future_value, *ptype
+    #
+    # @return [Float] The present value.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.24, duration: 12, future_value: 1000, payment: -300, ptype: :ending).pv
+    #   #=> 2384.1091906935
+    #
+    # @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 pv
+      factor = (1.0 + monthly_rate)**duration
+      second_factor = (factor - 1) * (1 + monthly_rate * ptype) / monthly_rate
+
+      -(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)
@@ -119,5 +263,13 @@ module Finance
           PAYMENT_TYPE_MAPPING[ptype]
         end
     end
+
+    # @api private
+    def remaining_balance
+      self.class.new(
+        nominal_rate: nominal_rate.to_f, duration: period - 1.0,
+        amount: amount.to_f, ptype: PAYMENT_TYPE_MAPPING.key(ptype)
+      ).fv(payment: pmt)
+    end
   end
 end

data/lib/finance/version.rb

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

data/spec/finance/loan_spec.rb

@@ -5,37 +5,37 @@ RSpec.describe Finance::Loan do
     context 'w/o a full set of params' do
       it 'calculates correct pmt value w/o :ptype' do
         loan = Finance::Loan.new(nominal_rate: 0.1, duration: 12, amount: 1000)
-        expect(loan.pmt).to eq(87.9158872300099)
+        expect(loan.pmt).to eq(-87.9158872300099)
       end
 
       it 'calculates correct pmt value w/o :nominal_rate' do
         loan = Finance::Loan.new(duration: 12, amount: 1200, ptype: :end)
-        expect(loan.pmt).to eq(100)
+        expect(loan.pmt).to eq(-100)
       end
     end
 
     context 'with zero rates' do
       it 'calculates correct pmt value for 3 years' do
         loan = Finance::Loan.new(nominal_rate: 0, duration: 36, amount: 10_000, ptype: :end)
-        expect(loan.pmt).to eq(277.77777777777777)
+        expect(loan.pmt).to eq(-277.77777777777777)
       end
 
       it 'calculates correct pmt value for 6 months' do
         loan = Finance::Loan.new(nominal_rate: 0, duration: 6, amount: 10_000, ptype: :end)
-        expect(loan.pmt).to eq(1666.6666666666667)
+        expect(loan.pmt).to eq(-1666.6666666666667)
       end
     end
 
     context 'with :beginning ptype' do
       it 'calculates correct pmt value' do
         loan = Finance::Loan.new(nominal_rate: 0.12, duration: 6, amount: 1000, ptype: :beginning)
-        expect(loan.pmt).to eq(170.8399670404763)
+        expect(loan.pmt).to eq(-170.8399670404763)
       end
     end
 
     it 'calculates correct pmt value' do
       loan = Finance::Loan.new(nominal_rate: 0.13, duration: 90, amount: 1_000_000, ptype: :end)
-      expect(loan.pmt).to eq(17_449.90775727763)
+      expect(loan.pmt).to eq(-17_449.90775727763)
     end
   end
 
@@ -70,4 +70,131 @@ RSpec.describe Finance::Loan do
       end
     end
   end
+
+  describe '#pv' do
+    context 'when :ptype == beginning' do
+      it 'calculates correct pv value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.24, duration: 12, future_value: 1000, payment: -300, ptype: :beginning
+        )
+        expect(loan.pv).to eq(2447.5612380190028)
+      end
+    end
+
+    context 'when :ptype == ending' do
+      it 'calculates correct pv value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.24, duration: 12, future_value: 1000, payment: -300, ptype: :ending
+        )
+        expect(loan.pv).to eq(2384.1091906935)
+      end
+    end
+  end
+
+  describe '#ipmt' do
+    context 'when 1 period' do
+      it 'calculates correct ipmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 1
+        )
+        expect(loan.ipmt).to eq(-17.166666666666668)
+      end
+    end
+
+    context 'when 2 periods' do
+      it 'calculates correct ipmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 2
+        )
+        expect(loan.ipmt).to eq(-15.789337457350777)
+      end
+    end
+
+    context 'when 3 periods' do
+      it 'calculates correct ipmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12.0, amount: 2500.0, period: 3.0, fv: 0.0
+        )
+        expect(loan.ipmt).to eq(-14.402550587464257)
+      end
+    end
+  end
+
+  describe '#ppmt' do
+    context 'when 1 period' do
+      it 'calculates correct ppmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 1
+        )
+        expect(loan.ppmt).to eq(-200.58192368678277)
+      end
+    end
+
+    context 'when 2 periods' do
+      it 'calculates correct ppmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 2
+        )
+        expect(loan.ppmt).to eq(-201.95925289609866)
+      end
+    end
+
+    context 'when 3 periods' do
+      it 'calculates correct ppmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 3
+        )
+        expect(loan.ppmt).to eq(-203.34603976598518)
+      end
+    end
+
+    context 'when 4 periods' do
+      it 'calculates correct ppmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 4
+        )
+        expect(loan.ppmt).to eq(-204.7423492390449)
+      end
+    end
+
+    context 'when 5 periods' do
+      it 'calculates correct ppmt value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.0824, duration: 12, amount: 2500, period: 5
+        )
+        expect(loan.ppmt).to eq(-206.1482467038197)
+      end
+    end
+  end
+
+  describe '#nper' do
+    context 'with normal arguments' do
+      it 'calculates correct nper value' do
+        loan = Finance::Loan.new(
+          nominal_rate: 0.07, amount: 8000, payment: -150, future_value: 0 
+        )
+        expect(loan.nper).to eq(64.0733487706618586)
+      end
+    end
+
+    context 'with incorrect arguments' do
+      it 'raises Math::DomainError' do
+        loan = Finance::Loan.new(
+          nominal_rate: 1e100, amount: 8000, payment: -150, future_value: 0 
+        )
+        expect { loan.nper }.to raise_error(Math::DomainError)
+      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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finance_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Vlad Dyachenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-30 00:00:00.000000000 Z
+date: 2021-05-01 00:00:00.000000000 Z
 dependencies: []
 description: A ruby port of numpy-financial functions. This library provides a Ruby
   interface for working with interest rates, mortgage amortization, and cashflows