istox 0.2.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 177c19f4e1837c38552a01345f4df0ed0b6d75489c3ff7ac7cee4e6ae5300e9d
-  data.tar.gz: bc1e0d56a7c66ebbbb11f2408e8dfbbec8fad3bb056eafd08ca89aa3b7af712c
+  metadata.gz: 5d4f2a0587825e06d3ff6a6a3ad516f20b90f1ca7e59e11d686b03c892b8c441
+  data.tar.gz: 3b6f8c0f67615b5165f9030343e0713f2b4562109632f93306ebb6a412d87aeb
 SHA512:
-  metadata.gz: 3b4c6ea1b0f4dade5ce454996d6d72c454560d641a4bba722385db12da19e8531bc6fcab904cb372b664ec3952047510942b92da16bf3ab3dcc28bbde685d603
-  data.tar.gz: 5d5e23ac455354401407c93507526fb616e4d7fba272e4883f7a142c86f0bff8c282101aec833b63ae810e90f914c8a273825306673de9c40f6e96908a6123fd
+  metadata.gz: 6fb65f68fed5082be9d4b8ecd73547a06cc77224baf3e57296974768351127c0d39dc51d063c7855d38921bb7ca4925a1edd36eb097747ceb7da83bd1568379f
+  data.tar.gz: 0be64c5925913cd5fad7242bc0604bf2f553f3d69a5969c1d3165571967d570d8cd2380d8b57b9e15b1af230b2c2f8a516c0bdd59ce59b9a8f9688d948b7406c

data/lib/istox/quant/bond.rb

@@ -12,45 +12,87 @@ module Istox
 
       DEFAULT_APPROXIMATION_ERROR = 0.00001
 
-      def initialize(coupon: nil, maturity_date: nil, years: nil, coupon_frequency: nil, coupon_payment_dates: nil, face_value: 100, days_of_year: 365)
-        raise "Invalid coupon #{coupon}" if (coupon.nil? || !is_number?(coupon))
+      def initialize(coupon: nil, maturity_date: nil, start_date: nil, coupon_frequency: nil, coupon_payment_dates: nil, face_value: 100, days_of_year: 365)
+        raise "Invalid coupon #{coupon}" if (coupon.nil? || !is_number?(coupon)) || coupon < 0
         raise "Invalid maturity_date #{maturity_date}" if (maturity_date.nil? || maturity_date.methods.include?("strftime"))
-        raise "Invalid years #{years}" if (years.nil? || !is_number?(years))
-        raise "Invalid coupon_frequency #{days_of_year}" if (coupon_frequency.nil? || !is_number?(coupon))
-        raise "Invalid coupon_payment_dates #{coupon_payment_dates}" if (coupon_payment_dates.nil? || coupon_payment_dates.count == 0 || coupon_payment_dates.any? { |date| date > maturity_date.to_date })
+        raise "Invalid start_date #{start_date}" if (start_date.nil? || start_date.methods.include?("strftime"))
+        raise "Invalid coupon_frequency #{coupon_frequency}" if (coupon_frequency.nil? || !coupon_frequency.is_a?(Integer) || coupon_frequency < 0)
+        raise "Invalid coupon_payment_dates #{coupon_payment_dates}" if (coupon_payment_dates.nil? || (coupon_payment_dates.count == 0 && coupon_frequency != 0) || coupon_payment_dates.any? { |date| date > maturity_date.to_date })
         raise "Invalid days_of_year #{days_of_year}" if (days_of_year != 365 && days_of_year != 360)
+        raise "start_date is not before maturity_date" if start_date>=maturity_date
 
         @coupon               = coupon.to_d
         @maturity_date        = maturity_date.to_date
-        @years                = years
-        @coupon_frequency     = coupon_frequency.to_d
+        @coupon_frequency     = coupon_frequency.to_i # if this is 0, it means zero coupon
         @days_of_year         = days_of_year.to_d
