CallableBond: CallableBond evaluation

Description Usage Arguments Details Value Note Author(s) References Examples

View source: R/bond.R

Description

The CallableBond function sets up and evaluates a callable fixed rate bond using Hull-White model and a TreeCallableFixedBondEngine pricing engine. For more detail, see the source codes in quantlib's example folder, Examples/CallableBond/CallableBond.cpp

Usage

1
2
## Default S3 method:
CallableBond(bondparams, hullWhite, coupon, dateparams)

Arguments

bondparams

a named list whose elements are:

issueDate a Date, the bond's issue date
maturityDate a Date, the bond's maturity date
faceAmount (Optional) a double, face amount of the bond.
Default value is 100.
redemption (Optional) a double, percentage of the initial face
amount that will be returned at maturity date.
Default value is 100.
callSch (Optional) a data frame whose columns are "Price",
"Type" and "Date" corresponding to QuantLib's
CallabilitySchedule. Defaule is an empty frame, or no callability.
hullWhite

a named list whose elements are parameters needed to set up a HullWhite pricing engine in QuantLib:

term a double, to set up a flat rate yield term structure
alpha a double, Hull-White model's alpha value
sigma a double, Hull-White model's sigma value
gridIntervals. a double, time intervals parameter to
set up the TreeCallableFixedBondEngine

Currently, the codes only support a flat rate yield term structure. For more detail, see QuantLib's doc on HullWhite and TreeCallableFixedBondEngine.

coupon

a numeric vector of coupon rates

dateparams

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

settlementDays (Optional) a double, settlement days.
Default value is 1.
calendar (Optional) a string, either 'us' or 'uk'
corresponding to US Goverment Bond
calendar and UK Exchange calendar.
Default value is 'us'.
dayCounter (Optional) a number or string,
day counter convention.
See Enum. Default value is 'Thirty360'
period (Optional) a number or string,
interest compounding interval. See Enum.
Default value is 'Semiannual'.
businessDayConvention (Optional) a number or string,
business day convention.
See Enum. Default value is 'Following'.
terminationDateConvention (Optional) a number or string
termination day convention.
See Enum. Default value is'Following'.

See example below.

Details

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

Value

The CallableBond function returns an object of class CallableBond (which inherits from class Bond). It contains a list with the following components:

NPV

net present value of the bond

cleanPrice

price price of the bond

dirtyPrice

dirty price of the bond

accruedAmount

accrued amount of the bond

yield

yield of the bond

cashFlows

cash flows of the bond

Note

The interface might change in future release as QuantLib stabilises its own API.

Author(s)

Khanh Nguyen knguyen@cs.umb.edu for the inplementation; Dirk Eddelbuettel edd@debian.org for the R interface; the QuantLib Group for QuantLib

References

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
#set-up a HullWhite according to example from QuantLib
HullWhite <- list(term = 0.055, alpha = 0.03, sigma = 0.01, gridIntervals = 40)

#callability schedule dataframe
Price <- rep(as.double(100),24)
Type <- rep(as.character("C"), 24)
Date <- seq(as.Date("2006-09-15"), by = '3 months', length = 24)
callSch <- data.frame(Price, Type, Date)
callSch$Type <- as.character(callSch$Type)

bondparams <- list(faceAmount=100, issueDate = as.Date("2004-09-16"),
                   maturityDate=as.Date("2012-09-16"), redemption=100,
                   callSch = callSch)
dateparams <- list(settlementDays=3, calendar="UnitedStates/GovernmentBond", 
                   dayCounter = "ActualActual", 
                   period="Quarterly", 
                   businessDayConvention = "Unadjusted", 
                   terminationDateConvention= "Unadjusted")
coupon <- c(0.0465)
setEvaluationDate(as.Date("2004-11-22"))

CallableBond(bondparams, HullWhite, coupon, dateparams)
#examples using default values
CallableBond(bondparams, HullWhite, coupon)
dateparams <- list(period="Quarterly", 
                   businessDayConvention = "Unadjusted", 
                   terminationDateConvention= "Unadjusted")
CallableBond(bondparams, HullWhite, coupon, dateparams)

bondparams <- list(issueDate = as.Date("2004-09-16"),
                   maturityDate=as.Date("2012-09-16"))
CallableBond(bondparams, HullWhite, coupon, dateparams)

Example output

