finportfolio

Create a finportfolio object

Description

Create a finportfolio object for a collection of instrument objects.

After creating instruments, models, and pricer objects, use finportfolio to create a finportfolio object for a collection of instruments. For more detailed information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available instruments, models, and pricing methods, see Choose Instruments, Models, and Pricers.

Creation

Syntax

finportfolio_obj = finportfolio

finportfolio_obj = finportfolio(inInstruments)

finportfolio_obj = finportfolio(inInstruments,inPricers)

finportfolio_obj = finportfolio(___,inQuant)

Description

finportfolio_obj = finportfolio creates an empty finportfolio object.

finportfolio_obj = finportfolio(inInstruments) creates a finportfolio object containing the instrument objects inInstruments.

finportfolio_obj = finportfolio(inInstruments,inPricers) creates a finportfolio object containing the instrument objects inInstruments and the pricer objects inPricers.

finportfolio_obj = finportfolio(___,inQuant) optionally sets the inQuant property which specifies the number of instruments. Use this syntax with any of the input argument combinations in previous syntaxes to set the properties for the finportfolio object. For example, finportfolio_obj = finportfolio([CapObj,FloorObj,SwaptionObj],[BlackPricerObj,NormalPricerObj,SabrPricerObj]) creates a finportfolio object that contains instrument and pricer objects.

Input Arguments

inInstruments — Instrument objects in the portfolio

scalar Instrument object | array of Instrument objects

Instrument objects in the portfolio, specified as a scalar Instrument object or an array of Instrument objects.

Data Types: object

inPricers — Pricer objects in the portfolio

scalar Pricer object | array of Pricer objects

Pricer objects in the portfolio, specified as a scalar Pricer object or an array of Pricer objects.

Data Types: object

inQuant — Number of instruments

positive or negative numeric | array of positive or negative numerics

Number of instruments, specified as a scalar numeric or an NINST-by-1 array of numeric values. Use a positive value for long positions and a negative value for short positions.

Data Types: double

Output Arguments

finportfolio_obj — Collection of instrument objects

finportfolio object

Collection of instrument objects, returned as a finportfolio object.

Properties

Instruments — Instrument objects in the portfolio

scalar instrument object | array of instrument objects

Instrument objects in the portfolio, returned as a scalar instrument object or an array of instrument objects.

Data Types: struct

Pricers — Pricer objects in the portfolio

scalar pricer object | array of pricer objects

Pricer objects in the portfolio, returned as a scalar pricer object or an array of pricer objects.

Data Types: struct

PricerIndex — Mapping of instrument objects to pricer objects in the portfolio

Read-only: numeric

This property is read-only.

Mapping of instrument objects to pricer objects in the portfolio, returned as numeric.

PricerIndex has a length equal to the number of instrument objects in the finportfolio object and stores an index of which pricer is used for each instrument object.

Data Types: struct

Quantity — Number of instruments

numeric

Number of instruments, returned as a scalar numeric or numeric array.

Data Types: double

Object Functions

pricePortfolio	Compute price and sensitivities for portfolio of instruments
addInstrument	Add instrument to portfolio of instruments
removeInstrument	Remove instrument from portfolio of instruments
setPricer	Set pricer for finportfolio object

Examples

Price Portfolio of Heterogeneous Instruments

Use finportfolio and pricePortfolio to create and price a portfolio containing a FixedBond instrument and an American Vanilla option instrument.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",'Maturity',datetime(2022,9,15),'CouponRate',0.05,'Name',"fixed_bond")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 2
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2022
                        Name: "fixed_bond"

Create ratecurve Object

Create a ratecurve object using ratecurve.

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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Discount Pricer Object for FixedBond Instrument

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

FBPricer = finpricer("Discount",'DiscountCurve',myRC)

FBPricer = 
  Discount with properties:

    DiscountCurve: [1×1 ratecurve]

Create Vanilla Instrument Object

Use fininstrument to create an American Vanilla instrument object.

Maturity = datetime(2023,9,15);
AmericanOpt = fininstrument("Vanilla",'ExerciseDate',Maturity,'Strike',120,'ExerciseStyle',"american",'Name',"vanilla_option")

AmericanOpt = 
  Vanilla with properties:

       OptionType: "call"
    ExerciseStyle: "american"
     ExerciseDate: 15-Sep-2023
           Strike: 120
             Name: "vanilla_option"

Create BlackScholes Model Object for Vanilla Instrument

Use finmodel to create a BlackScholes model object.

BSModel = finmodel("BlackScholes",'Volatility',0.12)