-        @face_value           = face_value
-        @coupon_payment_dates = coupon_payment_dates.map(&:to_date).sort
-        @start_date           = (@maturity_date-(years*12).to_i.months)
+        @face_value           = face_value.to_d
+        @coupon_payment_dates = coupon_payment_dates.map(&:to_date).uniq.sort
+        # note here we work out the start date based on maturity date and nunber of years
+        @start_date           = start_date.to_date
+
+        @pay_accrued_interest = false
+        @coupon_payment_dates_include_accrued_interest = false
+        if !is_zero_coupon?
+          if @coupon_payment_dates.include?(@maturity_date)
+            # maturity date is a coupon payment date, check if this should
+            # be accrued interest or last normal coupon
+            if @coupon_payment_dates.count > 1
+              previous_coupon_date = @coupon_payment_dates[@coupon_payment_dates.count-2]
+              next_coupon_date = add_month(previous_coupon_date, -(12/@coupon_frequency).to_i)
+              # If maturity date is a normal coupon payment, the theorecical next_coupon_date
+              # calculated from previous coupon payment should be the maturity date, to be safe,
+              # we allow 3 days difference
+              if (next_coupon_date - @maturity_date).abs <= 3
+                @pay_accrued_interest = false
+                @coupon_payment_dates_include_accrued_interest = false
+              else
+                @pay_accrued_interest = true
+                @coupon_payment_dates_include_accrued_interest = true
+              end
+            else
+              # maturity date is only coupon payment date, shouldn't be accrued interest!
+              @pay_accrued_interest = false
+              @coupon_payment_dates_include_accrued_interest = false
+            end
+          else
+            # maturity date is not included in coupon payment date, consider 
+            # this needs to pay accrued interest
+            @pay_accrued_interest = true
+            @coupon_payment_dates_include_accrued_interest = false
+          end
+        end
+
+        log.info "Bond info: start_date=#{@start_date} maturity_date=#{@maturity_date} days_of_years=#{days_of_year} coupon=#{@coupon} coupon_frequency=#{coupon_frequency} face_value=#{@face_value} coupon_payment_dates=#{@coupon_payment_dates} pay_accrued_interest=#{@pay_accrued_interest} coupon_payment_dates_include_accrued_interest=#{@coupon_payment_dates_include_accrued_interest}"
       end
 
       def price(ytm, date, ex_coupon_date: nil, fees: 0)
-        # price_for_irr(irr_from_ytm(ytm), date, fees: fees)
-        price = price_for_irr(ytm/@coupon_frequency, date, ex_coupon_date: ex_coupon_date, fees: fees)
+        irr = ytm
+        irr = ytm/@coupon_frequency if !is_zero_coupon?
+        price = price_for_irr(irr, date, ex_coupon_date: ex_coupon_date, fees: fees)
         price
       end
 
-      # def interest_payments(from_date)
-      #   payments = []
-      #   date = @maturity_date
-      #   while date >= from_date
-      #     payments << date
-      #     date = date.prev_month(12/@coupon_frequency)
-      #   end
-      #   payments.sort
-      # end
+      def ytm(date, ex_coupon_date: nil, price: 100, fees: 0, approximation_error: DEFAULT_APPROXIMATION_ERROR)
+        if !is_zero_coupon? && price == @face_value && date <= @start_date
+          # for non zero coupon bond, if price is face value and date is at or before start date
+          # YTM is simply the coupon rate
+          return @coupon
+        end
+        ytm_down, ytm_up = ytm_limits(price, date, ex_coupon_date: ex_coupon_date, fees: fees)
+        approximate_ytm(ytm_down, ytm_up, price, date, ex_coupon_date: ex_coupon_date, fees: fees, approximation_error: approximation_error)
+      end
+
+
+      private
 
       def coupon_payments(from_date)
         payments = []
 
         @coupon_payment_dates.each do |payment_date|
-          if payment_date > from_date
+          # if from_date falls on coupon payment date or maturity date, we 
+          # still add them to make it easy for calculation later
+          # just that the first coupon will not pay actually (i.e. 0)
+          if payment_date >= from_date && payment_date <= @maturity_date
             payments << payment_date
           end
         end
@@ -58,29 +100,25 @@ module Istox
         payments.sort
       end
 