[1] TRUE
Concise summary of valuation for CallableBond 
 Net present value :  92.58479 
       clean price :  91.683 
       dirty price :  92.585 
    accrued coupon :  0.90205 
             yield :  0.059916 
        cash flows : 
       Date   Amount
 2004-12-16   1.1561
 2005-03-16   1.1460
 2005-06-16   1.1721
 2005-09-16   1.1721
 2005-12-16   1.1593
 2006-03-16   1.1466
 2006-06-16   1.1721
 2006-09-16   1.1721
 2006-12-16   1.1593
 2007-03-16   1.1466
 2007-06-16   1.1721
 2007-09-16   1.1721
 2007-12-16   1.1593
 2008-03-16   1.1567
 2008-06-16   1.1689
 2008-09-16   1.1689
 2008-12-16   1.1561
 2009-03-16   1.1460
 2009-06-16   1.1721
 2009-09-16   1.1721
 2009-12-16   1.1593
 2010-03-16   1.1466
 2010-06-16   1.1721
 2010-09-16   1.1721
 2010-12-16   1.1593
 2011-03-16   1.1466
 2011-06-16   1.1721
 2011-09-16   1.1721
 2011-12-16   1.1593
 2012-03-16   1.1567
 2012-06-16   1.1689
 2012-09-16   1.1689
 2012-09-16 100.0000
Concise summary of valuation for CallableBond 
 Net present value :  92.11742 
       clean price :  91.252 
       dirty price :  92.117 
    accrued coupon :  0.86542 
             yield :  0.060709 
        cash flows : 
       Date   Amount
 2005-03-16   2.3250
 2005-09-16   2.3250
 2006-03-16   2.3250
 2006-09-18   2.3508
 2007-03-16   2.2992
 2007-09-17   2.3379
 2008-03-17   2.3250
 2008-09-16   2.3121
 2009-03-16   2.3250
 2009-09-16   2.3250
 2010-03-16   2.3250
 2010-09-16   2.3250
 2011-03-16   2.3250
 2011-09-16   2.3250
 2012-03-16   2.3250
 2012-09-17   2.3379
 2012-09-17 100.0000
Concise summary of valuation for CallableBond 
 Net present value :  92.59018 
       clean price :  91.725 
       dirty price :  92.59 
    accrued coupon :  0.86542 
             yield :  0.059833 
        cash flows : 
       Date   Amount
 2004-12-16   1.1625
 2005-03-16   1.1625
 2005-06-16   1.1625
 2005-09-16   1.1625
 2005-12-16   1.1625
 2006-03-16   1.1625
 2006-06-16   1.1625
 2006-09-16   1.1625
 2006-12-16   1.1625
 2007-03-16   1.1625
 2007-06-16   1.1625
 2007-09-16   1.1625
 2007-12-16   1.1625
 2008-03-16   1.1625
 2008-06-16   1.1625
 2008-09-16   1.1625
 2008-12-16   1.1625
 2009-03-16   1.1625
 2009-06-16   1.1625
 2009-09-16   1.1625
 2009-12-16   1.1625
 2010-03-16   1.1625
 2010-06-16   1.1625
 2010-09-16   1.1625
 2010-12-16   1.1625
 2011-03-16   1.1625
 2011-06-16   1.1625
 2011-09-16   1.1625
 2011-12-16   1.1625
 2012-03-16   1.1625
 2012-06-16   1.1625
 2012-09-16   1.1625
 2012-09-16 100.0000
Concise summary of valuation for CallableBond 
 Net present value :  93.7931 
       clean price :  92.928 
       dirty price :  93.793 
    accrued coupon :  0.86542 
             yield :  0.05781 
        cash flows : 
       Date   Amount
 2004-12-16   1.1625
 2005-03-16   1.1625
 2005-06-16   1.1625
 2005-09-16   1.1625
 2005-12-16   1.1625
 2006-03-16   1.1625
 2006-06-16   1.1625
 2006-09-16   1.1625
 2006-12-16   1.1625
 2007-03-16   1.1625
 2007-06-16   1.1625
 2007-09-16   1.1625
 2007-12-16   1.1625
 2008-03-16   1.1625
 2008-06-16   1.1625
 2008-09-16   1.1625
 2008-12-16   1.1625
 2009-03-16   1.1625
 2009-06-16   1.1625
 2009-09-16   1.1625
 2009-12-16   1.1625
 2010-03-16   1.1625
 2010-06-16   1.1625
 2010-09-16   1.1625
 2010-12-16   1.1625
 2011-03-16   1.1625
 2011-06-16   1.1625
 2011-09-16   1.1625
 2011-12-16   1.1625
 2012-03-16   1.1625
 2012-06-16   1.1625
 2012-09-16   1.1625
 2012-09-16 100.0000

RQuantLib documentation built on Oct. 6, 2021, 5:06 p.m.