BSModel = 
  BlackScholes with properties:

     Volatility: 0.1200
    Correlation: 1

Create BjerksundStensland Pricer Object for Vanilla Instrument

Use finpricer to create an analytic pricer object for the BjerksundStensland pricing method and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

BJSPricer = finpricer("analytic",'Model',BSModel,'DiscountCurve',myRC,'SpotPrice',100,'DividendValue',.02,'PricingMethod',"BjerksundStensland")

BJSPricer = 
  BjerksundStensland with properties:

    DiscountCurve: [1×1 ratecurve]
            Model: [1×1 finmodel.BlackScholes]
        SpotPrice: 100
    DividendValue: 0.0200
     DividendType: "continuous"

Add the Instruments to a finportfolio Object

Create a finportfolio object using finportfolio and add the two instruments with their associated pricers to the portfolio.

f1 = finportfolio([AmericanOpt,FixB],[BJSPricer,FBPricer])

f1 = 
  finportfolio with properties:

    Instruments: [2×1 fininstrument.FinInstrument]
        Pricers: [2×1 finpricer.FinPricer]
    PricerIndex: [2×1 double]
       Quantity: [2×1 double]

Price Portfolio

Use pricePortfolio to compute the price and sensitivities for the portfolio and the instruments in the portfolio.

[PortPrice,InstPrice,PortSens,InstSens] = pricePortfolio(f1)

PortPrice = 
119.1665

InstPrice = 2×1

    3.1912
  115.9753

PortSens=1×8 table
    Price      DV01       Delta      Gamma      Lambda     Vega      Theta       Rho 
    ______    _______    _______    ________    ______    ______    ________    _____

    119.17    0.04295    0.23188    0.011522    7.2661    65.454    -0.81408    86.71

InstSens=2×8 table
                      Price      DV01       Delta      Gamma      Lambda     Vega      Theta       Rho 
                      ______    _______    _______    ________    ______    ______    ________    _____

    vanilla_option    3.1912        NaN    0.23188    0.011522    7.2661    65.454    -0.81408    86.71
    fixed_bond        115.98    0.04295        NaN         NaN       NaN       NaN         NaN      NaN

Price Portfolio of Bond and Bond Option Instruments

This example shows the workflow to create and price a portfolio of bond and bond option instruments. You can use finportfolio and pricePortfolio to price FixedBond, FixedBondOption, OptionEmbeddedFixedBond, and FloatBond instruments using an IRTree pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018, 1, 1);
 ZeroTimes = calyears(1:4)';
 ZeroRates = [0.035; 0.042147; 0.047345; 0.052707];
 ZeroDates = Settle + ZeroTimes;
 Compounding = 1;
 ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates, "Compounding",Compounding)

ZeroCurve = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: 1
                Basis: 0
                Dates: [4×1 datetime]
                Rates: [4×1 double]
               Settle: 01-Jan-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Bond and Option Instruments

Use fininstrument to create a FixedBond, FixedBondOption, OptionEmbeddedFixedBond, and FloatBond instrument objects.

CDates = datetime([2020,1,1 ; 2022,1,1]);
CRates = [.0425; .0750];
CouponRate = timetable(CDates,CRates);
Maturity = datetime(2022,1,1);
Period = 1;

% Vanilla FixedBond
VBond = fininstrument("FixedBond",'Maturity',Maturity,'CouponRate',0.0425,'Period',Period,'Name',"vanilla_fixed") 

VBond = 
  FixedBond with properties:

                  CouponRate: 0.0425
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2022
                        Name: "vanilla_fixed"

 % Stepped coupon bond
SBond = fininstrument("FixedBond",'Maturity',Maturity,'CouponRate',CouponRate,'Period',Period,'Name',"stepped_coupon_bond") 

SBond = 
  FixedBond with properties:

                  CouponRate: [2×1 timetable]
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2022
                        Name: "stepped_coupon_bond"

% FloatBond
Spread = 0;
Reset = 1;
Float = fininstrument("FloatBond",'Maturity',Maturity,'Spread',Spread,'Reset', Reset, ...
                      'ProjectionCurve',ZeroCurve,'Name',"floatbond")

Float = 
  FloatBond with properties:

                      Spread: 0
             ProjectionCurve: [1×1 ratecurve]
                 ResetOffset: 0
                       Reset: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
          LatestFloatingRate: NaN
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2022
                        Name: "floatbond"

