finrb 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0e0f1b32ce469fa5fb2078a6f55e4836c8bbff50918efd593da7934ed3e230
-  data.tar.gz: 58cae9f2f1d746067d98f2ecd17e9c503506f2416559773429e6473a3b5e3f9b
+  metadata.gz: ccdd649275425f90381f0836259a3f054db4a1f6e115bcd2f2a70a3460669cb4
+  data.tar.gz: ef0a8b3cae6e610be1e6eb5d191bf2a182086768af3272be1ca93126ff2b29f5
 SHA512:
-  metadata.gz: 1a98a8c9a19317253db7e464590ce111fb7bdb6a88aca5c29b2e6f30d0378701ebc3d956061d2672e8450a40de883cdf342a04ca3993608bc2726347097064da
-  data.tar.gz: be19a4a46eb02e4f422f690709f13e5800cbeae3be82e7f7d323970333cdbd65eebbb17bf2acab77b23710bd626bafa070454ecdbb1f48d85b4c99a28cd55e18
+  metadata.gz: c8e35323bab165cca2e888ae745a85a9ee7a7a1ff348fa50e4929d44680a6383e13a15cc3a842d1aa2ba1804c14590f44cea406b7bf4706b36c131a7bd187492
+  data.tar.gz: c42221400c4d86b865541cb2df0c1a215b04c903536cd76d1bbc2a297cddb5de3276b568d196b5b4cb9b0c156cbe5433226db0764d21612b25e455dbafb25265

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # finrb changelog
 
+## 0.1.2
+
+- refactoring
+
+## 0.1.1
+
+- documentation additions and fixes
+- refactoring
+- bugfixes and test suite migration to rspec
+
 ## 0.1.0
 
 - sets ruby dependency to >= 3

data/README.md

