finrb 1.1.0 → 1.3.0

data/lib/finrb/yields.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Money-market yield and interest-rate conversion calculations.
@@ -14,9 +15,9 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy(d=1500,f=100000,t=120)
     def self.bdy(d:, f:, t:)
-      d = Flt::DecNum(d.to_s)
-      f = Flt::DecNum(f.to_s)
-      t = Flt::DecNum(t.to_s)
+      d = Validation.decimal(d, name: 'dollar discount')
+      f = Validation.positive_decimal(f, name: 'face value', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (d * 360 / f / t)
     end
@@ -28,10 +29,12 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy2mmy(bdy=0.045,t=120)
     def self.bdy2mmy(bdy:, t:)
-      bdy = Flt::DecNum(bdy.to_s)
-      t = Flt::DecNum(t.to_s)
+      bdy = Validation.decimal(bdy, name: 'bank discount yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
+      denominator = 360 - (t * bdy)
+      raise(DomainError, 'Bank discount yield and time to maturity must imply a positive purchase price.') unless denominator.positive?
 
-      (bdy * 360 / (360 - (t * bdy)))
+      (bdy * 360 / denominator)
     end
 
     # Convert stated annual rate to the effective annual rate
@@ -44,10 +47,10 @@ module Finrb
     # @example
     #   Finrb::Yields.ear(0.04,365)
     def self.ear(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      ((((r / m) + 1)**m) - 1)
+      ((compounding_base(r, m)**m) - 1)
     end
 
     # Convert stated annual rate to the effective annual rate with continuous compounding
@@ -59,7 +62,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear_continuous(0.03)
     def self.ear_continuous(r:)
-      r = Flt::DecNum(r.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
 
       (r.exp - 1)
     end
@@ -70,7 +73,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2bey(ear=0.08)
     def self.ear2bey(ear:)
-      ear = Flt::DecNum(ear.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
 
       (((ear + 1).sqrt - 1) * 2)
     end
@@ -82,8 +85,8 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2hpr(ear=0.05039,t=150)
     def self.ear2hpr(ear:, t:)
-      ear = Flt::DecNum(ear.to_s)
-      t = Flt::DecNum(t.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((ear + 1)**(t / 365)) - 1)
     end
@@ -124,18 +127,18 @@ module Finrb
     #   # monthly proportional interest rate which is equivalent to a simple annual interest
     #   Finrb::Yields.eir(r=0.05,p=12,type='p')
     def self.eir(r:, n: 1, p: 12, type: 'e')
-      r = Flt::DecNum(r.to_s)
-      n = Flt::DecNum(n.to_s)
-      p = Flt::DecNum(p.to_s)
+      r = Validation.decimal(r, name: 'annual rate')
+      n = Validation.positive_decimal(n, name: 'source compounding periods', error: DomainError)
+      p = Validation.positive_decimal(p, name: 'target compounding periods', error: DomainError)
       type = type.to_s
 
       case type
       when 'e'
-        eir = (((r / n) + 1)**(n / p)) - 1
+        eir = (compounding_base(r, n)**(n / p)) - 1
       when 'p'
         eir = r / p
       else
-        raise(Error, "type must be 'e' or 'p'")
+        raise(ArgumentError, "conversion type must be 'e' (equivalent) or 'p' (proportional)")
       end
       eir
     end
@@ -147,8 +150,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2bey(hpr=0.02,t=3)
     def self.hpr2bey(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       ((((hpr + 1)**(6 / t)) - 1) * 2)
     end
@@ -160,8 +163,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2ear(hpr=0.015228,t=120)
     def self.hpr2ear(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((hpr + 1)**(365 / t)) - 1)
     end
@@ -173,8 +176,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2mmy(hpr=0.01523,t=120)
     def self.hpr2mmy(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal(hpr, name: 'holding period return')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (hpr * 360 / t)
     end
@@ -186,8 +189,8 @@ module Finrb
     # @example
     #   Finrb::Yields.mmy2hpr(mmy=0.04898,t=150)
     def self.mmy2hpr(mmy:, t:)
-      mmy = Flt::DecNum(mmy.to_s)
-      t = Flt::DecNum(t.to_s)
+      mmy = Validation.decimal(mmy, name: 'money market yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (mmy * t / 360)
     end
@@ -199,10 +202,10 @@ module Finrb
     # @example
     #   Finrb::Yields.r_continuous(r=0.03,m=4)
     def self.r_continuous(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'nominal rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      (m * ((r / m) + 1).log)
+      (m * compounding_base(r, m).log)
     end
 
     # Convert a given continuous compounded rate to a norminal rate
@@ -215,10 +218,18 @@ module Finrb
     # @example
     #   Finrb::Yields.r_norminal(rc=0.03,m=4)
     def self.r_norminal(rc:, m:)
-      rc = Flt::DecNum(rc.to_s)
-      m = Flt::DecNum(m.to_s)
+      rc = Validation.decimal(rc, name: 'continuously compounded rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
       (m * ((rc / m).exp - 1))
     end
+
+    def self.compounding_base(rate, periods)
+      base = (rate / periods) + 1
+      raise(DomainError, 'The rate per compounding period must be greater than -1.') unless base.positive?
+
+      base
+    end
+    private_class_method :compounding_base
   end
 end

data/lib/finrb.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 require 'finrb/accounting'
+require 'finrb/calendars'
 require 'finrb/cashflows'
 require 'finrb/config'
+require 'finrb/day_count'
 require 'finrb/decimal'
 require 'finrb/errors'
 require 'finrb/precision'
 require 'finrb/ratios'
 require 'finrb/returns'
+require 'finrb/schedule'
 require 'finrb/tvm'
 require 'finrb/version'
 require 'finrb/yields'
@@ -23,6 +26,7 @@ FinrbError = Finrb::Error
 #  * *rate* represents the interest rate _per period_.
 module Finrb
   autoload :Amortization, 'finrb/amortization'
+  autoload :FixedRateBond, 'finrb/fixed_rate_bond'
   autoload :Rate,         'finrb/rates'
   autoload :Transaction,  'finrb/transaction'
 end

data/sig/finrb.rbs

@@ -42,9 +42,104 @@ module Finrb
   class DomainError < Error
   end
 
+  module Calendars
+    type convention = :following | :modified_following | :preceding | :modified_preceding | :half_month_modified_following | :nearest | :unadjusted
+
+    class Base
+      CONVENTIONS: Array[Symbol]
+
+      def initialize: (?additional_holidays: Array[Date], ?removed_holidays: Array[Date]) -> void
+      def additional_holidays: () -> Array[Date]
+      def removed_holidays: () -> Array[Date]
+      def business_day?: (Date) -> bool
+      def holiday?: (Date) -> bool
+      def holiday_names: (Date) -> Array[String]
+      def holidays_between: (Date, Date, ?include_weekends: bool) -> Hash[Date, Array[String]]
+      def adjust: (Date, convention: convention) -> Date
+      def advance: (Date, business_days: Integer, ?convention: convention) -> Date
+      def ==: (untyped) -> bool
+      def eql?: (untyped) -> bool
+      def hash: () -> Integer
+    end
+
+    class USFederalReserve < Base
+      SUPPORTED_START_DATE: Date
+      SUPPORTED_END_DATE: Date
+      SUPPORTED_DATE_RANGE: Range[Date]
+      def name: () -> String
+    end
+
+    class IsraelTase < Base
+      SUPPORTED_START_DATE: Date
+      SUPPORTED_END_DATE: Date
+      SUPPORTED_DATE_RANGE: Range[Date]
+      TRADING_WEEK_CHANGE: Date
+      def name: () -> String
+    end
+  end
+
+  module DayCount
+    type convention = :actual_365_fixed | :actual_360 | :actual_actual_icma
+    CONVENTIONS: Array[convention]
+    DEFAULT: convention
+
+    def self.year_fraction: (Date, Date, ?convention: convention, ?reference_period_start: Date?, ?reference_period_end: Date?, ?frequency: Integer?) -> decimal
+  end
+
+  class Schedule
+    type frequency = :monthly | :quarterly | :semiannual | :annual
+    type stub = :none | :short_final
+
+    FREQUENCY_MONTHS: Hash[frequency, Integer]
+    STUB_CONVENTIONS: Array[stub]
+
+    class Period
+      def initialize: (index: Integer, accrual_start_date: Date, unadjusted_payment_date: Date, payment_date: Date, ?stub: stub?) -> void
+      def index: () -> Integer
+      def accrual_start_date: () -> Date
+      def unadjusted_payment_date: () -> Date
+      def payment_date: () -> Date
+      def stub: () -> stub?
+      def short_final_stub?: () -> bool
+    end
+
+    def self.from_months: (start_date: Date, term_months: Integer, ?frequency: frequency, ?stub: stub, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> Schedule
+    def initialize: (start_date: Date, maturity_date: Date, ?frequency: frequency, ?stub: stub, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> void
+    def start_date: () -> Date
+    def maturity_date: () -> Date
+    def frequency: () -> frequency
+    def stub: () -> stub
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def periods: () -> Array[Period]
+    def payment_dates: () -> Array[Date]
+    def unadjusted_payment_dates: () -> Array[Date]
+  end
+
   class InvalidCashflowError < Error
   end
 
+  class FixedRateBond
+    type price_type = :clean | :dirty
+    PRICE_TYPES: Array[price_type]
+
+    def initialize: (face_value: number, coupon_rate: number, issue_date: Date, maturity_date: Date, ?frequency: Schedule::frequency, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> void
+    def face_value: () -> decimal
+    def coupon_rate: () -> decimal
+    def issue_date: () -> Date
+    def maturity_date: () -> Date
+    def frequency: () -> Schedule::frequency
+    def schedule: () -> Schedule
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def day_count: () -> :actual_actual_icma
+    def cashflows: (settlement_date: Date) -> Array[Transaction]
+    def accrued_interest: (settlement_date: Date) -> decimal
+    def dirty_price: (settlement_date: Date, yield_rate: number) -> decimal
+    def clean_price: (settlement_date: Date, yield_rate: number) -> decimal
+    def yield_to_maturity: (settlement_date: Date, price: number, ?price_type: price_type, ?guess: number) -> decimal
+  end
+
   module Precision
     def self.money: (number) -> decimal
     def self.rate: (number) -> decimal
@@ -94,8 +189,14 @@ module Finrb
   end
 
   class Amortization
+    type frequency = :monthly | :quarterly | :semiannual | :annual
+    type stub = :none | :short_final
+
+    FREQUENCY_MONTHS: Hash[frequency, Integer]
+    STUB_CONVENTIONS: Array[stub]
+
     class Entry
-      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number) -> void
+      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number, ?date: Date?) -> void
       def period: () -> Integer
       def opening_balance: () -> decimal
       def payment: () -> decimal
@@ -106,15 +207,16 @@ module Finrb
       def interest_only: () -> bool
       def interest_only?: () -> bool
       def closing_balance: () -> decimal
+      def date: () -> Date?
       def ==: (untyped) -> bool
       def eql?: (untyped) -> bool
       def hash: () -> Integer
-      def to_h: () -> Hash[Symbol, Integer | decimal]
+      def to_h: () -> Hash[Symbol, Integer | decimal | bool | Date]
     end
 
     def self.payment: (number, number, Integer, ?balloon: number) -> decimal
 
-    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool) ?{ (Transaction) -> number } -> void
+    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool, ?start_date: Date?, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?, ?day_count: DayCount::convention, ?frequency: frequency, ?stub: stub) ?{ (Transaction) -> number } -> void
     def ==: (untyped) -> bool
     def balance: () -> decimal
     def balloon: () -> decimal
@@ -128,7 +230,14 @@ module Finrb
     def principal: () -> decimal
     def rates: () -> Array[Rate]
     def schedule: () -> Array[Entry]
+    def start_date: () -> Date?
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def day_count: () -> DayCount::convention
+    def frequency: () -> frequency
+    def stub: () -> stub
     def additional_payments: () -> Array[decimal]
+    def cashflow_yield: (?number) -> Rate
     def duration: () -> Integer
     def inspect: () -> String
     def interest: () -> Array[decimal]
@@ -150,7 +259,7 @@ module Finrb
   end
 
   module TVM
-    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?lower: number, ?upper: number) -> decimal
+    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?guess: number?, ?lower: number?, ?upper: number?) -> decimal
     def self.fv: (r: number, n: number, ?pv: number, ?pmt: number, ?type: Integer) -> decimal
     def self.fv_annuity: (r: number, n: number, pmt: number, ?type: Integer) -> decimal
     def self.fv_simple: (r: number, n: number, pv: number) -> decimal
@@ -169,7 +278,7 @@ module Finrb
   module Accounting
     type inventory_result = { cost_of_goods: decimal, ending_inventory: decimal }
 
-    def self.cogs: (uinv: number, pinv: number, units: number | numbers, price: number | numbers, sinv: number, ?method: String) -> inventory_result
+    def self.cogs: (uinv: number, pinv: number, units: number | numbers | nil, price: number | numbers | nil, sinv: number, ?method: String | Symbol) -> inventory_result
     def self.ddb: (cost: number, rv: number, t: Integer) -> { t: Array[Integer], ddb: Array[decimal] }
     def self.slde: (cost: number, rv: number, t: number) -> decimal
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finrb
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Nadir Cohen
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -248,26 +262,36 @@ extra_rdoc_files:
 - README.md
 files:
 - CHANGELOG.md
+- CONTRIBUTING.md
 - COPYING
 - COPYING.LESSER
 - NOTICE.md
 - README.md
+- SECURITY.md
 - lib/finrb.rb
 - lib/finrb/accounting.rb
 - lib/finrb/amortization.rb
+- lib/finrb/calendars.rb
+- lib/finrb/calendars/base.rb
+- lib/finrb/calendars/hebrew_calendar.rb
+- lib/finrb/calendars/israel_tase.rb
+- lib/finrb/calendars/us_federal_reserve.rb
 - lib/finrb/cashflows.rb
 - lib/finrb/config.rb
 - lib/finrb/core_ext.rb
 - lib/finrb/core_ext/array.rb
 - lib/finrb/core_ext/numeric.rb
+- lib/finrb/day_count.rb
 - lib/finrb/decimal.rb
 - lib/finrb/errors.rb
+- lib/finrb/fixed_rate_bond.rb
 - lib/finrb/numerical/brent.rb
 - lib/finrb/numerical/rate_search.rb
 - lib/finrb/precision.rb
 - lib/finrb/rates.rb
 - lib/finrb/ratios.rb
 - lib/finrb/returns.rb
+- lib/finrb/schedule.rb
 - lib/finrb/transaction.rb
 - lib/finrb/tvm.rb
 - lib/finrb/validation.rb
@@ -297,7 +321,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Precision-first financial mathematics for Ruby
 test_files: []