% Call option
Strike = 100;
ExerciseDates = datetime(2020,1,1); 
OptionType ='call';
Period = 1;
CallOption = fininstrument("FixedBondOption",'Strike',Strike,'ExerciseDate',ExerciseDates, ...
                   'OptionType',OptionType,'ExerciseStyle',"american",'Bond', VBond,'Name',"fixed_bond_option")    

CallOption = 
  FixedBondOption with properties:

       OptionType: "call"
    ExerciseStyle: "american"
     ExerciseDate: 01-Jan-2020
           Strike: 100
             Bond: [1×1 fininstrument.FixedBond]
             Name: "fixed_bond_option"

% Option for embedded bond (callable bond)
CDates = datetime([2020,1,1 ; 2022,1,1]);
CRates = [.0425; .0750];
CouponRate = timetable(CDates,CRates);
StrikeOE = [100; 100];
ExerciseDatesOE = [datetime(2020,1,1); datetime(2021,1,1)];
CallSchedule =  timetable(ExerciseDatesOE,StrikeOE,'VariableNames',{'Strike Schedule'}); 
CallableBond = fininstrument("OptionEmbeddedFixedBond", 'Maturity',Maturity, ...
                              'CouponRate',CouponRate,'Period', Period, ...
                              'CallSchedule',CallSchedule,'Name',"option_embedded_fixedbond")

CallableBond = 
  OptionEmbeddedFixedBond with properties:

                  CouponRate: [2×1 timetable]
                      Period: 1
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Jan-2022
                   CallDates: [2×1 datetime]
                    PutDates: [0×1 datetime]
                CallSchedule: [2×1 timetable]
                 PutSchedule: [0×0 timetable]
           CallExerciseStyle: "american"
            PutExerciseStyle: [0×0 string]
                        Name: "option_embedded_fixedbond"

Create HullWhite Model

Use finmodel to create a HullWhite model object.

VolCurve = 0.01;
AlphaCurve = 0.1;

HWModel = finmodel("hullwhite",'alpha',AlphaCurve,'sigma',VolCurve)

HWModel = 
  HullWhite with properties:

    Alpha: 0.1000
    Sigma: 0.0100

Create IRTree Pricer for HullWhite Model

Use finpricer to create an IRTree pricer object for a HullWhite model and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("IRTree",'Model',HWModel,'DiscountCurve',ZeroCurve,'TreeDates',ZeroDates)

HWTreePricer = 
  HWBKTree with properties:

             Tree: [1×1 struct]
        TreeDates: [4×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 ratecurve]

Create finportfolio Object and Add Callable Bond Instrument

Create a finportfolio object with the vanilla bond, stepped coupon bond, float bond, and the call option.

myportfolio = finportfolio([VBond,SBond,Float,CallOption],HWTreePricer, [1,2,2,1])

myportfolio = 
  finportfolio with properties:

    Instruments: [4×1 fininstrument.FinInstrument]
        Pricers: [1×1 finpricer.irtree.HWBKTree]
    PricerIndex: [4×1 double]
       Quantity: [4×1 double]

Use addInstrument to add the callable bond instrument to the existing portfolio.

myportfolio = addInstrument(myportfolio,CallableBond,HWTreePricer,1)

myportfolio = 
  finportfolio with properties:

    Instruments: [5×1 fininstrument.FinInstrument]
        Pricers: [1×1 finpricer.irtree.HWBKTree]
    PricerIndex: [5×1 double]
       Quantity: [5×1 double]

myportfolio.PricerIndex

ans = 5×1

     1
     1
     1
     1
     1

The PricerIndex property has a length equal to the length of instrument objects in the finportfolio object and stores the index of which pricer is used for each instrument object. In this case, because there is only one pricer, each instrument must use that pricer.

Price Portfolio

Use pricePortfolio to compute the price and sensitivities for the portfolio and the bond and option instruments in the portfolio.

format bank
[PortPrice,InstPrice,PortSens,InstSens] = pricePortfolio(myportfolio)

PortPrice = 
        600.55

InstPrice = 5×1

         96.59
        204.14
        200.00
          0.05
         99.77

PortSens=1×4 table
    Price      Delta       Gamma      Vega 
    ______    ________    _______    ______

    600.55    -1297.48    5759.65    -63.40

InstSens=5×4 table
                                 Price      Delta      Gamma      Vega 
                                 ______    _______    _______    ______

    vanilla_fixed                 96.59    -344.81    1603.49     -0.00
    stepped_coupon_bond          204.14    -725.96    3364.60      0.00
    floatbond                    200.00       0.00      -0.00     -0.00
    fixed_bond_option              0.05      -3.69      24.15     12.48
    option_embedded_fixedbond     99.77    -223.03     767.41    -75.88

