finrb 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0e0f1b32ce469fa5fb2078a6f55e4836c8bbff50918efd593da7934ed3e230
-  data.tar.gz: 58cae9f2f1d746067d98f2ecd17e9c503506f2416559773429e6473a3b5e3f9b
+  metadata.gz: b999dd6faadf24d9020be497526bbf8a2614fbcc994232e84b8d2cc693eb283f
+  data.tar.gz: 5611c3ab6cc8abc69e95fdb58e3d5913c1e47eaaf599f0aa097ba82f1377893b
 SHA512:
-  metadata.gz: 1a98a8c9a19317253db7e464590ce111fb7bdb6a88aca5c29b2e6f30d0378701ebc3d956061d2672e8450a40de883cdf342a04ca3993608bc2726347097064da
-  data.tar.gz: be19a4a46eb02e4f422f690709f13e5800cbeae3be82e7f7d323970333cdbd65eebbb17bf2acab77b23710bd626bafa070454ecdbb1f48d85b4c99a28cd55e18
+  metadata.gz: a631f3777e169081228e91e08f94835780e479a63604828a89c649cf8ca0303d2ef2a9ad11de60376c14bc14d2652e700455523d232d45d4581ddb06b430e8c4
+  data.tar.gz: 74d40ad091e7cc2756e58371ea53bf10ade3b5e6573be78813cfadfb90c67e54d7595bc57947d4b9f5b5b74fb9423dc835a10541144a65b9747c0017f6cb297f

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # finrb changelog
 
+## 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.
@@ -34,6 +34,26 @@ module Finrb
     # @api public
     attr_reader :rates
 
+    # @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 / (((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
@@ -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)
@@ -158,26 +178,6 @@ module Finrb
       @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))

data/lib/finrb/cashflows.rb

@@ -1,11 +1,12 @@
 # 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"
+require 'bigdecimal'
+require 'bigdecimal/newton'
+require 'business_time'
 include Newton
 
 module Finrb
@@ -15,7 +16,7 @@ module Finrb
     # 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
@@ -40,7 +41,7 @@ module Finrb
 
     # 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
+    # @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 +49,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,7 +58,7 @@ 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
@@ -75,7 +76,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 +98,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
 
@@ -120,48 +121,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,7 +3,7 @@
 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)

data/lib/finrb/decimal.rb

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

data/lib/finrb/rates.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "decimal"
+require_relative 'decimal'
 
 module Finrb
   # the Rate class provides an interface for working with interest rates.
@@ -8,6 +8,45 @@ module Finrb
   # @api public
   class Rate
     include Comparable
+    # Accepted rate types
+    TYPES = { apr: 'effective', apy: 'effective', effective: 'effective', nominal: 'nominal' }.freeze
+    # convert a nominal interest rate to an effective interest rate
+    # @return [DecNum] the effective interest rate
+    # @param [Numeric] rate the nominal interest rate
+    # @param [Numeric] periods the number of compounding periods per year
+    # @example
+    #   Rate.to_effective(0.05, 4) #=> DecNum('0.05095')
+    # @api public
+    def self.to_effective(rate, periods)
+      rate = Flt::DecNum.new(rate.to_s)
+      periods = Flt::DecNum.new(periods.to_s)
+
+      if periods.infinite?
+        rate.exp - 1
+      else
+        (((rate / periods) + 1)**periods) - 1
+      end
+    end
+
+    # convert an effective interest rate to a nominal interest rate
+    # @return [DecNum] the nominal interest rate
+    # @param [Numeric] rate the effective interest rate
+    # @param [Numeric] periods the number of compounding periods per year
+    # @example
+    #   Rate.to_nominal(0.06, 365) #=> DecNum('0.05827')
+    # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
+    # @api public
+    def self.to_nominal(rate, periods)
+      rate = Flt::DecNum.new(rate.to_s)
+      periods = Flt::DecNum.new(periods.to_s)
+
+      if periods.infinite?
+        (rate + 1).log
+      else
+        periods * (((rate + 1)**(1.to_f / periods)) - 1)
+      end
+    end
+
     # create a new Rate instance
     # @return [Rate]
     # @param [Numeric] rate the decimal value of the interest rate
@@ -37,9 +76,6 @@ module Finrb
       end
     end
 
-    # Accepted rate types
-    TYPES = { apr: "effective", apy: "effective", effective: "effective", nominal: "nominal" }.freeze
-
     # @return [Integer] the duration for which the rate is valid, in months
     # @api public
     attr_accessor :duration
@@ -52,7 +88,7 @@ module Finrb
 
     # compare two Rates, using the effective rate
     # @return [Numeric] one of -1, 0, +1
-    # @param [Rate] rate the comparison Rate
+    # @param [Rate] other the comparison Rate
     # @example Which is better, a nominal rate of 15% compounded monthly, or 15.5% compounded semiannually?
     #   r1 = Rate.new(0.15, :nominal) #=> Rate.new(0.160755, :apr)
     #   r2 = Rate.new(0.155, :nominal, :compounds => :semiannually) #=> Rate.new(0.161006, :apr)
@@ -125,43 +161,6 @@ module Finrb
       @effective = Rate.to_effective(rate, @periods)
     end
 
-    # convert a nominal interest rate to an effective interest rate
-    # @return [DecNum] the effective interest rate
-    # @param [Numeric] rate the nominal interest rate
-    # @param [Numeric] periods the number of compounding periods per year
-    # @example
-    #   Rate.to_effective(0.05, 4) #=> DecNum('0.05095')
-    # @api public
-    def self.to_effective(rate, periods)
-      rate = Flt::DecNum.new(rate.to_s)
-      periods = Flt::DecNum.new(periods.to_s)
-
-      if periods.infinite?
-        rate.exp - 1
-      else
-        ((1 + (rate / periods))**periods) - 1
-      end
-    end
-
-    # convert an effective interest rate to a nominal interest rate
-    # @return [DecNum] the nominal interest rate
-    # @param [Numeric] rate the effective interest rate
-    # @param [Numeric] periods the number of compounding periods per year
-    # @example
-    #   Rate.to_nominal(0.06, 365) #=> DecNum('0.05827')
-    # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
-    # @api public
-    def self.to_nominal(rate, periods)
-      rate = Flt::DecNum.new(rate.to_s)
-      periods = Flt::DecNum.new(periods.to_s)
-
-      if periods.infinite?
-        (rate + 1).log
-      else
-        periods * (((1 + rate)**(1 / periods)) - 1)
-      end
-    end
-
     private :compounds=, :effective=, :nominal=
   end
 end

data/lib/finrb/transaction.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "decimal"
+require_relative 'decimal'
 
 module Finrb
   # the Transaction class provides a general interface for working with individual cash flows.