Main Content

finportfolio

Create a finportfolio object

Since R2020a

expand all in page

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.

example

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

example

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

example

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.

example

Input Arguments

expand all

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

Data Types: object

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

Data Types: object

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

Properties

expand all

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

Data Types: struct

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

Data Types: struct

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

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

Data Types: double

Object Functions

pricePortfolioCompute price and sensitivities for portfolio of instruments
addInstrumentAdd instrument to portfolio of instruments
removeInstrumentRemove instrument from portfolio of instruments
setPricerSet pricer for finportfolio object

Examples

collapse all

Open Live Script

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: [10x1 datetime]
                Rates: [10x1 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: [1x1 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: [1x1 ratecurve]
            Model: [1x1 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: [2x1 fininstrument.FinInstrument]
        Pricers: [2x1 finpricer.FinPricer]
    PricerIndex: [2x1 double]
       Quantity: [2x1 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
Open Live Script

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: [4x1 datetime]
                Rates: [4x1 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: [2x1 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: [1x1 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: [1x1 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: [2x1 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: [2x1 datetime]
                    PutDates: [0x1 datetime]
                CallSchedule: [2x1 timetable]
                 PutSchedule: [0x0 timetable]
           CallExerciseStyle: "american"
            PutExerciseStyle: [0x0 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: [1x1 struct]
        TreeDates: [4x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 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: [4x1 fininstrument.FinInstrument]
        Pricers: [1x1 finpricer.irtree.HWBKTree]
    PricerIndex: [4x1 double]
       Quantity: [4x1 double]

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

myportfolio = addInstrument(myportfolio,CallableBond,HWTreePricer,1)
myportfolio = 
  finportfolio with properties:

    Instruments: [5x1 fininstrument.FinInstrument]
        Pricers: [1x1 finpricer.irtree.HWBKTree]
    PricerIndex: [5x1 double]
       Quantity: [5x1 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
Open Live Script

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: [10x1 datetime]
                Rates: [10x1 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: [1x1 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: [1x1 ratecurve]
            Model: [1x1 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: [6x1 fininstrument.FinInstrument]
        Pricers: [6x1 finpricer.FinPricer]
    PricerIndex: [6x1 double]
       Quantity: [6x1 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

See Also

Functions

Topics