Price Portfolio of Multiple Instances of Heterogeneous Instruments

Use finportfolio and pricePortfolio to create and price a portfolio containing three FixedBond instruments and three American Vanilla option instruments.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object for three Fixed Bond instruments.

FixB = fininstrument("FixedBond",'Maturity',datetime([2022,9,15 ; 2022,10,15 ; 2022,11,15]),'CouponRate',0.05,'Name',"fixed_bond")

FixB=3×1 FixedBond array with properties:
    CouponRate
    Period
    Basis
    EndMonthRule
    Principal
    DaycountAdjustedCashFlow
    BusinessDayConvention
    Holidays
    IssueDate
    FirstCouponDate
    LastCouponDate
    StartDate
    Maturity
    Name

Create ratecurve Object

Create a ratecurve object using ratecurve.

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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Discount Pricer Object for FixedBond Instruments

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

FBPricer = finpricer("Discount",'DiscountCurve',myRC)

FBPricer = 
  Discount with properties:

    DiscountCurve: [1×1 ratecurve]

Create Vanilla Instrument Object

Use fininstrument to create an American Vanilla instrument object for three Vanilla instruments.

Maturity = datetime([2023,9,15 ; 2023,10,15 ; 2023,11,15]);
AmericanOpt = fininstrument("Vanilla",'ExerciseDate',Maturity,'Strike',120,'ExerciseStyle',"american",'Name',"vanilla_option")

AmericanOpt=3×1 Vanilla array with properties:
    OptionType
    ExerciseStyle
    ExerciseDate
    Strike
    Name

Create BlackScholes Model Object for Vanilla Instruments

Use finmodel to create a BlackScholes model object.

BSModel = finmodel("BlackScholes",'Volatility',0.12)

BSModel = 
  BlackScholes with properties:

     Volatility: 0.1200
    Correlation: 1

Create BjerksundStensland Pricer Object for Vanilla Instruments

Use finpricer to create an analytic pricer object for the BjerksundStensland pricing method and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

BJSPricer = finpricer("analytic",'Model',BSModel,'DiscountCurve',myRC,'SpotPrice',100,'DividendValue',.02,'PricingMethod',"BjerksundStensland")

BJSPricer = 
  BjerksundStensland with properties:

    DiscountCurve: [1×1 ratecurve]
            Model: [1×1 finmodel.BlackScholes]
        SpotPrice: 100
    DividendValue: 0.0200
     DividendType: "continuous"

Add the Instruments to a finportfolio Object

Create a finportfolio object using finportfolio and add the six instruments with their associated pricers to the portfolio.

f1 = finportfolio([AmericanOpt;FixB],[BJSPricer, BJSPricer, BJSPricer, FBPricer, FBPricer, FBPricer])

f1 = 
  finportfolio with properties:

    Instruments: [6×1 fininstrument.FinInstrument]
        Pricers: [6×1 finpricer.FinPricer]
    PricerIndex: [6×1 double]
       Quantity: [6×1 double]

Price Portfolio

Use pricePortfolio to compute the price and sensitivities for the portfolio and the instruments in the portfolio.

[PortPrice,InstPrice,PortSens,InstSens] = pricePortfolio(f1)

PortPrice = 
358.4108

InstPrice = 6×1

    3.1912
    3.2579
    3.3272
  115.9753
  116.2114
  116.4478

PortSens=1×8 table
    Price      DV01       Delta      Gamma      Lambda     Vega      Theta      Rho  
    ______    _______    _______    ________    ______    ______    _______    ______

    358.41    0.13159    0.70286    0.034471    21.572    198.96    -2.4455    266.62

InstSens=6×8 table
                        Price       DV01       Delta      Gamma      Lambda     Vega      Theta       Rho  
                        ______    ________    _______    ________    ______    ______    ________    ______

    vanilla_option      3.1912         NaN    0.23188    0.011522    7.2661    65.454    -0.81408     86.71
    vanilla_option_1    3.2579         NaN    0.23427    0.011494    7.1907    66.314    -0.81353    88.842
    vanilla_option_2    3.3272         NaN    0.23672    0.011455    7.1147    67.196    -0.81784    91.063
    fixed_bond          115.98     0.04295        NaN         NaN       NaN       NaN         NaN       NaN
    fixed_bond_1        116.21    0.043858        NaN         NaN       NaN       NaN         NaN       NaN
    fixed_bond_2        116.45    0.044786        NaN         NaN       NaN       NaN         NaN       NaN

Version History

Introduced in R2020a