-      def ytm(date, ex_coupon_date: nil, price: 100, fees: 0, approximation_error: DEFAULT_APPROXIMATION_ERROR)
-        ytm_down, ytm_up = ytm_limits(price, date, ex_coupon_date: ex_coupon_date, fees: fees)
-        approximate_ytm(ytm_down, ytm_up, price, date, ex_coupon_date: ex_coupon_date, fees: fees, approximation_error: approximation_error)
-      end
-
-
-      private
-
       def is_365?
         @days_of_year == 365.to_d
       end
 
-      def add_month(mydate, n)
-        if mydate.month != mydate.next_day.month 
+      def is_zero_coupon?
+        @coupon == 0
+      end
+
+      def add_month(my_date, n)
+        if is_month_end?(my_date)
           # month end
-          (mydate.next_day + n.month).prev_day
+          (my_date.next_day + n.month).prev_day
         else
-          mydate.next_day + n.month
+          my_date.next_day + n.month
         end
       end
 
-      def is_month_end?(mydate)
-        mydate.month != mydate.next_day.month 
+      def is_month_end?(my_date)
+        my_date.month != my_date.next_day.month 
       end
 
       def is_number?(val)
@@ -107,111 +145,160 @@ module Istox
         [ytm_down, ytm_up]
       end
 
-      # def price_for_irr(irr, date, fees: 0)
-      #   raise "Date is after maturity_date!" if date > @maturity_date
-      #   last = date
-      #   interest_payments(date).map do |payday|
-      #     interest = @coupon * @face_value * ((payday-last)/@days_of_year)
-      #     interest += @face_value if payday == @maturity_date
-      #     last = payday
-      #     interest / ((1+irr) ** ((payday-date)/@days_of_year))
-      #   end.inject(:+) / (1+fees)
-      # end
-
       def price_for_irr(irr, date, ex_coupon_date: nil, fees: 0)
         date = date.to_date
         raise "Date is after maturity_date!" if date > @maturity_date
+        # if today is maturity, price is face value (without including any coupon/accrued interest)
+        # BizOps said we will always have an ex_coupon_date when it's close
+        # to coupon payment date but not too early, so the fomula needs to 
+        # accept nil value. Even if we have ex_coupon_date as maturity date,
+        # buyer is not eligible to receive the coupon, so no need to check ex_coupon_date here
+        if date == @maturity_date
+          return @face_value
+        end
+
         if date <= @start_date
           date = @start_date
         end
-        last_coupon_payday = @coupon_payment_dates.last
-        payment_dates = coupon_payments(date)
         
-        if payment_dates.count == 0
-          # no more coupon payments, we do only 1 discount of accrued interest and face value to the current date
+        # it's supporting 365 actual days only at the moment
+        if is_zero_coupon?
+          total_days = @maturity_date - date
+          no_of_years = total_days / 365
+          remainder_days = total_days % 365
+
+          return @face_value/(1+irr)**no_of_years/(1+irr*remainder_days/365)
+        end
+
+        payment_dates = coupon_payments(date)
+
+        no_regular_coupon_before_maturity = false
+        if payment_dates.count == 0 || (payment_dates.count == 1 && payment_dates.first == @maturity_date)
+          no_regular_coupon_before_maturity = true
+        end
+
+        if no_regular_coupon_before_maturity
+          discount_factor = nil
           if is_365?
-            discount_factor = 1.0/(1+irr*(@maturity_date-date)/accrued_interest_discount_days)
+            previous_coupon_date = previous_coupon_date_before_maturity
+            next_coupon_date = add_month(previous_coupon_date, (12/@coupon_frequency).to_i)
+            discount_factor = 1.0/(1+irr*(@maturity_date-date)/(next_coupon_date-previous_coupon_date))
           else
             discount_factor = 1.0/(1+irr*@coupon_frequency*day_count_factor(date, @maturity_date, nil))
           end
-          discounted_accrued_interest = @coupon*@face_value*accrued_interest_factor*discount_factor
-          discounted_face_value = @face_value*discount_factor
-          price = discounted_accrued_interest + discounted_face_value
+
+          if @pay_accrued_interest
+            # accrued interest + face value discounted to the current date
+            discounted_accrued_interest = 0
+            if ex_coupon_date.nil? || ex_coupon_date == @maturity_date
+              discounted_accrued_interest = @coupon*@face_value*accrued_interest_factor*discount_factor
+            end
+            discounted_face_value = @face_value*discount_factor
+            price = discounted_accrued_interest + discounted_face_value
+            return price
+          else
+            discounted_last_coupon = 0
+            if ex_coupon_date.nil? || ex_coupon_date == @maturity_date
+              discounted_last_coupon = @coupon*@face_value/@coupon_frequency*discount_factor
+            end
+            discounted_face_value = @face_value*discount_factor
+            price = discounted_last_coupon + discounted_face_value
+            return price
+          end
         else
