Main Content

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 a mapping of function-based instrument pricing to the object-based instrument pricing, see:

Related Topics