finrb 0.0.1

data/finrb.gemspec

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+SPEC =
+  Gem::Specification.new do |s|
+    s.name = 'finrb'
+    s.version = '0.0.1'
+    s.authors = ['Nadir Cohen', 'Martin Bjeldbak Madsen', 'Bill Kranec']
+    s.license = 'LGPL-3.0'
+    s.email = ['nadircs11@gmail.com', 'me@martinbjeldbak.com', 'wkranec@gmail.com']
+    s.platform = Gem::Platform::RUBY
+    s.summary = 'Ruby gem for financial calculations/modeling'
+
+    s.description = <<~EOF
+      The finrb library (forked from the finance gem) provides a Ruby interface for financial calculations/modeling.
+
+      - Working with interest rates
+      - Mortgage amortization
+      - Cashflows (NPV, IRR, etc.)
+      - 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
+
+    EOF
+
+    s.homepage = 'https://rubygems.org/gems/finrb'
+
+    s.required_ruby_version = '>= 3.0'
+
+    s.add_dependency('activesupport')
+    s.add_dependency('business_time')
+    s.add_dependency('flt')
+
+    s.add_development_dependency('minitest')
+    s.add_development_dependency('pry')
+    s.add_development_dependency('rake')
+    s.add_development_dependency('rubocop')
+    s.add_development_dependency('rubocop-minitest')
+    s.add_development_dependency('rubocop-performance')
+    s.add_development_dependency('rubocop-rake')
+    s.add_development_dependency('semver')
+    s.add_development_dependency('solargraph')
+
+    s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+
+    s.extra_rdoc_files = ['README.md', 'COPYING', 'COPYING.LESSER', 'CHANGELOG.md']
+
+    s.metadata['rubygems_mfa_required'] = 'true'
+  end

data/lib/finrb/amortization.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative 'cashflows'
+require_relative 'decimal'
+require_relative 'transaction'
+
+module Finrb
+  # the Amortization class provides an interface for working with loan amortizations.
+  # @note There are _two_ ways to create an amortization.  The first
+  #   example uses the amortize method for the Numeric class.  The second
+  #   calls Amortization.new directly.
+  # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR
+  #   rate = Rate.new(0.0425, :apr, :duration => (30 * 12))
+  #   amortization = 250000.amortize(rate)
+  # @example Borrow $250,000 under a 30 year, adjustable rate loan, with an APR starting at 4.25%, and increasing by 1% every five years
+  #   values = %w{ 0.0425 0.0525 0.0625 0.0725 0.0825 0.0925 }
+  #   rates = values.collect { |value| Rate.new( value, :apr, :duration = (5 * 12) ) }
+  #   arm = Amortization.new(250000, *rates)
+  # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR, but pay $150 extra each month
+  #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
+  #   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)
+    # @api public
+    attr_reader :balance
+    # @return [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
+    # @api public
+    attr_reader :principal
+    # @return [Array] the interest rates used for calculating the amortization
+    # @api public
+    attr_reader :rates
+
+    # create a new Amortization instance
+    # @return [Amortization]
+    # @param [DecNum] principal the initial amount of the loan or investment
+    # @param [Rate] rates the applicable interest rates
+    # @param [Proc] block
+    # @api public
+    def initialize(principal, *rates, &block)
+      @principal = Flt::DecNum.new(principal.to_s)
+      @rates     = rates
+      @block     = block
+
+      # compute the total duration from all of the rates.
+      @periods = rates.sum(&:duration)
+      @period  = 0
+
+      compute
+    end
+
+    # compare two Amortization instances
+    # @return [Numeric] -1, 0, or +1
+    # @param [Amortization]
+    # @api public
+    def ==(other)
+      (principal == other.principal) && (rates == other.rates) && (payments == other.payments)
+    end
+
+    # @return [Array] the amount of any additional payments in each period
+    # @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'), ... ]
+    # @api public
+    def additional_payments
+      @transactions.select(&:payment?).map(&:difference)
+    end
+
+    # amortize the balance of loan with the given interest rate
+    # @return none
+    # @param [Rate] rate the interest rate to use in the amortization
+    # @api private
+    def amortize(rate)
+      # For the purposes of calculating a payment, the relevant time
+      # period is the remaining number of periods in the loan, not
+      # necessarily the duration of the rate itself.
+      periods = @periods - @period
+      amount = Amortization.payment(@balance, rate.monthly, periods)
+
+      pmt = Payment.new(amount, period: @period)
+      pmt.modify(&@block) if @block
+
+      rate.duration.to_i.times do
+        # Do this first in case the balance is zero already.
+        break if @balance.zero?
+
+        # Compute and record interest on the outstanding balance.
+        int = (@balance * rate.monthly).round(2)
+        interest = Interest.new(int, period: @period)
+        @balance += interest.amount
+        @transactions << interest.dup
+
+        # Record payment.  Don't pay more than the outstanding balance.
+        pmt.amount = -@balance if pmt.amount.abs > @balance
+        @transactions << pmt.dup
+        @balance += pmt.amount
+
+        @period += 1
+      end
+    end
+
+    # compute the amortization of the principal
+    # @return none
+    # @api private
+    def compute
+      @balance = @principal
+      @transactions = []
+
+      @rates.each do |rate|
+        amortize(rate)
+      end
+
+      # Add any remaining balance due to rounding error to the last payment.
+      unless @balance.zero?
+        @transactions.reverse.find(&:payment?).amount -= @balance
+        @balance = 0
+      end
+
+      @payment = (payments[0] if @rates.length == 1)
+
+      @transactions.freeze
+    end
+
+    # @return [Integer] the time required to pay off the loan, in months
+    # @example In most cases, the duration is equal to the total duration of all rates
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate)
+    #   amt.duration #=> 360
+    # @example Extra payments may reduce the duration
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt.duration #=> 319
+    # @api public
+    def duration
+      payments.length
+    end
+
+    # @api public
+    def inspect
+      "Amortization.new(#{@principal})"
+    end
+
+    # @return [Array] the amount of interest charged in each period
+    # @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')
+    # @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')
+    # @api public
+    def interest
+      @transactions.select(&:interest?).map(&:amount)
+    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 http://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')
+    # @api public
+    def payments
+      @transactions.select(&:payment?).map(&:amount)
+    end
+  end
+end
+
+class Numeric
+  # @see Amortization#new
+  # @api public
+  def amortize(*rates, &block)
+    Finrb::Amortization.new(self, *rates, &block)
+  end
+end