-          # we discount face value and coupons and accrued interest (coupon) at maturity (if any)
-          # to the first coupon payment left, and then discount the total to current date
+          # there are at least 1 more regular coupon payment before maturity
+          # we discount face value and coupons or accrued interest if any
+          # to the first coupon payment date left, and then discount the total to current date
           value_at_first_coupon = 0.to_d
-          if payment_dates.include?(@maturity)
-            # last coupon payment is at maturity
-            discount_factor = 1.0/(1+irr)**(payment_dates.count-1)
-            value_at_first_coupon = @face_value*discount_factor
-          else
-            period = @coupon_payment_dates.include?(date) ? payment_dates.count : payment_dates.count-1
-            # last coupon is not at maturity, need to add accrued interest (coupon)
-            discount_factor = 1.0/((1+irr)**period)/(1+irr*@coupon_frequency*accrued_interest_factor)
+          # this is the discount period excluding the one at maturity date
+          # e.g. payment_dates has date1, date2, maturity, we need to discount 
+          # to date1, excluding the period from date2 to maturity, period = 1 (i.e. from date2 to date1)
+          no_of_discount_period = 0 
+          if @pay_accrued_interest
+            if @coupon_payment_dates_include_accrued_interest
+              no_of_discount_period = payment_dates.count-2
+            else
+              no_of_discount_period = payment_dates.count-1
+            end
+            
+            discount_factor = 1.0/((1+irr)**no_of_discount_period)/(1+irr*@coupon_frequency*accrued_interest_factor)
             discounted_accrued_interest = @coupon*@face_value*accrued_interest_factor*discount_factor
             discounted_face_value = @face_value*discount_factor
             value_at_first_coupon = discounted_accrued_interest + discounted_face_value
-          end  
+          else
+            # last coupon payment is at maturity
+            no_of_discount_period = payment_dates.count-1
+            discount_factor = 1.0/(1+irr)**(no_of_discount_period+1)
+            discounted_last_coupon = @coupon*@face_value/@coupon_frequency*discount_factor
+            discounted_face_value = @face_value*discount_factor
+            value_at_first_coupon = discounted_last_coupon + discounted_face_value
+          end
 
-          # first coupon can be pro-rata
-          value_at_first_coupon += first_coupon(date, ex_coupon_date)
-          if payment_dates.count >= 1
-            if @coupon_payment_dates.include?(date)
-              # today is on one of the coupon payment date, the coupon will not be payed today
-              # discount all coupon payments to first coupon date
-              for n in 1..payment_dates.count do
-                value_at_first_coupon += @coupon*@face_value/@coupon_frequency/(1+irr)**n    
-              end
-            else
-              # discount all coupon payments excluding first one to first coupon date
-              for n in 1..payment_dates.count-1 do
-                value_at_first_coupon += @coupon*@face_value/@coupon_frequency/(1+irr)**n    
-              end
-            end
+          if no_of_discount_period >= 1
+            # discount all coupon payments excluding first one to first coupon date
+            for n in 1..no_of_discount_period do
+              value_at_first_coupon += @coupon*@face_value/@coupon_frequency/(1+irr)**n    
+            end  
           end
 
+          # first coupon, can be pro-rated, check the logic in first_coupon
+          value_at_first_coupon += first_coupon(date, ex_coupon_date)
+
           if @coupon_payment_dates.include?(date)
             # today is one of the coupon payment, no need to discount
             price = value_at_first_coupon
           else
             # discount value at first coupon date to present value
             if is_365?