@@ -4,6 +4,18 @@
 [![CodeQL](https://github.com/ncs1/finrb/actions/workflows/codeql.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/codeql.yml)
 [![RuboCop](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml)
 
+<!-- TOC depthfrom:2 -->
+
+- [Overview](#overview)
+  - [Features](#features)
+  - [Configuration](#configuration)
+  - [API and examples](#api-and-examples)
+- [Resources](#resources)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+<!-- /TOC -->
+
 Ruby gem for financial calculations/modeling.
 
 finrb forked from the ruby [finance](https://github.com/Edward-Intelligence/finance) gem.
@@ -14,66 +26,103 @@ finrb forked from the ruby [finance](https://github.com/Edward-Intelligence/fina
 
 Currently implemented features include:
 
-* Uses the [flt](https://github.com/jgoizueta/flt) gem to ensure precision decimal arithmetic in all calculations.
-* Fixed-rate mortgage amortization (30/360).
-* Interest rates
-* Various cash flow computations, such as NPV and IRR.
-* Adjustable rate mortgage amortization.
-* Payment modifications (i.e., how does paying an additional $75 per month affect the amortization?)
-* Utils class provides basic financial calculation utilities (ported from R's [FinCal](https://github.com/felixfan/FinCal) library):
-  * Computing bank discount yield (BDY) for a T-bill
-  * Computing money market yield (MMY) for a T-bill
-  * Cash ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
-  * Computing Coefficient of variation
-  * Cost of goods sold and ending inventory under three methods (FIFO,LIFO,Weighted average)
-  * Current ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
-  * Depreciation Expense Recognition - double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
-  * Debt ratio - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
-  * Diluted Earnings Per Share
-  * Computing the rate of return for each period
-  * Convert stated annual rate to the effective annual rate
-  * Convert stated annual rate to the effective annual rate with continuous compounding
-  * Bond-equivalent yield (BEY), 2 x the semiannual discount rate
-  * Computing HPR, the holding period return
-  * Equivalent/proportional Interest Rates
-  * Basic Earnings Per Share
-  * Financial leverage - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
-  * Estimate future value (fv)
-  * Estimate future value of an annuity
-  * Estimate future value (fv) of a single sum
-  * Computing the future value of an uneven cash flow series
-  * Geometric mean return
-  * Gross profit margin - Evaluate a company's financial performance
-  * Harmonic mean, average price
-  * Computing HPR, the holding period return
-  * Bond-equivalent yield (BEY), 2 x the semiannual discount rate
-  * Convert holding period return to the effective annual rate
-  * Computing money market yield (MMY) for a T-bill
-  * Computing IRR, the internal rate of return
-  * Calculate the net increase in common shares from the potential exercise of stock options or warrants
-  * Long-term debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
-  * Computing HPR, the holding period return
-  * Estimate the number of periods
-  * Net profit margin - Evaluate a company's financial performance
-  * Computing NPV, the PV of the cash flows less the initial (time = 0) outlay
-  * Estimate period payment
-  * Estimate present value (pv)
-  * Estimate present value (pv) of an annuity
-  * Estimate present value of a perpetuity
-  * Estimate present value (pv) of a single sum
-  * Computing the present value of an uneven cash flow series
-  * Quick ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
-  * Convert a given norminal rate to a continuous compounded rate
-  * Convert a given continuous compounded rate to a norminal rate
-  * Rate of return for a perpetuity
-  * Computing Sampling error
-  * Computing Roy's safety-first ratio
-  * Computing Sharpe Ratio
-  * Depreciation Expense Recognition - Straight-line depreciation (SL) allocates an equal amount of depreciation each year over the asset's useful life
-  * Total debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
-  * Computing TWRR, the time-weighted rate of return
-  * Calculate weighted average shares - weighted average number of common shares
-  * Weighted mean as a portfolio return
+- Uses the [flt](https://github.com/jgoizueta/flt) gem to ensure precision decimal arithmetic in all calculations.
+- Fixed-rate mortgage amortization (30/360).
+- Interest rates
+- Various cash flow computations, such as NPV and IRR.
+- Adjustable rate mortgage amortization.
+- Payment modifications (i.e., how does paying an additional $75 per month affect the amortization?)
+- Utils class provides basic financial calculation utilities (ported from R's [FinCal](https://github.com/felixfan/FinCal) library):
+
+  - Basic Earnings Per Share
+
+  - Bond-equivalent yield (BEY), 2 x the semiannual discount rate
+
+  - Calculate the net increase in common shares from the potential exercise of stock options or warrants
+
+  - Calculate weighted average shares - weighted average number of common shares
+
+  - Cash ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+
+  - Computing Coefficient of variation
+
+  - Computing HPR, the holding period return
+
+  - Computing IRR, the internal rate of return
+
+  - Computing NPV, the PV of the cash flows less the initial (time = 0) outlay
+
+  - Computing Roy's safety-first ratio
+
+  - Computing Sampling error
+
+  - Computing Sharpe Ratio
+
+  - Computing TWRR, the time-weighted rate of return
+
+  - Computing bank discount yield (BDY) for a T-bill
+
+  - Computing money market yield (MMY) for a T-bill
+
+  - Computing the future value of an uneven cash flow series
+
+  - Computing the present value of an uneven cash flow series
+
+  - Computing the rate of return for each period
+
+  - Convert a given continuous compounded rate to a norminal rate
+
+  - Convert a given norminal rate to a continuous compounded rate
+
+  - Convert holding period return to the effective annual rate
+
+  - Convert stated annual rate to the effective annual rate (with continuous compounding)
+
+  - Cost of goods sold and ending inventory under three methods (FIFO,LIFO,Weighted average)
+
+  - Current ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+
+  - Debt ratio - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+
+  - Depreciation Expense Recognition - Straight-line depreciation (SL) allocates an equal amount of depreciation each year over the asset's useful life
+
+  - Depreciation Expense Recognition - double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
+
+  - Diluted Earnings Per Share
+
+  - Equivalent/proportional Interest Rates
+
+  - Estimate future value (fv) (of a single sum)
+
+  - Estimate future value of an annuity
+
+  - Estimate period payment
+
+  - Estimate present value (pv) (of a single sum) (of an annuity)
+
+  - Estimate present value of a perpetuity
+
+  - Estimate the number of periods
+
+  - Financial leverage - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+
+  - Geometric mean return
+
+  - Gross profit margin - Evaluate a company's financial performance
+
+  - Harmonic mean, average price
+
+  - Long-term debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+
+  - Net profit margin - Evaluate a company's financial performance
+
+  - Quick ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+
+  - Rate of return for a perpetuity
+
+  - Total debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+
+  - Weighted mean as a portfolio return
 
 ### Configuration
 
@@ -94,9 +143,14 @@ See [api.md](docs/api.md)
 
 ## Resources
 
-* [RubyGems Page](https://rubygems.org/gems/finrb)
-* [Source Code](https://github.com/ncs1/finrb)
-* [Bug Tracker](https://github.com/ncs1/finrb/issues)
+- [RubyGems Page](https://rubygems.org/gems/finrb)
+- [Source Code](https://github.com/ncs1/finrb)
+- [Bug Tracker](https://github.com/ncs1/finrb/issues)
+
+## Acknowledgements
+
+- Martin Bjeldbak Madsen (@martinbjeldbak), Bill Kranec (@wkranec) - original [finance](https://github.com/Edward-Intelligence/finance) gem maintainers.
+- Yanhui Fan (@felixfan) - maintainer of [FinCal](https://github.com/felixfan/FinCal) library.
 
 ## License
 

data/lib/finrb/amortization.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "cashflows"
-require_relative "decimal"
-require_relative "transaction"
+require_relative 'cashflows'
+require_relative 'decimal'
+require_relative 'transaction'
 
 module Finrb
   # the Amortization class provides an interface for working with loan amortizations.
@@ -21,22 +21,42 @@ module Finrb
   #   extra_payments = 250000.amortize(rate){ |period| period.payment - 150 }
   # @api public
   class Amortization
-    # @return [DecNum] the balance of the loan at the end of the amortization period (usually zero)
+    # @return [Flt::DecNum] the balance of the loan at the end of the amortization period (usually zero)
     # @api public
     attr_reader :balance
-    # @return [DecNum] the required monthly payment.  For loans with more than one rate, returns nil
+    # @return [Flt::DecNum] the required monthly payment.  For loans with more than one rate, returns nil
     # @api public
     attr_reader :payment
-    # @return [DecNum] the principal amount of the loan
+    # @return [Flt::DecNum] the principal amount of the loan
     # @api public
     attr_reader :principal
     # @return [Array] the interest rates used for calculating the amortization
     # @api public
     attr_reader :rates
 
+    # @return [Flt::DecNum] the periodic payment due on a loan
+    # @param [Flt::DecNum] principal the initial amount of the loan or investment
+    # @param [Rate] rate the applicable interest rate (per period)
+    # @param [Integer] periods the number of periods needed for repayment
+    # @note in most cases, you will probably want to use rate.monthly when calling this function outside of an Amortization instance.
+    # @example
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   rate.duration #=> 360
+    #   Amortization.payment(200000, rate.monthly, rate.duration) #=> Flt::DecNum('-926.23')
+    # @see https://en.wikipedia.org/wiki/Amortization_calculator
+    # @api public
+    def self.payment(principal, rate, periods)
+      if rate.zero?
+        # simplified formula to avoid division-by-zero when interest rate is zero
+        -(principal / periods).round(2)
+      else
+        -(principal * (rate + (rate / (((rate + 1)**periods) - 1)))).round(2)
+      end
+    end
+
     # create a new Amortization instance
     # @return [Amortization]
-    # @param [DecNum] principal the initial amount of the loan or investment
+    # @param [Flt::DecNum] principal the initial amount of the loan or investment
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
     # @api public
@@ -54,7 +74,7 @@ module Finrb
 
     # compare two Amortization instances
     # @return [Numeric] -1, 0, or +1
-    # @param [Amortization]
+    # @param [Amortization] other
     # @api public
     def ==(other)
       (principal == other.principal) && (rates == other.rates) && (payments == other.payments)
@@ -64,7 +84,7 @@ module Finrb
     # @example
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
-    #   amt.additional_payments #=> [DecNum('-100.00'), DecNum('-100.00'), ... ]
+    #   amt.additional_payments #=> [Flt::DecNum('-100.00'), Flt::DecNum('-100.00'), ... ]
     # @api public
     def additional_payments
       @transactions.filter_map { |trans| trans.difference if trans.payment? }
@@ -115,7 +135,7 @@ module Finrb
       end
 
       # Add any remaining balance due to rounding error to the last payment.
-      unless @balance.zero?
+      if @balance.nonzero?
         @transactions.reverse.find(&:payment?).amount -= @balance
         @balance = 0
       end
@@ -148,41 +168,21 @@ module Finrb
     # @example find the total cost of interest for a loan
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = 300000.amortize(rate)
-    #   amt.interest.sum #=> DecNum('200163.94')
+    #   amt.interest.sum #=> Flt::DecNum('200163.94')
     # @example find the total interest charges in the first six months
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = 300000.amortize(rate)
-    #   amt.interest[0,6].sum #=> DecNum('5603.74')
+    #   amt.interest[0,6].sum #=> Flt::DecNum('5603.74')
     # @api public
     def interest
       @transactions.filter_map { |trans| trans.amount if trans.interest? }
     end
 
-    # @return [DecNum] the periodic payment due on a loan
-    # @param [DecNum] principal the initial amount of the loan or investment
-    # @param [Rate] rate the applicable interest rate (per period)
-    # @param [Integer] periods the number of periods needed for repayment
-    # @note in most cases, you will probably want to use rate.monthly when calling this function outside of an Amortization instance.
-    # @example
-    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   rate.duration #=> 360
-    #   Amortization.payment(200000, rate.monthly, rate.duration) #=> DecNum('-926.23')
-    # @see https://en.wikipedia.org/wiki/Amortization_calculator
-    # @api public
-    def self.payment(principal, rate, periods)
-      if rate.zero?
-        # simplified formula to avoid division-by-zero when interest rate is zero
-        -(principal / periods).round(2)
-      else
-        -(principal * (rate + (rate / (((1 + rate)**periods) - 1)))).round(2)
-      end
-    end
-
     # @return [Array] the amount of the payment in each period
     # @example find the total payments for a loan
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = 300000.amortize(rate)
-    #   amt.payments.sum #=> DecNum('-500163.94')
+    #   amt.payments.sum #=> Flt::DecNum('-500163.94')
     # @api public
     def payments
       @transactions.filter_map { |trans| trans.amount if trans.payment? }

data/lib/finrb/cashflows.rb

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
-require_relative "decimal"
-require_relative "rates"
+require_relative 'config'
+require_relative 'decimal'
+require_relative 'rates'
 
-require "bigdecimal"
-require "bigdecimal/newton"
-require "business_time"
-include Newton
+require 'bigdecimal'
+require 'bigdecimal/newton'
+require 'business_time'
 
 module Finrb
+  include Newton
+
   # Provides methods for working with cash flows (collections of transactions)
   # @api public
   module Cashflow
     # Base class for working with Newton's Method.
     # @api private
     class Function
-      values = { eps: Finrb.config.eps, one: "1.0", two: "2.0", ten: "10.0", zero: "0.0" }
+      values = { eps: Finrb.config.eps, one: '1.0', two: '2.0', ten: '10.0', zero: '0.0' }
 
       values.each do |key, value|
         define_method key do
@@ -29,7 +31,7 @@ module Finrb
       end
 
       def values(x)
-        value = @transactions.send(@function, Flt::DecNum.new(x[0].to_s))
+        value = @transactions.public_send(@function, Flt::DecNum.new(x[0].to_s))
         begin
           [BigDecimal(value.to_s)]
         rescue ArgumentError
@@ -39,8 +41,8 @@ module Finrb
     end
 
     # calculate the internal rate of return for a sequence of cash flows
-    # @return [DecNum] the internal rate of return
-    # @param [Numeric] Initial guess rate, Defaults to 1.0
+    # @return [Flt::DecNum] the internal rate of return
+    # @param [Numeric] guess Initial guess rate, Defaults to 1.0
     # @example
     #   [-4000,1200,1410,1875,1050].irr #=> 0.143
     # @see https://en.wikipedia.org/wiki/Internal_rate_of_return
@@ -48,7 +50,7 @@ module Finrb
     def irr(guess = nil)
       # Make sure we have a valid sequence of cash flows.
       positives, negatives = partition { |i| i >= 0 }
-      raise(ArgumentError, "Calculation does not converge.") if positives.empty? || negatives.empty?
+      raise(ArgumentError, 'Calculation does not converge.') if positives.empty? || negatives.empty?
 
       func = Function.new(self, :npv)
       rate = [valid(guess)]
@@ -57,13 +59,17 @@ module Finrb
     end
 
     def method_missing(name, *args, &block)
-      return sum if name.to_s == "sum"
+      return sum if name.to_s == 'sum'
 
       super
     end
 
+    def respond_to_missing?(name, include_private = false)
+      name.to_s == 'sum' || super
+    end
+
     # calculate the net present value of a sequence of cash flows
-    # @return [DecNum] the net present value
+    # @return [Flt::DecNum] the net present value
     # @param [Numeric] rate the discount rate to be applied
     # @example
     #   [-100.0, 60, 60, 60].npv(0.1) #=> 49.211
@@ -75,7 +81,7 @@ module Finrb
       rate = Flt::DecNum.new(rate.to_s)
       total = Flt::DecNum.new(0.to_s)
       cashflows.each_with_index do |cashflow, index|
-        total += cashflow / ((1 + rate)**index)
+        total += cashflow / ((rate + 1)**index)
       end
 
       total
@@ -97,7 +103,7 @@ module Finrb
       if positives.empty? || negatives.empty?
         raise(
           ArgumentError,
-          "Calculation does not converge. Cashflow needs to have a least one positive and one negative value."
+          'Calculation does not converge. Cashflow needs to have a least one positive and one negative value.'
         )
       end
 
@@ -108,7 +114,7 @@ module Finrb
     end
 
     # calculate the net present value of a sequence of cash flows
-    # @return [DecNum]
+    # @return [Flt::DecNum]
     # @example
     #   @transactions = []
     #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
@@ -120,48 +126,47 @@ module Finrb
       rate = Flt::DecNum.new(rate.to_s)
 
       sum do |t|
-        t.amount / ((1 + rate)**(date_diff(start, t.date) / days_in_period))
+        t.amount / ((rate + 1)**(date_diff(start, t.date) / days_in_period))
       end
     end
 
     private
-      def date_diff(from, to)
-        if Finrb.config.business_days
-          from.to_date.business_days_until(to)
-        else
-          to - from
-        end
-      end
 
-      def days_in_period
-        if Finrb.config.periodic_compound && Finrb.config.business_days
-          start.to_date.business_days_until(stop).to_f
-        else
-          Flt::DecNum.new(365.days.to_s)
-        end
+    def date_diff(from, to)
+      if Finrb.config.business_days
+        from.to_date.business_days_until(to)
+      else
+        to - from
       end
+    end
 
-      def start
-        @start ||= self[0].date
+    def days_in_period
+      if Finrb.config.periodic_compound && Finrb.config.business_days
+        start.to_date.business_days_until(stop).to_f
+      else
+        Flt::DecNum.new(365.days.to_s)
       end
+    end
 
-      def stop
-        @stop ||= self[-1].date.to_date
-      end
+    def start
+      @start ||= self[0].date
+    end
 
-      def valid(guess)
-        if guess.nil?
-          unless Finrb.config.guess.is_a?(Numeric)
-            raise(ArgumentError, "Invalid Guess. Default guess should be a [Numeric] value.")
-          end
+    def stop
+      @stop ||= self[-1].date.to_date
+    end
 
-          Finrb.config.guess
-        else
-          raise(ArgumentError, "Invalid Guess. Use a [Numeric] value.") unless guess.is_a?(Numeric)
+    def valid(guess)
+      if guess.nil?
+        raise(ArgumentError, 'Invalid Guess. Default guess should be a [Numeric] value.') unless Finrb.config.guess.is_a?(Numeric)
 
-          guess
-        end.to_f
-      end
+        Finrb.config.guess
+      else
+        raise(ArgumentError, 'Invalid Guess. Use a [Numeric] value.') unless guess.is_a?(Numeric)
+
+        guess
+      end.to_f
+    end
   end
 end
 

data/lib/finrb/config.rb

@@ -3,9 +3,9 @@
 module Finrb
   include ActiveSupport::Configurable
 
-  default_values = { eps: "1.0e-16", guess: 1.0, business_days: false, periodic_compound: false }
+  default_values = { eps: '1.0e-16', guess: 1.0, business_days: false, periodic_compound: false }
 
   default_values.each do |key, value|
-    config.send("#{key.to_sym}=", value)
+    config.__send__("#{key.to_sym}=", value)
   end
 end

data/lib/finrb/decimal.rb

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
-require "rubygems"
-require "flt"
-include Flt
+require 'flt'
+require 'rubygems'
 
-DecNum.context.define_conversion_from(BigDecimal) do |x, _context|
-  DecNum(x.to_s)
+Flt::DecNum.context.define_conversion_from(BigDecimal) do |x, _context|
+  Flt::DecNum(x.to_s)
 end
 
-DecNum.context.define_conversion_to(BigDecimal) do |x|
+Flt::DecNum.context.define_conversion_to(BigDecimal) do |x|
   BigDecimal(x.to_s)
 end
 
 class Numeric
-  def to_d
-    if instance_of?(DecNum)
+  def to_dec
+    if instance_of?(Flt::DecNum)
       self
     else
-      DecNum(to_s)
+      Flt::DecNum(to_s)
     end
   end
 end