data/lib/finrb/cashflows.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+require_relative 'rates'
+
+require 'bigdecimal'
+require 'bigdecimal/newton'
+require 'business_time'
+include Newton
+
+module Finrb
+  # 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.each do |key, value|
+        define_method key do
+          BigDecimal(value)
+        end
+      end
+
+      def initialize(transactions, function)
+        @transactions = transactions
+        @function = function
+      end
+
+      def values(x)
+        value = @transactions.send(@function, Flt::DecNum.new(x[0].to_s))
+        begin
+          [BigDecimal(value.to_s)]
+        rescue ArgumentError
+          [0]
+        end
+      end
+    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
+    # @example
+    #   [-4000,1200,1410,1875,1050].irr #=> 0.143
+    # @see http://en.wikipedia.org/wiki/Internal_rate_of_return
+    # @api public
+    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?
+
+      func = Function.new(self, :npv)
+      rate = [valid(guess)]
+      nlsolve(func, rate)
+      rate[0]
+    end
+
+    def method_missing(name, *args, &block)
+      return sum if name.to_s == 'sum'
+
+      super
+    end
+
+    # calculate the net present value of a sequence of cash flows
+    # @return [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
+    # @see http://en.wikipedia.org/wiki/Net_present_value
+    # @api public
+    def npv(rate)
+      cashflows = map { |entry| Flt::DecNum.new(entry.to_s) }
+
+      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)
+      end
+
+      total
+    end
+
+    # calculate the internal rate of return for a sequence of cash flows with dates
+    # @param[Numeric] Initial guess rate, Deafults to 1.0
+    # @return [Rate] the internal rate of return
+    # @example
+    #   @transactions = []
+    #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
+    #   @transactions.xirr(0.6) #=> Rate("0.024851", :apr, :compounds => :annually)
+    # @api public
+    def xirr(guess = nil)
+      # Make sure we have a valid sequence of cash flows.
+      positives, negatives = partition { |t| t.amount >= 0 }
+      if positives.empty? || negatives.empty?
+        raise(
+          ArgumentError,
+          'Calculation does not converge. Cashflow needs to have a least one positive and one negative value.'
+        )
+      end
+
+      func = Function.new(self, :xnpv)
+      rate = [valid(guess)]
+      nlsolve(func, rate)
+      Rate.new(rate[0], :apr, compounds: Finrb.config.periodic_compound ? :continuously : :annually)
+    end
+
+    # calculate the net present value of a sequence of cash flows
+    # @return [DecNum]
+    # @example
+    #   @transactions = []
+    #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
+    #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
+    #   @transactions.xnpv(0.6).round(2) #=> -937.41
+    # @api public
+    def xnpv(rate)
+      rate = Flt::DecNum.new(rate.to_s)
+
+      sum do |t|
+        t.amount / ((1 + rate)**(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
+    end
+
+    def start
+      @start ||= self[0].date
+    end
+
+    def stop
+      @stop ||= self[-1].date.to_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
+
+        Finrb.config.guess
+      else
+        raise(ArgumentError, 'Invalid Guess. Use a [Numeric] value.') unless guess.is_a?(Numeric)
+
+        guess
+      end.to_f
+    end
+  end
+end
+
+class Array
+  include Finrb::Cashflow
+end

data/lib/finrb/config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Finrb
+  include ActiveSupport::Configurable
+
+  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)
+  end
+end

data/lib/finrb/decimal.rb

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

data/lib/finrb/rates.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+
+module Finrb
+  # the Rate class provides an interface for working with interest rates.
+  # {render:Rate#new}
+  # @api public
+  class Rate
+    include Comparable
+    # create a new Rate instance
+    # @return [Rate]
+    # @param [Numeric] rate the decimal value of the interest rate
+    # @param [Symbol] type a valid {TYPES rate type}
+    # @param [optional, Hash] opts set optional attributes
+    # @option opts [String] :duration a time interval for which the rate is valid
+    # @option opts [String] :compounds (:monthly) the number of compounding periods per year
+    # @example create a 3.5% APR rate
+    #   Rate.new(0.035, :apr) #=> Rate(0.035, :apr)
+    # @see http://en.wikipedia.org/wiki/Effective_interest_rate
+    # @see http://en.wikipedia.org/wiki/Nominal_interest_rate
+    # @api public
+    def initialize(rate, type, opts = {})
+      # Default monthly compounding.
+      opts = { compounds: :monthly }.merge(opts)
+
+      # Set optional attributes..
+      opts.each do |key, value|
+        send("#{key}=", value)
+      end
+
+      # Set the rate in the proper way, based on the value of type.
+      begin
+        send("#{TYPES.fetch(type)}=", Flt::DecNum.new(rate.to_s))
+      rescue KeyError
+        raise(ArgumentError, "type must be one of #{TYPES.keys.join(', ')}", caller)
+      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
+    # @return [DecNum] the effective interest rate
+    # @api public
+    attr_reader :effective
+    # @return [DecNum] the nominal interest rate
+    # @api public
+    attr_reader :nominal
+
+    # compare two Rates, using the effective rate
+    # @return [Numeric] one of -1, 0, +1
+    # @param [Rate] rate 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)
+    #   r1 <=> r2 #=> -1
+    # @api public
+    def <=>(other)
+      @effective <=> other.effective
+    end
+
+    # (see #effective)
+    # @api public
+    def apr
+      effective
+    end
+
+    # (see #effective)
+    # @api public
+    def apy
+      effective
+    end
+
+    # a convenience method which sets the value of @periods
+    # @return none
+    # @param [Symbol, Numeric] input the compounding frequency
+    # @raise [ArgumentError] if input is not an accepted keyword or Numeric
+    # @api private
+    def compounds=(input)
+      @periods =
+        case input
+        when :annually     then Flt::DecNum.new(1)
+        when :continuously then Flt::DecNum.infinity
+        when :daily        then Flt::DecNum.new(365)
+        when :monthly      then Flt::DecNum.new(12)
+        when :quarterly    then Flt::DecNum.new(4)
+        when :semiannually then Flt::DecNum.new(2)
+        when Numeric       then Flt::DecNum.new(input.to_s)
+        else raise(ArgumentError)
+        end
+    end
+
+    # set the effective interest rate
+    # @return none
+    # @param [DecNum] rate the effective interest rate
+    # @api private
+    def effective=(rate)
+      @effective = rate
+      @nominal = Rate.to_nominal(rate, @periods)
+    end
+
+    def inspect
+      "Rate.new(#{apr.round(6)}, :apr)"
+    end
+
+    # @return [DecNum] the monthly effective interest rate
+    # @example
+    #   rate = Rate.new(0.15, :nominal)
+    #   rate.apr.round(6) #=> DecNum('0.160755')
+    #   rate.monthly.round(6) #=> DecNum('0.013396')
+    # @api public
+    def monthly
+      (effective / 12).round(15)
+    end
+
+    # set the nominal interest rate
+    # @return none
+    # @param [DecNum] rate the nominal interest rate
+    # @api private
+    def nominal=(rate)
+      @nominal = rate
+      @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 http://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