finance_rb 0.0.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82235bcca3f51afff5ec345707da9d1ed2e8472a20488bb3847a4967baf6932c
-  data.tar.gz: '02029b9b9151d52ad860b1f985cc708199d734f8f210e574cda50fc7290f4231'
+  metadata.gz: 52d806b7797622aa42c8a3d13197ddd3e66817dd41199751cc402d2e2ede4741
+  data.tar.gz: 3404f5b73ededdd707d82f976a61bed2b575a3e00b448c1b056a06c92169bd5a
 SHA512:
-  metadata.gz: 38348b526019d3124c6cff67c4cd39427600d7a52ea584ea9b583328bedcfceb6680783bbbfdb8f9b45b686ff612e6295e670f1a09d882e09f4540fcf23a3aea
-  data.tar.gz: 879a9b9b6e01efd654e32a1bbc77a9e07e8a9b1cebbbb1061f6d20f3e0aa723b8150fbf8a56e66dee87bf3eb69a14301dc4d9a51fd62f87e9414f69f47aab5d6
+  metadata.gz: b2114092617e4120fc0b4e61d5e98cd0c227c882605e10fb0bfafdeb761f8c6dc8124a82ac729b548f4365f1a7fa17b061ad14a1e8d1befb6608ced7f4d68634
+  data.tar.gz: c42f87903359390b44fdb6472baacf24f6fc60934961cd16c007675e1adb231c0122bfca514c4ceffab7506f66b13b95736474c85ae23b4d4d103259f747f718

data/CHANGELOG.md

@@ -1,12 +1,42 @@
+## [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
+* Create a basic structure for `Finance::Loan`
+* Implement `Finance::Loan#pmt`
+
+
 ## [0.0.4] - 2021-03-25
 
 ### Added
-* Implement Finance::Calculations#mirr
+* Implement `Finance::Calculations#mirr`
 
 ## [0.0.3] - 2021-03-23
 
 ### Added
-* Implement Finance::Calculations#irr using Newton's method
+* Implement `Finance::Calculations#irr` using Newton's method
 
 ## [0.0.2] - 2021-03-22
 

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|
-| 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|
+| 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|
 | 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

@@ -2,24 +2,198 @@
 
 module Finance
   class Loan
+    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
+
+    # @return [Integer] Specification of whether payment is made
+    #   at the beginning (ptype = 1) or the end (ptype = 0) of each period.
+    #   Defaults to {:end, 0}.
+    attr_accessor :ptype
+
+    # @return [Float] The nominal annual rate of interest as decimal (not per cent).
+    #   (e.g., 13% -> 0.13)
+    #   Defaults to 0.
+    attr_accessor :nominal_rate
+
+    # @return [Float] The monthly rate is the nominal annual rate divided by 12.
+    #   Defaults to 0.
+    attr_reader :monthly_rate
+
+    # @return [Float] The number of periods to be compounded for. (I.e. Nper())
+    #   Defaults to 1.
+    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
+      @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).
+    #   It can also be used to calculate the recurring payments needed to achieve
+    #   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
+    #   require 'finance_rb'
+    #   Finance::Loan.new(nominal_rate: 0.1, duration: 12, amount: 1000, ptype: :end).pmt
+    #   #=> 87.9158872300099
+    #
+    # @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 pmt
+      factor = (1.0 + monthly_rate)**duration
+      second_factor =
+        if monthly_rate.zero?
+          duration
+        else
+          (factor - 1) * (1 + monthly_rate * ptype) / monthly_rate
+        end
+
+      -((future_value + amount * factor) / second_factor)
     end
 
-    def pmt()
+    # 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
 
-    def ipmt()
+    # 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
 
-    def ppmt()
+    # 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
 
-    def fv();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
 
-    def pv();end
+      factor = (1.0 + monthly_rate)**duration
+      second_factor = (factor - 1) * (1 + monthly_rate * ptype) / monthly_rate
 
-    def nper();end
+      -((amount * factor) + (final_payment.to_f * second_factor))
+    end
+
+    private
 
-    def rate();end
+    def initialize_payment_type(ptype)
+      @ptype =
+        if ptype.nil? || !PAYMENT_TYPE_MAPPING.keys.include?(ptype)
+          PAYMENT_TYPE_MAPPING[:end]
+        else
+          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.0.4"
+  VERSION = "0.2.1"
 end

data/spec/finance/loan_spec.rb

@@ -0,0 +1,169 @@
+require 'spec_helper'
+
+RSpec.describe Finance::Loan do
+  describe '#pmt' 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)
+      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)
+      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)
+      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)
+      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)
+      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)
+    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 '#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.0.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Vlad Dyachenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-24 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
@@ -27,6 +27,7 @@ files:
 - lib/finance/version.rb
 - lib/finance_rb.rb
 - spec/finance/calculations_spec.rb
+- spec/finance/loan_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/wowinter13/finance_rb
 licenses:
@@ -57,4 +58,5 @@ specification_version: 4
 summary: A library for finance manipulations in Ruby.
 test_files:
 - spec/finance/calculations_spec.rb
+- spec/finance/loan_spec.rb
 - spec/spec_helper.rb