finance_rb 0.1.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a3ce7fbe55b1715dc8b2b636326a1bb99eb4b8638f2a3c111e0decfe1b4d126
-  data.tar.gz: a5568d0deadc00bdd55ffac1cb05dee7a7d8abb8bee87015d321916f59694705
+  metadata.gz: 07e154f5ba5d444fe1e2c782c39a3d21a79b9fd3d413fba6e7c5285fa5f07df4
+  data.tar.gz: bef7aea3a7f54df1fc69d05619e9416637c717ce7e8b4d3a211573fbfbf5a6df
 SHA512:
-  metadata.gz: cd349f4f6aa4cf20fab8db9064da6b77f1199b61b927af170f491dd447cfdb3889aeea97d07de34706ca12493cfae56d1089aa8cfb2ff80e351ddd951d3e92e9
-  data.tar.gz: fdef6ff2746503b68a2a83494b6a006f05a7216f87125a71967dfdf7de05d4dcae80563f4cfbac0cf8ce7b91c5510cfd4cc4111cbe49f6573e43dc37fc21d4f2
+  metadata.gz: bf67fafbda3defb85d73581d02b3dc00b26f83c6b03e4f35bd5c2d3a0ac661a823cd737d8055c54309b8a6d6feba8be7d03675b39ddb95b2e8f7ceaa94a7e472
+  data.tar.gz: 4f429be0368ac5e986c689fcd6afd146cec1676741d149ced828ae6d03e38e2d2e1ebdfeae88fce1d76de1a31c51a08fb0809577362f07f1de0e70e761bfa8b1

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [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
+* Implement `Finance::Loan#fv`
+
 ## [0.1.0] - 2021-03-28
 
 ### Added

data/README.md

@@ -4,20 +4,48 @@ This package is a ruby native port of the numpy-financial package with some help
 
 The functions in this package are a scalar version of their vectorised counterparts in the [numpy-financial](https://github.com/numpy/numpy-financial) library.
 
-[![Release](https://img.shields.io/github/v/release/wowinter13/finance_rb.svg?style=flat-square)](https://github.com/wowinter13/finance_rb/releases) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+[![Release](https://img.shields.io/github/v/release/wowinter13/finance_rb.svg?style=flat-square)](https://github.com/wowinter13/finance_rb/releases) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) [![Maintainability](https://api.codeclimate.com/v1/badges/bbca82ad7815794c6718/maintainability)](https://codeclimate.com/github/wowinter13/finance_rb/maintainability)
 
 Currently, only some functions are ported,  
 which are as follows:  
 
 | numpy-financial function     | ruby native function ported?   | info|
 |:------------------------:    |:------------------:  | :------------------|
-| fv                           |       |   Computes the  future value|
-| ipmt                         |       |   Computes interest payment for a loan|
+| fv                           |   ✅    |   Computes the  future value|
+| 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|
+| 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|
+| mirr                         |    ✅    |    Computes the modified internal rate of return|
+
+## Installation
+
+finance_rb is available as a gem, to install it just install the gem:
+
+    gem install finance_rb
+
+If you're using Bundler, add the gem to Gemfile.
+
+    gem 'finance_rb'
+
+Run `bundle install`.
+
+## Running tests
+
+    bundle exec rspec spec/
+
+## Contributing
+
+1. Fork it ( https://github.com/wowinter13/finance_rb/fork )
+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 a new Pull Request
+
+## License
+
+MIT License. See LICENSE for details.

data/lib/finance/loan.rb

@@ -5,6 +5,7 @@ module Finance
     PAYMENT_TYPE_MAPPING = { end: 0, beginning: 1 }.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.
     #   Defaults to 0.
     attr_accessor :amount
 
@@ -24,19 +25,31 @@ 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.
+    #   You can use #fv method to calculate value if param is not defined.
     #   Defaults to 0.
     attr_accessor :future_value
 
+    # @return [Float] The (fixed) periodic payment.
+    #   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])
       @nominal_rate  = options.fetch(:nominal_rate, 0).to_f
       @duration      = options.fetch(:duration, 1).to_f
       @amount        = options.fetch(:amount, 0).to_f
       @future_value  = options.fetch(:future_value, 0).to_f
-      @monthly_rate = @nominal_rate / 12
+      @period        = options[:period]
+      @payment       = options[:payment]
+      @monthly_rate  = @nominal_rate / 12
     end
 
     # Pmt computes the payment against a loan principal plus interest (future_value = 0).
@@ -44,6 +57,8 @@ module Finance
     #   a certain future value given an initial deposit,
     #   a fixed periodically compounded interest rate, and the total number of periods.
     #
+    #   Required Loan arguments: nominal_rate, duration, amount, future_value*
+    #
     # @return [Numeric] The (fixed) periodic payment.
     #
     # @example
@@ -66,7 +81,125 @@ 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] 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] 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] 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).
+    #   Required Loan arguments: nominal_rate, duration, payment, amount*
+    #
+    # @param payment [Float] The (fixed) periodic payment.
+    #   In case you don't want to modify the original loan, use this parameter to recalculate fv.
+    #
+    # @return [Float] The value at the end of the `duration` periods.
+    #
+    # @example
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.05, duration: 120, amount: -100, payment: -200).fv
+    #   #=> 15692.928894335748
+    #
+    # @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 fv(payment: nil)
+      raise ArgumentError, 'no payment given' if self.payment.nil? && payment.nil?
+
+      final_payment = payment || self.payment
+
+      factor = (1.0 + monthly_rate)**duration
+      second_factor = (factor - 1) * (1 + monthly_rate * ptype) / monthly_rate
+
+      -((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
 
     private
@@ -79,5 +212,12 @@ module Finance
           PAYMENT_TYPE_MAPPING[ptype]
         end
     end
+
+    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.0"
+  VERSION = "0.2.2"
 end

data/spec/finance/loan_spec.rb

@@ -5,37 +5,185 @@ 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
+
+  describe '#fv' do
+    context 'with loan arguments' do
+      it 'calculates correct fv value' do
+        loan = Finance::Loan.new(nominal_rate: 0.05, duration: 120, amount: -100, payment: -100)
+        expect(loan.fv).to eq(15_692.928894335748)
+      end
+
+      context 'with :ptype' do
+        it 'calculates correct fv value' do
+          loan = Finance::Loan.new(
+            nominal_rate: 0.9, duration: 20, amount: 0, payment: -2000, ptype: :beginning
+          )
+          expect(loan.fv).to eq(93_105.06487352113)
+        end
+      end
+    end
+
+    context 'with an optional :payment argument' do
+      it 'calculates correct fv value' do
+        loan = Finance::Loan.new(nominal_rate: 0.05, duration: 120, amount: -100, payment: -200)
+        expect(loan.fv(payment: -100)).to eq(15_692.928894335748)
+      end
+    end
+
+    context 'w/o any payments' do
+      it 'raises an ArgumentError exception w/o loan arguments' do
+        loan = Finance::Loan.new(nominal_rate: 0.05, duration: 120, amount: -100)
+        expect { loan.fv }.to raise_error(ArgumentError, "no payment given")
+      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
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finance_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Vlad Dyachenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-28 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