RQuantLib (version 0.4.24)

FixedRateBond: Fixed-Rate bond pricing

Description

The FixedRateBond function evaluates a fixed rate bond using discount curve, the yield or the clean price. More specificly, when a discount curve is provided the calculation is done by DiscountingBondEngine from QuantLib. The NPV, clean price, dirty price, accrued interest, yield, duration, actual settlement date and cash flows of the bond is returned. When a yield is provided instead, no engine is provided to the bond class and prices are computed from yield. In the latter case, NPV is set to NA. Same situation when the clean price is given instead of discount curve or yield. For more detail, see the source codes in QuantLib's file test-suite/bond.cpp.

The FixedRateBondPriceByYield function calculates the theoretical price of a fixed rate bond from its yield.

The FixedRateBondYield function calculates the theoretical yield of a fixed rate bond from its price.

Usage

# S3 method for default
FixedRateBond(bond, rates, schedule,
                                calc=list(dayCounter='ActualActual.ISMA',
                                          compounding='Compounded',
                                          freq='Annual',
                                          durationType='Modified'),
                                discountCurve = NULL, yield = NA, price = NA)
# S3 method for default
FixedRateBondPriceByYield( settlementDays=1, yield, faceAmount=100, 
                                 effectiveDate, maturityDate,
                                 period, calendar="UnitedStates/GovernmentBond", 
                                 rates, dayCounter=2,
                                 businessDayConvention=0, compound = 0, redemption=100, 
                                 issueDate)
# S3 method for default
FixedRateBondYield( settlementDays=1, price, faceAmount=100, 
                                 effectiveDate, maturityDate,
                                 period, calendar="UnitedStates/GovernmentBond", 
                                 rates, dayCounter=2,
                                 businessDayConvention=0, 
                                 compound = 0, redemption=100, 
                                 issueDate)

Value

The FixedRateBond function returns an object of class

FixedRateBond (which inherits from class

Bond). It contains a list with the following components:

NPV

net present value of the bond

cleanPrice

clean price of the bond

dirtyPrice

dirty price of the bond

accruedAmount

accrued amount of the bond

yield

yield of the bond

duration

the duration of the bond

settlementDate

the actual settlement date used for the bond

cashFlows

cash flows of the bond

The FixedRateBondPriceByYield function returns an object of class

FixedRateBondPriceByYield (which inherits from class

Bond). It contains a list with the following components:

price

price of the bond

The FixedRateBondYield function returns an object of class

FixedRateBondYield (which inherits from class

Bond). It contains a list with the following components:

yield

yield of the bond

Arguments

bond

(Optional) bond parameters, a named list whose elements are:

settlementDays	(Optional) a double, settlement days.
	Default value is 1.
faceAmount	(Optional) a double, face amount of the bond.
	Default value is 100.
dayCounter	(Optional) a number or string,
	day counter convention. Defaults to 'Thirty360'
issueDate	(Optional) a Date, the bond's issue date
	Defaults to QuantLib default.
paymentConvention	(Optional) a number or string, the bond
	payment convention.
	Defaults to QuantLib default.
redemption	(Optional) a double, the redemption amount.
	Defaults to QuantLib default (100).
paymentCalendar	(Optional) a string, the name of the calendar.
	Defaults to QuantLib default.
exCouponPeriod	(Optional) a number, the number of days when
	the coupon goes ex relative to the coupon date.
	Defaults to QuantLib default.
exCouponCalendar	(Optional) a string, the name of the
	ex-coupon calendar.
	Defaults to QuantLib default.
exCouponConvention	(Optional) a number or string, the coupon
	payment convention.
	Defaults to QuantLib default.
exCouponEndOfMonth	(Optional) 1 or 0, use End of Month rule for
	ex-coupon dates. Defaults to 0 (false).

rates

a numeric vector, bond's coupon rates

schedule

(Optional) a named list, QuantLib's parameters of the bond's schedule.

effectiveDate	a Date, when the schedule becomes effective.
maturityDate	a Date, when the schedule matures.
period	(Optional) a number or string, the frequency of
	the schedule. Default value is 'Semiannual'.
calendar	(Optional) a string, the calendar name.
	Defaults to 'TARGET'
businessDayConvention	(Optional) a number or string, the
	day convention to use.
	Defaults to 'Following'.
terminationDateConvention	(Optional) a number or string, the
	day convention to use for the terminal date.
	Defaults to 'Following'.
dateGeneration	(Optional) a number or string, the
	date generation rule.
	Defaults to 'Backward'.
endOfMonth	(Optional) 1 or 0, use End of Month rule for
	schedule dates. Defaults to 0 (false).

See example below.

calc

(Optional) a named list, QuantLib's parameters for calculations.

dayCounter	(Optional) a number or string, day counter
	convention. Defaults to 'ActualActual.ISMA'
compounding	a string, what kind of compounding to use.
	Defaults to 'Compounded'
freq	(Optional) a number or string, the frequency
	to use. Default value is 'Annual'.
durationType	(Optional) a number or string, the type of
	duration to calculate. Defaults to 'Simple'
accuracy	(Optional) a number, the accuracy required.
	Defaults to 1.0e-8.
maxEvaluations	(Optional) a number, max number of iterations.
	Defaults to 100.

discountCurve