-              price = value_at_first_coupon/(1+irr*(payment_dates.first-date)/first_coupon_discount_days(date))/(1+fees)
+              previous_coupon_date = add_month(payment_dates.first, -(12/@coupon_frequency).to_i)
+              price = value_at_first_coupon/(1+irr*(payment_dates.first-date)/(payment_dates.first-previous_coupon_date))/(1+fees)
             else
               price = value_at_first_coupon/(1+irr*@coupon_frequency*day_count_factor(date, payment_dates.first, nil))/(1+fees)
             end   
           end
+          return price
         end
-
       end
 
       def first_coupon(date, ex_coupon_date)
-        if @coupon_payment_dates.include?(date) || (!ex_coupon_date.nil? && date > ex_coupon_date.to_date)
-          # if today is on coupon payment date, we won't include the coupon 
-          # as by default it's passing ex_coupon_date in our calculation
-          # after ex coupon date, buyer won't receive next coupon
+        # BizOps said we will always have an ex_coupon_date when it's close
+        # to coupon payment date but not too early, so the fomula needs to 
+        # accept nil value. 
+        if !ex_coupon_date.nil? && date >= ex_coupon_date.to_date
+          # on or after ex coupon date, buyer won't receive next coupon
+          return 0.to_d
+        elsif @coupon_payment_dates.include?(date)
+          # if today is a coupon payment date, for sure it will pass ex_coupon_date
+          # and buyer won't receive this coupon. In case ex_coupon_date is nil,
+          # that's the same assumption, so first_coupon will be 0
           return 0.to_d
         end
         
         coupon = @coupon*@face_value/@coupon_frequency
-        if date <= @coupon_payment_dates.first
+        # For the very first coupon, we need to check if it needs to be pro-rated 
+        if date <= @coupon_payment_dates.first && @pay_accrued_interest
           coupon = @coupon*@face_value*first_coupon_factor
         end
         coupon
       end
 
-      def accrued_interest_discount_days
-        # the days between last coupon payment date and the next coupon payment date if maturity was longer
-        last_coupon_payday = @coupon_payment_dates.last
-        (add_month(last_coupon_payday, (12/@coupon_frequency).to_i) - last_coupon_payday).to_i
-      end
+      def previous_coupon_date_before_maturity
+        previous_coupon_date = @start_date
+        if @coupon_payment_dates.include?(@maturity_date)
+          # maturity date is in coupon payment dates, get the previous coupon date
+          # if there is no more date, use the default start date
+          if @coupon_payment_dates.count > 1
+            previous_coupon_date = @coupon_payment_dates[@coupon_payment_dates.count-2]
+          end
+        else
+          # maturity date is not in coupon payment dates, get the last coupon date
+          # if there is no more date, use the default start date
+          if @coupon_payment_dates.count > 0
+            previous_coupon_date = @coupon_payment_dates.last
+          end
+        end
 
-      def first_coupon_discount_days(date)
-        # first coupon date is based on current date
-        payment_dates = coupon_payments(date)
-        first_coupon_date = payment_dates.first
-        (first_coupon_date - add_month(first_coupon_date, -(12/@coupon_frequency).to_i)).to_i
+        return previous_coupon_date
       end
 
       def first_coupon_factor
@@ -227,6 +314,13 @@ module Istox
 
       def accrued_interest_factor
         date1 = @coupon_payment_dates.last
+        if @coupon_payment_dates_include_accrued_interest
+          if @coupon_payment_dates.count > 1
+            date1 = @coupon_payment_dates[@coupon_payment_dates.count-2]
+          else
+            raise "coupon_payment_dates count < 2 and we have accrued interest payment date included!!!"
+          end
+        end
         date2 = @maturity_date
         date3 = add_month(date1, (12/@coupon_frequency).to_i)
         day_count_factor(date1, date2, date3)
@@ -234,8 +328,10 @@ module Istox
 
       def day_count_factor(date1, date2, date3)
         if is_365?
+          # Actual/365
           (date2 - date1)/(date3 - date1)/@coupon_frequency
         else
+          # 30/360
           d1 = [date1.day, 30].min
           d2 = date2.day
           if d1 == 30 

data/lib/istox/version.rb

@@ -1,3 +1,3 @@
 module Istox
-  VERSION = '0.2.1'.freeze
+  VERSION = '0.2.4'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: istox
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.4
 platform: ruby
 authors:
 - Siong Leng
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-10 00:00:00.000000000 Z
+date: 2021-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print