Mapping Financial Instruments Toolbox Functions to Object-Based Framework for Instruments, Models, and Pricers

Financial Instruments Toolbox™ allows you to use either a function-based framework or an alternative object-based framework to price financial instruments.

In the function-based framework, a typical workflow to price a bond with embedded options is as follows.

  1. Create a RateSpec instrument using intenvset.

    % Zero Data
Settle = datetime(2018,9,15);
Type = "zero";
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
Compounding = -1;
Basis = 1;

% Instrument parameters
Maturity = datetime(2024,9,15);
CouponRate = 0.035;
Strike = 100;
ExerciseDates = datetime(2022,9,15);
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'});
Period = 1;

% HW Parameters
Vol = 0.01;
Alpha = 0.1;
TreeDates = Settle + calyears(1:10);

RateSpec = intenvset('Compounding', Compounding,'StartDates', Settle,...
    'EndDates', ZeroDates,'Rates', ZeroRates,'Basis',Basis);

  2. Create a Hull-White tree object using hwvolspec, hwtimespec, and hwtree.

    HWVolSpec = hwvolspec(Settle, TreeDates, Vol,TreeDates, Alpha);
HWTimeSpec = hwtimespec(Settle, TreeDates, 1);
HWTree = hwtree(HWVolSpec, RateSpec, HWTimeSpec);
OldPrice = optembndbyhw(HWTree,CouponRate,Settle,Maturity,'call',Strike,ExerciseDates,'Period',Period)

  3. Price the bond with embedded options using an Hull-White interest-rate tree with optembndbyhw.

    OldPrice = optembndbyhw(HWTree,CouponRate,Settle,Maturity,'call',Strike,ExerciseDates,'Period',Period)

    OldPrice =

  109.4814

By contrast, in the Financial Instruments Toolbox object-based workflow, you price an instrument using instrument, model, and pricer objects:

  1. Create an OptionEmbeddedFixedBond instrument using OptionEmbeddedFixedBond.

    % Zero Data
Settle = datetime(2018,9,15);
Type = "zero";
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
Compounding = -1;
Basis = 1;

% Instrument parameters
Maturity = datetime(2024,9,15);
CouponRate = 0.035;
Strike = 100;
ExerciseDates = datetime(2022,9,15);
CallSchedule =  timetable(ExerciseDates,Strike,'VariableNames',{'Strike Schedule'});
Period = 1;

% HW Parameters
Vol = 0.01;
Alpha = 0.1;
TreeDates = Settle + calyears(1:10);

CallableBond = fininstrument("OptionEmbeddedFixedBond", "Maturity",Maturity,...
    'CouponRate',CouponRate,'Period',Period, ...
    'CallSchedule',CallSchedule,'Name',"CallableBond",'Basis',Basis);

  2. Create a ratecurve object using ratecurve.

    myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates,'Basis',Basis);

  3. Create a HullWhite model object using HullWhite.

    HWModel = finmodel("HullWhite","Alpha",Alpha,"Sigma",Vol);

  4. Create an IRTree pricer object using IRTree.

    HWPricer = finpricer("IRTree",'Model',HWModel,'DiscountCurve',myRC,'TreeDates',TreeDates');

  5. Price the bond instrument using price.

    NewPrice = price(HWPricer, CallableBond)
    NewPrice =

  109.4814

Note

The function-based and object-based workflows can return different instrument prices even if you use the same data. The difference is because the existing Financial Instruments Toolbox functions internally use datetime and the object-based framework use yearfrac for date handling. For more information, see Difference Between yearfrac and date2time.

For a mapping of function-based instrument pricing to the object-based instrument pricing, see:

See Also

Topics