Can be one of the following:

a DiscountCurve	a object of DiscountCurve class
	For more detail, see example or
	the discountCurve function
A 2 items list	specifies a flat curve in two
	values "todayDate" and "rate"
A 3 items list	specifies three values to construct a
	DiscountCurve object, "params" ,
	"tsQuotes", "times".
	For more detail, see example or
	the discountCurve function

yield

yield of the bond

price

clean price of the bond

settlementDays

an integer, 1 for T+1, 2 for T+2, etc...

effectiveDate

bond's effective date

maturityDate

bond's maturity date

period

frequency of events,0=NoFrequency, 1=Once, 2=Annual, 3=Semiannual, 4=EveryFourthMonth, 5=Quarterly, 6=Bimonthly ,7=Monthly ,8=EveryFourthWeek,9=Biweekly, 10=Weekly, 11=Daily. For more information, see QuantLib's Frequency class

calendar

Business Calendar. Either us or uk

faceAmount

face amount of the bond

businessDayConvention

convention used to adjust a date in case it is not a valid business day. See quantlib for more detail. 0 = Following, 1 = ModifiedFollowing, 2 = Preceding, 3 = ModifiedPreceding, other = Unadjusted

dayCounter

day count convention. 0 = Actual360(), 1 = Actual365Fixed(), 2 = ActualActual(), 3 = Business252(), 4 = OneDayCounter(), 5 = SimpleDayCounter(), all other = Thirty360(). For more information, see QuantLib's DayCounter class

compound

compounding type. 0=Simple, 1=Compounded, 2=Continuous, all other=SimpleThenCompounded. See QuantLib's Compound class

redemption

redemption when the bond expires

issueDate

date the bond is issued

Author

Khanh Nguyen for the inplementation; Dirk Eddelbuettel for the R interface; the QuantLib Group for QuantLib

Details

A discount curve is built to calculate the bond value.

Please see any decent Finance textbook for background reading, and the QuantLib documentation for details on the QuantLib implementation.

References

https://www.quantlib.org/ for details on QuantLib.

Examples

#Simple call with a flat curve
bond <- list(settlementDays=1,
             issueDate=as.Date("2004-11-30"),
             faceAmount=100,
             dayCounter='Thirty360',
             paymentConvention='Unadjusted')
schedule <- list(effectiveDate=as.Date("2004-11-30"),
                 maturityDate=as.Date("2008-11-30"),
                 period='Semiannual',
                 calendar='UnitedStates/GovernmentBond',
                 businessDayConvention='Unadjusted',
                 terminationDateConvention='Unadjusted',
                 dateGeneration='Forward',
                 endOfMonth=1)
calc=list(dayCounter='Actual360',
          compounding='Compounded',
          freq='Annual',
          durationType='Modified')
coupon.rate <- c(0.02875)
                       
params <- list(tradeDate=as.Date('2002-2-15'),
               settleDate=as.Date('2002-2-19'),
               dt=.25,
               interpWhat="discount",
               interpHow="loglinear")
setEvaluationDate(as.Date("2004-11-22"))

discountCurve.flat <- DiscountCurve(params, list(flat=0.05))
FixedRateBond(bond,
              coupon.rate,
              schedule,
              calc,
              discountCurve=discountCurve.flat)


#Same bond with a discount curve constructed from market quotes
tsQuotes <- list(d1w  =0.0382,
                 d1m  =0.0372,
                 fut1=96.2875,
                 fut2=96.7875,
                 fut3=96.9875,
                 fut4=96.6875,
                 fut5=96.4875,
                 fut6=96.3875,
                 fut7=96.2875,
                 fut8=96.0875,
                 s3y  =0.0398,
                 s5y  =0.0443,
                 s10y =0.05165,
                 s15y =0.055175)
tsQuotes <- list("flat" = 0.02)		## While discount curve code is buggy

discountCurve <- DiscountCurve(params, tsQuotes)
FixedRateBond(bond,
              coupon.rate,
              schedule,
              calc,
              discountCurve=discountCurve)

#Same bond calculated from yield rather than from the discount curve
yield <- 0.02
FixedRateBond(bond,
              coupon.rate,
              schedule,
              calc,
              yield=yield)


#same example with clean price
price <- 103.31
FixedRateBond(bond,
              coupon.rate,
              schedule,
              calc,
              price = price)

#example with default calc parameter
FixedRateBond(bond,
              coupon.rate,
              schedule,
              discountCurve=discountCurve)
              
#example with default calc and schedule parameters
schedule <- list(effectiveDate=as.Date("2004-11-30"),
                 maturityDate=as.Date("2008-11-30"))
FixedRateBond(bond,
              coupon.rate,
              schedule,
              discountCurve=discountCurve)

#example with default calc, schedule and bond parameters
FixedRateBond(,
              coupon.rate,
              schedule,
              discountCurve=discountCurve)

FixedRateBondPriceByYield(,0.0307, 100000, as.Date("2004-11-30"),
                          as.Date("2008-11-30"), 3, , c(0.02875),
                          , , , ,as.Date("2004-11-30"))

FixedRateBondYield(,90, 100000, as.Date("2004-11-30"), as.Date("2008-11-30"),
                   3, , c(0.02875), , , , ,as.Date("2004-11-30"))