finance_rb 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a0dc37279e3b577acb13a90c61ad4f232573a4d8c0eccdf19a267d42001a9ea
-  data.tar.gz: ca6db2175dd770056d7539d555b239127bcc5836ae79826edc6807a4f5bd4311
+  metadata.gz: d76ff15f6be262332aa729708a548d775f1caaaefaa3135c1d545660c34717ca
+  data.tar.gz: 2d75e526b34bf1704686e3fb9bf5198b4b2d302f05e714207d8d06833ce96acf
 SHA512:
-  metadata.gz: 395383e7e7c9b2b564a738aae13bc6f95d7180652b951a2fa4cf90118e551cb0cba6e87badb4ca23c7b5ab790be2de0ff5bef0e3736c50c18a7246262b2ae496
-  data.tar.gz: 5c9a8d1e5b8726234fafa45ed747dcf881f7ae92a9157abf34e9186594775a4e651fc8c09395cdd9fd30e21426e217c4216f2b13644ee15f324a967325d4bf6a
+  metadata.gz: 9545eebb0c540d6e5f3d75cdbf8a5b7fabe0ed75860601dd278f2c0b13ca05285a9d0865d978837532c92c2fb70815c5f450a10d6ff7bd008330ae81ac4d915b
+  data.tar.gz: bffcb93c73279bea34db04dbc39d0b6747e9d609e91a3a5f8006aaefe6ca08be2a4109b033b622a3382a4232a4e3ffba4d1a2eb168fbf6f1e6fe73fd971ab20c

data/CHANGELOG.md

@@ -1,7 +1,29 @@
+## [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`
+
 ## [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

@@ -2,20 +2,50 @@
 
 This package is a ruby native port of the numpy-financial package with some helpful additional functions.
 
-The functions in this package are a scalar version of their vectorised counterparts in  the [numpy-financial](https://github.com/numpy/numpy-financial) library.
+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) [![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|
+| 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|
+| 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/calculations.rb

@@ -35,6 +35,8 @@ module Finance
       # @return [Float] Internal Rate of Return for periodic input values.
       #
       # @param [Array<Numeric>] :values Input cash flows per time period.
+      #   At least, must contain one positive and one negative value.
+      #   Otherwise, irr equals zero.
       #
       # @example
       #   require 'finance_rb'
@@ -44,10 +46,7 @@ module Finance
       # @see L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed.,
       #   Addison-Wesley, 2003, pg. 348.
       def irr(values)
-        inflows, outflows = values.partition{ |i| i >= 0 }
-        if inflows.empty? || outflows.empty?
-          return 0.0
-        end
+        return 0.0 unless correct_cashflows?(values)
 
         func = BigDecimal.limit(100)
         func = Function.new(values)
@@ -56,11 +55,54 @@ module Finance
         rate[0].to_f
       end
 
+      # MIRR computes the modified Rate of Interest.
+      #
+      # @return [Float] Modified Internal Rate of Return.
+      #
+      # @param [Array<Numeric>] :values
+      #   At least, must contain one positive and one negative value.
+      #   Otherwise, mirr equals zero.
+      # @param [Numeric] :rate Interest rate paid on the cash flows
+      # @param [Numeric] :reinvest_rate Interest rate received on the cash flows upon reinvestment
+      # 
+      # @example
+      #   require 'finance_rb'
+      #   Finance::Calculations.mirr([100, 200, -50, 300, -200], 0.05, 0.06) => 0.2979256979689131
+      #
+      # @see https://en.wikipedia.org/wiki/Modified_internal_rate_of_return
+      def mirr(values, rate, reinvest_rate)
+        inflows = [];
+        outflows = [];
+        # We prefer manual enumeration over the partition
+        #   because of the need to replace outflows with zeros.
+        values.each do |val|
+          if val >= 0
+            inflows << val
+            outflows << 0.0
+          else
+            outflows << val
+            inflows << 0.0
+          end
+        end
+        if outflows.all?(0.0) || inflows.all?(0.0)
+          return 0.0
+        end
+        fv = npv(reinvest_rate, inflows).abs
+        pv = npv(rate, outflows).abs
+
+        return (fv/pv) ** (1.0/(values.size - 1)) * (1 + reinvest_rate) - 1
+      end
+
       alias net_present_value npv
       alias internal_return_rate irr
 
       private
 
+      def correct_cashflows?(values)
+        inflows, outflows = values.partition{ |i| i >= 0 }
+        !(inflows.empty? || outflows.empty?)
+      end
+
       # Base class for working with Newton's Method.
       # For more details, see Bigdecimal::Newton.
       # @api private

data/lib/finance/loan.rb

@@ -2,12 +2,182 @@
 
 module Finance
   class Loan
-    def initialize; end
+    PAYMENT_TYPE_MAPPING = { end: 0, beginning: 1 }.freeze
 
-    def pmt; end
+    # @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
 
-    def ipmt; end
+    # @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
 
-    def ppmt; end
+    # @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
+
+    # 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
+
+    # 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
+
+    private
+
+    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.3"
+  VERSION = "0.2.0"
 end

data/spec/finance/calculations_spec.rb

@@ -26,7 +26,7 @@ RSpec.describe Finance::Calculations do
       ).to eq(0.14299344106053188)
     end
 
-    it 'calculates zero value for cashflows w/o any inflows' do
+    it 'calculates zero for cashflows w/o any inflows' do
       expect(
         Finance::Calculations.irr([100,500,200,50])
       ).to eq(0.0)
@@ -38,4 +38,46 @@ RSpec.describe Finance::Calculations do
       ).to eq(-0.09549583035161031)
     end
   end
+
+  describe '#mirr' do
+    it 'calculates correct mirr value' do
+      expect(
+        Finance::Calculations.mirr(
+          [-120000.0, 39000.0, 30000.0, 21000.0, 37000.0, 46000.0], 0.10, 0.12
+        )
+      ).to eq(0.1260941303659051)
+    end
+    
+    it 'calculates correct mirr value with integers' do
+      expect(
+        Finance::Calculations.mirr(
+          [-4500, -800, 800, 800, 600, 600, 800, 800, 700, 3000], 0.08, 0.055
+        )
+      ).to eq(0.06659717503155349)
+    end
+
+    it 'calculates zero for cashflows w/o any outflows' do
+      expect(
+        Finance::Calculations.mirr(
+          [39000, 30000, 21000, 37000, 46000], 0.10, 0.12
+        )
+      ).to eq(0.0)
+    end
+
+    it 'calculates zero for cashflows w/o any inflows' do
+      expect(
+        Finance::Calculations.mirr(
+          [-1000, -5000, -2000, -100, -50], 0.10, 0.12
+        )
+      ).to eq(0.0)
+    end
+
+    it 'calculates correct mirr value for a shuffled order' do
+      expect(
+        Finance::Calculations.mirr(
+          [100, 200, -50, 300, -200], 0.05, 0.06
+        )
+      ).to eq(0.3428233878421769)
+    end
+  end
 end

data/spec/finance/loan_spec.rb

@@ -0,0 +1,149 @@
+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
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finance_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Vlad Dyachenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-22 00:00:00.000000000 Z
+date: 2021-04-30 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