finance_rb 0.0.2 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fa908552e787182999bb782ed6c7f7f624307f0acd77ff969c0171e07dd0179
-  data.tar.gz: e0492ef3dd7baa271a4d7893ff32c5c94de852d2328d1c49321bb1d78147f08e
+  metadata.gz: 3f920db19ed5b406b8e263c09fac4aba9cd203ebdca989c096b44b441753757e
+  data.tar.gz: 435cd054975eee4b5027245d0301551b1b0cfd889153879f02929f1885d55f77
 SHA512:
-  metadata.gz: ccc866a27aecf49b0f869f9ddf590ac58d7682bc35c30a5abfda526251b800960b143fa19b05063411e30061a96f950963c4f8c38d867da763b1654ec77bfb52
-  data.tar.gz: 5ca7d064faf5bb38ad5cd70ddb1595d8983833e4ad9b46290f17b9f5ca8eee2abd4e4c99eedf852bbf79790c28d54e4aa4743beeffbf72921ff0dccc95f1cc94
+  metadata.gz: 15fa362a606eacc22aeff3c89312bbedbfbe2d78319b66cd3c146a985a6c5a68114fcb1601986facdc823fa14b03a798708faae3adf704aad8c8ee89c59ec07b
+  data.tar.gz: c96d0f272ccee5c88cab312981f7795bac101e7bd3b229b88cfb34f05db3334b63bc61d9f41f13404105c6b6ab6bd4d318ecf3ad98ac89dbe443f1cc920a453a

data/CHANGELOG.md

@@ -1,4 +1,29 @@
-## [Unreleased]
+## [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
 
 ## [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|
-| 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|
+| 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/calculations.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require 'bigdecimal'
+require 'bigdecimal/newton'
+
+include Newton
+
 module Finance
   class Calculations
     class << self
       # Npv computes the Net Present Value of a cash flow series.
+      #
       # @return [Numeric] The NPV of the input cash flow series `values` at the discount `rate`.
       #
       # @param [Numeric] :rate A discount rate applied once per period.
@@ -24,7 +30,100 @@ module Finance
         npv_value
       end
 
+      # IRR computes the Rate of Interest per period.
+      #
+      # @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'
+      #   Finance::Calculations.irr([-100, 0, 0, 74]) #=> 0.14299344106053188
+      #
+      # @see http://en.wikipedia.org/wiki/Internal_rate_of_return
+      # @see L. J. Gitman, "Principles of Managerial Finance, Brief," 3rd ed.,
+      #   Addison-Wesley, 2003, pg. 348.
+      def irr(values)
+        return 0.0 unless correct_cashflows?(values)
+
+        func = BigDecimal.limit(100)
+        func = Function.new(values)
+        rate = [ func.one ]
+        nlsolve(func, rate)
+        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
+      class Function
+        def initialize(values)
+          @zero   = BigDecimal("0.0")
+          @one    = BigDecimal("1.0")
+          @two    = BigDecimal("2.0")
+          @ten    = BigDecimal("10.0")
+          @eps    = BigDecimal("1.0e-16")
+          @values = values
+        end
+        
+        def zero; @zero; end
+        def one ; @one;  end
+        def two ; @two;  end
+        def ten ; @ten;  end
+        def eps ; @eps;  end
+
+        def values(x); [Finance::Calculations.npv(x[0], @values)]; end
+      end
     end
   end
 end

data/lib/finance/loan.rb

@@ -2,12 +2,161 @@
 
 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
+
+    # 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.2"
+  VERSION = "0.1.2"
 end

data/spec/finance/calculations_spec.rb

@@ -12,10 +12,72 @@ RSpec.describe Finance::Calculations do
       ).to eq(-85.07888805409468)
     end
 
-    it 'returns correct npv for zero rates' do
+    it 'calculates correct npv for zero rates' do
       expect(
         Finance::Calculations.net_present_value(0.0, [-2000, 55, 55, 55])
       ).to eq(-1835.0)
     end
   end
+
+  describe '#irr' do
+    it 'calculates correct irr value' do
+      expect(
+        Finance::Calculations.irr([-4000,1200,1410,1875,1050])
+      ).to eq(0.14299344106053188)
+    end
+
+    it 'calculates zero for cashflows w/o any inflows' do
+      expect(
+        Finance::Calculations.irr([100,500,200,50])
+      ).to eq(0.0)
+    end
+
+    it 'is available through alias name' do
+      expect(
+        Finance::Calculations.internal_return_rate([-100, 0, 0, 74])
+      ).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,102 @@
+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
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finance_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.2
 platform: ruby
 authors:
 - Vlad Dyachenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-22 00:00:00.000000000 Z
+date: 2021-04-04 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,15 +27,16 @@ 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:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/wowinter13/finance_rb/issues
-  changelog_uri: https://github.com/wowinter13/finance_rb/blob/v0.0.2/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/wowinter13/finance_rb/0.0.2
-  source_code_uri: https://github.com/wowinter13/finance_rb/tree/v0.0.2
+  changelog_uri: https://github.com/wowinter13/finance_rb/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/github/wowinter13/finance_rb
+  source_code_uri: https://github.com/wowinter13/finance_rb
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -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